# 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`](/root/sourceserver/pbf/STEP_RECORD.md)
2. [`PROJECT_HANDOFF_2026-03-31.md`](/root/sourceserver/pbf/PROJECT_HANDOFF_2026-03-31.md)
3. [`NavSea_Delivery_Preflight_Audit_Spec.md`](/root/sourceserver/pbf/NavSea_Delivery_Preflight_Audit_Spec.md)

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

4. [`NavSea_Chart_Domain_Model_v1.md`](/root/sourceserver/pbf/NavSea_Chart_Domain_Model_v1.md)
5. [`NavSea_Semantic_Package_Overlay_Design.md`](/root/sourceserver/pbf/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`](/root/sourceserver/pbf/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`](/root/sourceserver/pbf/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`](/root/sourceserver/pbf/NavSea_Legacy_Field_Exit_Roadmap.md)
- [`NavSea_Delivery_Preflight_Audit_Spec.md`](/root/sourceserver/pbf/NavSea_Delivery_Preflight_Audit_Spec.md)
- [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md)

## Resume Checklist

At the start of a session:

1. Read [`STEP_RECORD.md`](/root/sourceserver/pbf/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`](/root/sourceserver/pbf/STEP_RECORD.md).
2. If the checkpoint is useful, commit it.
3. Keep unrelated dirty files out of the commit.