pbf/PROJECT_HANDOFF_2026-03-31.md

PBF Project Handoff

Date: 2026-03-31 Project Root: /root/sourceserver/pbf Primary Branch: main Current Git Remote: ssh://git@nas:2222/tei/pbf.git

1. Project Positioning

pbf is the NavSea chart tile engineering and delivery workspace.

This repository is no longer in early exploration. The core production path already exists:

• raw vector tile input
• database-backed semantic mapping
• delivery/engineering tile rebuilding
• style migration
• render audit
• Domain split-package prototype

The work now sits between late-stage prototype and pre-delivery convergence.

2. Main Workstreams

A. Delivery/Engineering Tile Pipeline

Core files:

• navsea_tile_builder.py
• navsea_mapping_registry.py
• tasks/pbf/NavSea_tile_generation_pipeline_v2.md

Current state:

• can read original PBF tiles
• can join database-backed mapping and rule context
• can emit NavSea delivery/engineering-oriented properties
• preserves geometry/extents
• already supports reversible NavSea FID handling

Assessment:

• this line is implemented and usable
• remaining work is mainly around semantic completion, audit closure, and delivery hardening

B. Legacy Field Exit / Standardization

Core docs:

• NavSea_Legacy_Field_Exit_Roadmap.md
• tasks/pbf/mappings/navsea_field_name_rules_v1.yaml

Latest committed stages on main:

• Stage 1: standardize delivery field names
• Stage 2: migrate styles to standardized layer names
• Stage 3: strip legacy Japanese delivery keys by default
• Stage 4.1: remove remaining Japanese delivery field keys

Assessment:

• first-round standardization is complete
• the project has started exiting direct dependence on old Japanese delivery keys
• however, the repository has not yet fully finished the roadmap target of a pure new-field style

Important nuance:

• the roadmap explicitly states that the project has "started" the exit but has not yet truly escaped the old field system
• a full exit still requires new-field-only styling plus equivalence audit closure

C. Render Audit / Delivery Gate

Core files:

• navsea_render_audit.py
• NavSea_Delivery_Preflight_Audit_Spec.md

Current state:

• object-level render observation comparison exists
• tile-instance-granularity comparison exists
• Markdown/JSON audit output exists
• style semantic special checks are defined

Assessment:

• audit automation is meaningful and already part of the engineering flow
• but delivery signoff is still not fully automated

Still not fully automated according to the spec:

• scene-window audit
• deployment consistency auto-check
• separate hard gates for navigation/fishing editions
• auto-judgement for pre-registered equivalent render expressions

D. Chart Domain / Split Package Prototype

Core docs:

• NavSea_Chart_Domain_Model_v1.md
• NavSea_Semantic_Package_Overlay_Design.md

Core prototype code:

• src/Domain/chart_domain_model.py
• src/Domain/build_chart_domain_tiles.py
• src/Domain/navsea_domain_render_audit.py
• src/Domain/navsea_mbtiles_validator.py
• src/Domain/package_domain_mbtiles.py

Current state:

• a semantic Domain model has been designed
• safety and detail package splitting has prototype code
• Domain-aware render audit has prototype code
• MBTiles packaging/validation has prototype code

Assessment:

• Domain work is beyond idea stage
• it is implemented as an isolated experimental line
• it is not yet the stabilized production path

3. Overall Progress Judgment

The project is approximately here:

1. The base engineering pipeline is already built.
2. Delivery field/layer standardization has finished its first major pass.
3. Full removal of legacy render-control dependency is not yet complete.
4. Domain split-package architecture is designed and prototyped, but not yet fully consolidated into the main delivery line.

Short version:

The repository is in a "usable engineering system, still converging toward final delivery architecture" stage.

4. Repository Status At Handoff

Observed on 2026-03-31:

• branch: main
• remote: origin -> ssh://git@nas:2222/tei/pbf.git
• local branch relation after remote sync: main aligned with origin/main at 94c8f45
• working tree is not clean

Important note:

• there are existing modified and untracked files in the workspace that were not created by this handoff commit
• they appear to include ongoing Domain work, audit outputs, style files, and roadmap documents
• this handoff commit intentionally does not bundle those pending changes

5. Known Risks

• The repo does not currently show a real automated test suite. Only task/docs are present; no proper test package was found.
• The working tree is already dirty, so any future commit should be staged carefully.
• Several important artifacts remain as uncommitted local work, which means current progress is not yet fully consolidated into committed branch history.
• Audit capability is present, but final release gating still depends on mandatory manual review for fixed sample areas.

6. Recommended Next Steps

Priority order:

1. Decide whether the current uncommitted Domain line should be curated and committed as a coherent feature batch.
2. Complete the "pure new-field style" milestone so the delivery style no longer directly reads legacy render-control keys.
3. Run and archive a fresh equivalence audit on the target delivery area, especially Karatsu 10nm / 20nm.
4. Separate "production-ready" docs and outputs from "working notes / generated reports" to reduce repo noise.
5. Add at least a minimal automated verification layer for builder/audit scripts.

7. Fast Orientation For The Next Maintainer

If taking over this repository, start from these files:

• navsea_tile_builder.py
• navsea_mapping_registry.py
• navsea_render_audit.py
• NavSea_Legacy_Field_Exit_Roadmap.md
• NavSea_Delivery_Preflight_Audit_Spec.md
• NavSea_Chart_Domain_Model_v1.md
• src/Domain/chart_domain_model.py

8. Handoff Intent

This handoff document is meant to preserve two truths at the same time:

• the project has real engineering depth already completed
• the project is not yet in a final "fully cleaned, fully closed, fully released" state

That distinction matters for any next commit, delivery decision, or branch cleanup.