127 lines
4.1 KiB
Markdown
127 lines
4.1 KiB
Markdown
# 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
|
|
|
|
The current working visual baseline is:
|
|
|
|
- `http://192.168.200.184/newpec/navsea-compare-karatsu-20nm.html`
|
|
|
|
Current target PBF line for visual restoration:
|
|
|
|
- `/home/wwwroot/pbf-delivery-karatsu-20nm`
|
|
|
|
Rules:
|
|
|
|
- use the page above as the primary visual regression surface
|
|
- do not switch the primary comparison URL casually
|
|
- do not create additional comparison pages unless explicitly requested
|
|
- prefer improving the current 20nm compare page over replacing it
|
|
- keep the click-pick inspection panel working on both left and right maps
|
|
- every visible compare-page revision must bump a human-readable version string on the page itself
|
|
- show that version near the reload button so visual review can confirm refresh state
|
|
- use the same version string as a cache-busting base for style / tile reloads
|
|
|
|
## 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)
|
|
|
|
### 5. Make Visual Revisions Traceable
|
|
|
|
When changing the primary compare page:
|
|
|
|
- bump the compare page version string
|
|
- display it near the reload button
|
|
- redeploy the HTML to `/mnt/sda1/www/newpec/navsea-compare-karatsu-20nm.html`
|
|
- if the visual change depends on style updates, redeploy the corresponding style JSON too
|
|
|
|
## 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.
|