pbf/AGENTS.md

AGENTS.md

Project Identity

Project root: /root/sourceserver/pbf

This repository is the NavSea PBF engineering, delivery, and audit workspace.

Primary Git remote:

• origin -> ssh://git@nas:2222/tei/pbf.git

First Files To Read

When resuming work in this project, read in this order:

1. STEP_RECORD.md
2. PROJECT_HANDOFF_2026-03-31.md
3. NavSea_Delivery_Preflight_Audit_Spec.md

If the task is specifically about Domain work, also read:

4. NavSea_Chart_Domain_Model_v1.md
5. NavSea_Semantic_Package_Overlay_Design.md

Current Reliable Audit Baseline

As of 2026-03-31:

• the most reliable current delivery audit baseline is Karatsu 10nm
• the trusted report is:
  • NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.md

Important limitation:

• Karatsu 20nm delivery is currently not object-auditable with the existing audit script because the delivery PBF no longer preserves enough trace-back anchor fields

Current Visual Regression Baseline

For the current goal of:

• removing Japanese fields from the PBF-facing path
• while keeping the rendered appearance as close as possible to the legacy chart

use this fixed comparison page as the only primary visual baseline:

• http://192.168.200.184/newpec/domain/navsea-compare-legacy-domain-compatible.html

The right side of that page is the current working target line.

Current target PBF line for this goal:

• pbf-domain-karatsu-10nm
• package sources:
  • domain_safety
  • domain_detail

Rules:

• do not create additional comparison pages for this migration unless explicitly requested
• do not switch the primary comparison URL casually
• treat the fixed page above as the stable regression surface for visual checking
• keep delivery-line experiments separate from this baseline unless the user explicitly redirects the work

Working Rules

1. Step Record Must Stay Fresh

Whenever there is meaningful progress, update:

• STEP_RECORD.md

This includes:

• after audits
• after code fixes
• after direction changes
• before stopping at a meaningful checkpoint

2. Commit Carefully

This repository is often in a dirty working state.

Rules:

• never stage unrelated modified files
• only commit files touched for the current task
• do not sweep untracked audit artifacts into commits unless that is the explicit goal

3. Preserve Audit Reality

Do not present a delivery audit as trustworthy unless object identity is still recoverable.

Current known-good object-level delivery audit pattern:

• use /home/wwwroot/pbf-delivery-karatsu-10nm
• use --fid-key 'thisMyWorld@2026'
• use --match-on-fid-only

4. Prefer Repo-Local Documentation

When deciding what to do next, prefer repo-local docs over memory.

Key references:

• NavSea_Legacy_Field_Exit_Roadmap.md
• NavSea_Delivery_Preflight_Audit_Spec.md
• STEP_RECORD.md

Resume Checklist

At the start of a session:

1. Read STEP_RECORD.md.
2. Check git status --short --branch.
3. Confirm git remote -v still points to nas.
4. Continue from the latest recorded next step.

At the end of a session:

1. Update STEP_RECORD.md.
2. If the checkpoint is useful, commit it.
3. Keep unrelated dirty files out of the commit.