# PBF Project Handoff

Date: 2026-03-31
Project Root: `/root/sourceserver/pbf`
Primary Branch: `main`
Current Git Remote: `ssh://git@192.168.1.230: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`](/root/sourceserver/pbf/navsea_tile_builder.py)
- [`navsea_mapping_registry.py`](/root/sourceserver/pbf/navsea_mapping_registry.py)
- [`tasks/pbf/NavSea_tile_generation_pipeline_v2.md`](/root/sourceserver/pbf/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`](/root/sourceserver/pbf/NavSea_Legacy_Field_Exit_Roadmap.md)
- [`tasks/pbf/mappings/navsea_field_name_rules_v1.yaml`](/root/sourceserver/pbf/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`](/root/sourceserver/pbf/navsea_render_audit.py)
- [`NavSea_Delivery_Preflight_Audit_Spec.md`](/root/sourceserver/pbf/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`](/root/sourceserver/pbf/NavSea_Chart_Domain_Model_v1.md)
- [`NavSea_Semantic_Package_Overlay_Design.md`](/root/sourceserver/pbf/NavSea_Semantic_Package_Overlay_Design.md)

Core prototype code:

- [`src/Domain/chart_domain_model.py`](/root/sourceserver/pbf/src/Domain/chart_domain_model.py)
- [`src/Domain/build_chart_domain_tiles.py`](/root/sourceserver/pbf/src/Domain/build_chart_domain_tiles.py)
- [`src/Domain/navsea_domain_render_audit.py`](/root/sourceserver/pbf/src/Domain/navsea_domain_render_audit.py)
- [`src/Domain/navsea_mbtiles_validator.py`](/root/sourceserver/pbf/src/Domain/navsea_mbtiles_validator.py)
- [`src/Domain/package_domain_mbtiles.py`](/root/sourceserver/pbf/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@192.168.1.230: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`](/root/sourceserver/pbf/navsea_tile_builder.py)
- [`navsea_mapping_registry.py`](/root/sourceserver/pbf/navsea_mapping_registry.py)
- [`navsea_render_audit.py`](/root/sourceserver/pbf/navsea_render_audit.py)
- [`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)
- [`NavSea_Chart_Domain_Model_v1.md`](/root/sourceserver/pbf/NavSea_Chart_Domain_Model_v1.md)
- [`src/Domain/chart_domain_model.py`](/root/sourceserver/pbf/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.