diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0d242f6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,96 @@ +# 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 + +## 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. diff --git a/STEP_RECORD.md b/STEP_RECORD.md index aa5e183..4b13f7e 100644 --- a/STEP_RECORD.md +++ b/STEP_RECORD.md @@ -12,6 +12,11 @@ Remote: `ssh://git@nas:2222/tei/pbf.git` - 已补交接文档： - [`PROJECT_HANDOFF_2026-03-31.md`](/root/sourceserver/pbf/PROJECT_HANDOFF_2026-03-31.md) - [`GIT_REMOTE_SWITCH_TO_NAS_2026-03-31.md`](/root/sourceserver/pbf/GIT_REMOTE_SWITCH_TO_NAS_2026-03-31.md) +- 已补项目协作约定文件： + - [`AGENTS.md`](/root/sourceserver/pbf/AGENTS.md) + - [`codex/README.md`](/root/sourceserver/pbf/codex/README.md) + - [`codex/SESSION_START.md`](/root/sourceserver/pbf/codex/SESSION_START.md) + - [`codex/RESUME_PROMPT.md`](/root/sourceserver/pbf/codex/RESUME_PROMPT.md) - 已完成一次新的 delivery 审计，并确认哪条审计线可用 ## Latest Audit Status diff --git a/codex/README.md b/codex/README.md new file mode 100644 index 0000000..24efa4f --- /dev/null +++ b/codex/README.md @@ -0,0 +1,20 @@ +# Codex Project Notes + +This directory stores project-specific Codex working conventions. + +Use these files as the startup layer for future sessions in `pbf`. + +## Files + +- [`SESSION_START.md`](/root/sourceserver/pbf/codex/SESSION_START.md) + - what to read first when resuming work +- [`RESUME_PROMPT.md`](/root/sourceserver/pbf/codex/RESUME_PROMPT.md) + - a ready-to-use prompt for continuing the project + +## Core Rule + +If there has been meaningful progress, update: + +- [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md) + +That file is the current source of truth for "where we stopped last time." diff --git a/codex/RESUME_PROMPT.md b/codex/RESUME_PROMPT.md new file mode 100644 index 0000000..36d56cd --- /dev/null +++ b/codex/RESUME_PROMPT.md @@ -0,0 +1,5 @@ +# Resume Prompt + +Use this prompt to continue the project quickly: + +`继续处理 /root/sourceserver/pbf/STEP_RECORD.md 里记录的下一步，先读 STEP_RECORD.md 和 AGENTS.md，再从 Karatsu 10nm delivery 审计的 baseline / depth / navigation marks 三组问题开始修。` diff --git a/codex/SESSION_START.md b/codex/SESSION_START.md new file mode 100644 index 0000000..a5e7b6c --- /dev/null +++ b/codex/SESSION_START.md @@ -0,0 +1,47 @@ +# Session Start + +When opening this project again, do this first: + +1. Read [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md). +2. Read [`AGENTS.md`](/root/sourceserver/pbf/AGENTS.md). +3. Run: + +```bash +cd /root/sourceserver/pbf +git status --short --branch +git remote -v +sed -n '1,220p' STEP_RECORD.md +``` + +## Current Resume Target + +Unless a newer step record says otherwise, continue from: + +- `Karatsu 10nm delivery` audit follow-up +- priority groups: + - `baseline` + - `depth / bathymetry` + - `navigation marks` + +## Audit Reminder + +The current trusted delivery audit line is: + +```bash +.venv/bin/python navsea_render_audit.py \ + --audit-name navsea_original_vs_delivery_karatsu_10nm_20260331 \ + --comparison-label 'delivery版' \ + --fid-key 'thisMyWorld@2026' \ + --match-on-fid-only \ + --original-style /root/sourceserver/pbf/src/pbf/style.json \ + --engineering-style /root/sourceserver/pbf/src/pbf/style.navsea-delivery-karatsu-10nm.json \ + --original-tile-root /home/wwwroot/newpec/exported_auto/tile.mapple-on.jp__newpec-mvt-20260106__z___x___y_.pbf/tiles \ + --engineering-tile-root /home/wwwroot/pbf-delivery-karatsu-10nm \ + --report-md /root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.md \ + --report-json /root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.json \ + --skip-db-persist +``` + +## Stop Rule + +Before ending a work session, update [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md).