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
4. NavSea_Audit_Logic_And_Evolution_2026-04-01.md

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

5. NavSea_Chart_Domain_Model_v1.md
6. 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

Audit Order

Current official order:

1. object preservation audit
2. render audit
3. AOI / visual audit

Do not treat a visual match as a pass if objects have already been dropped or wrongly merged.

Preferred current 20nm object-preservation entry point:

• navsea_object_preservation_audit.py
• current reports:
  • report/object_preservation_20nm/object_preservation_delivery_20nm.md
  • report/object_preservation_20nm/object_preservation_final_20nm.md

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

0. 文档语言统一

本项目默认文档语言为中文。

规则：

• STEP_RECORD.md 必须使用中文
• 所有新增输出文档必须使用中文
• 所有新增审计报告必须使用中文
• 不要再新增英文版交接、审计、总结文档，除非用户明确要求

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

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

6. Prefer Unified Strict Audit For 20nm Visual Gate

For the current 20nm visual baseline, prefer:

• navsea_strict_audit.py
• strict_audit_hotspots_20nm.json
• strict_audit_hotspots_20nm_pilot.json
• visual review page:
  • http://192.168.200.184/newpec/navsea-compare-karatsu-20nm.html

Even when 10nm delivery is rebuilt and audited:

• keep 20nm compare as the visual audit baseline
• use 10nm as the object-level backend audit reference only
• do not silently switch the user's visual review baseline away from 20nm compare

For small-scope image audit experiments:

• keep the style under test fixed to:
  • src/pbf/style.navsea-delivery-karatsu-10nm.json
• prefer the 3-hotspot pilot config first
• use full hotspot coverage only when pilot hotspots are no longer enough

This script combines:

• browser-rendered screenshot diff from the fixed compare page
• backend render audit summary from the current 20nm audit JSON

And now focuses on:

• small AOI hotspot crops that are chosen to calibrate backend audit blind spots
• not just one coarse full-screen diff number

Use it when you need one report that explains both:

• what the user really sees
• what the backend render audit currently says

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.