PlanForge

PlanForge transforms heterogeneous engineering sources into reviewed canonical knowledge and deterministically compiles that knowledge into CAD-oriented outputs. Model assistance interprets sources into candidate knowledge; it never approves facts, calculates final engineering poses, or writes final CAD output.

The implemented v1 workflow is preserved as a compatibility baseline. The normative M26 boundary and future roadmap are documented in Architecture and M26–M50 roadmap; M26 does not change the current CLI behavior.

The first release is intentionally pragmatic: an LLM builds and uses versioned knowledge packages, while a deterministic Go pipeline validates structured models and renders a DXF that opens in NanoCAD, FreeCAD, or LibreCAD.

Core idea

Manufacturer pre-installation documentation + CAD models
                |
                v
       Knowledge Builder
                |
                v
     Versioned Knowledge Package
                |
                +----------------------+
                                       |
Project sketch + customer requirements |
                |                      |
                v                      v
             Project Planner / LLM
                       |
                       v
          Canonical Engineering Model
                       |
                       v
             Deterministic Go pipeline
                       |
                       v
               DXF + report + model

MVP outcome

After all MVP milestones are completed, PlanForge shall:

1. Build a reviewed, versioned knowledge package from PIM, pre-installation documentation, and DWG/DXF source material.
2. Create a project from a room sketch or MagicPlan export and customer notes.
3. Generate engineering_model.yaml.
4. Validate the model before rendering.
5. Produce an ASCII DXF that opens in NanoCAD without repair.
6. Copy all final deliverables into the project outbox/.
7. Record assumptions, unresolved conflicts, source provenance, and validation results.

Technology

• Go for contracts, validation, orchestration, geometry primitives, rendering, and tests.
• LLM/Claude Code initially for documentation interpretation, semantic extraction, planning, annotation decisions, and review.
• YAML for reviewed persistent artifacts.
• Go structs for the in-memory model.
• DXF as the first CAD output format.

Repository layout

planforge/
├── AGENTS.md
├── PLANS.md
├── README.md
├── go.mod
├── cmd/planforge/
├── contracts/
├── customers/
│   └── <customer-id>/customer.yaml
├── evidence/
│   ├── blobs/sha256/
│   └── records/
├── internal/
├── knowledge/
├── projects/
├── docs/
├── plans/
├── tests/
├── .agents/skills/
└── outbox/

CLI

Available now:

planforge version
planforge knowledge validate knowledge/equipment/<package-id>/<version>
planforge project validate projects/<project-id>
planforge customer validate customers/<customer-id>
planforge customer list
planforge project list
planforge registry validate
planforge evidence add --file <source> --id <evidence-id> --category <category> --media-type <media-type> --authority <authority> --purpose <purpose> --origin <origin> --actor <actor> --method <method> --captured-at <RFC3339> --created-at <RFC3339>
planforge evidence validate <record-or-id>
planforge evidence verify <record-or-id>
planforge evidence list
planforge evidence audit
planforge audit validate
planforge revision create --project <project-id> --id <revision-id> --actor <actor> --reason <reason> --created-at <RFC3339> [--equipment-geometry <authority.yaml>]
planforge revision validate <project-id>
planforge revision list <project-id>
planforge revision show <project-id> <revision-id>
planforge revision current <project-id>
planforge revision set-current <project-id> <revision-id>
planforge revision compare <project-id> <left-revision-id> <right-revision-id>
planforge revision audit
planforge agent validate agent
planforge agent list
planforge workflow validate agent/workflows/source-drawing-understanding.yaml
planforge run validate agent/runs/synthetic-supervised-ingestion.yaml
planforge run list
planforge run show <run-id>
planforge run audit
planforge cognitive validate <session.yaml>
planforge cognitive show <session.yaml>
planforge cognitive compare <left.yaml> <right.yaml>
planforge cognitive audit [repository-root]
planforge cognitive run --session <created-session.yaml> --output <completed-session.yaml>
planforge cognitive model invoke --session <created-session.yaml> --response <fake-response.json> --output <completed-session.yaml>
planforge cognitive candidate review --session <session.yaml> --review-id <id> --decision <accept|reject|defer> --reviewer <human-id> --rationale <text> --reviewed-at <RFC3339> --output <review.yaml>
planforge cognitive candidate promote --session <session.yaml> --review <review.yaml> --output <directory>
planforge knowledge graph validate <graph.yaml>
planforge knowledge graph show <graph.yaml>
planforge knowledge graph compare <left.yaml> <right.yaml>
planforge knowledge graph audit <graph.yaml>
planforge knowledge compile-v2 <graph.yaml> --output <cpk-v2.yaml>
planforge knowledge validate-v2 <cpk-v2.yaml>
planforge knowledge compare-v2 <left.yaml> <right.yaml>
planforge knowledge audit-v2 --graph <graph.yaml> --cpk <cpk-v2.yaml>
planforge knowledge project-v2 graph-ingest --project <id> --id <graph-id> --revision <revision-id> --from-graph <graph.yaml>
planforge knowledge project-v2 compile --project <id> --graph <graph-id>
planforge knowledge project-v2 bind --project <id> --id <binding-id> --revision <revision-id> --graph <graph-id> --cpk <cpk-id>
planforge knowledge project-v2 audit --binding <project-id> <binding-id>
planforge drawing-source inspect <evidence-id> --output <inventory.yaml>
planforge drawing-source validate <inventory-or-observations.yaml>
planforge drawing-source observations validate <observations.yaml>
planforge drawing-source audit
planforge pim inspect <evidence-id> --output <inventory.yaml>
planforge pim validate <inventory-or-requirements.yaml>
planforge pim requirements validate <requirements.yaml>
planforge operator intent validate <intent.yaml>
planforge operator intent show <project-id> <intent-id>
planforge operator intent list <project-id>
planforge operator intent audit
planforge knowledge project validate <cpk.yaml>
planforge knowledge project list <project-id>
planforge knowledge project audit
planforge compile project --project <id> --revision <revision-id> --output projects/<id>/compilations/<compilation-id>
planforge compile project-v2 --project <id> --revision <revision-id> --binding <binding-id> --output projects/<id>/cpk-v2-compilations/<compilation-id>
planforge knowledge cutover-check --project <id> --revision <revision-id> [--binding <binding-id>] [--output <report.yaml>]
planforge compile validate projects/<id>/compilations/<compilation-id>
planforge compile validate-v2 projects/<id>/cpk-v2-compilations/<compilation-id>
planforge compile compare-v2 <v2-compilation> <legacy-compilation>
planforge compile audit
planforge geometry build --compilation projects/<id>/compilations/<compilation-id> --output projects/<id>/geometry/<geometry-build-id>
planforge geometry validate projects/<id>/geometry/<geometry-build-id>
planforge geometry audit
planforge geometry render-svg --scene projects/<id>/geometry/<geometry-build-id> --output /tmp/geometry-debug.svg
planforge compliance evaluate --scene projects/<id>/geometry/<geometry-build-id> --request projects/<id>/compliance/requests/<request>.yaml --output projects/<id>/compliance/<run-id>
planforge compliance validate projects/<id>/compliance/<run-id>
planforge compliance show projects/<id>/compliance/<run-id>
planforge compliance compare <left-run> <right-run>
planforge compliance audit
planforge modification plan --scene <geometry-dir> --compliance <compliance-dir> --request <request.yaml> --output projects/<id>/modifications/<plan-id>
planforge modification validate projects/<id>/modifications/<plan-id>
planforge modification show projects/<id>/modifications/<plan-id>
planforge modification compare <left-plan> <right-plan>
planforge modification audit
planforge project build <project-id> --revision <revision-id> [--knowledge-version v1|v2] --output projects/<id>/builds/<build-id>
planforge project build validate projects/<id>/builds/<build-id>
planforge project build show projects/<id>/builds/<build-id>
planforge project build compare <left-build> <right-build>
planforge project build audit
planforge drawing v2 build --build projects/<id>/builds/<build-id> --output projects/<id>/builds/<build-id>/drawing
planforge drawing v2 validate projects/<id>/builds/<build-id>/drawing
planforge drawing v2 show projects/<id>/builds/<build-id>/drawing
planforge drawing v2 compare <left-drawing> <right-drawing>
planforge drawing v2 audit
planforge cad exchange build --drawing <drawing-model.yaml> --state <current|proposed|unspecified> --output <bundle-directory>
planforge cad exchange validate <bundle-directory>
planforge cad exchange compare <bundle-a> <bundle-b>
planforge cad freecad build --input <cad-exchange-bundle> --output <directory>
planforge cad freecad validate <directory>
planforge cad freecad execute --input <cad-exchange-bundle> --fcstd <document.FCStd> --report <object-map.json> --freecad-cmd <FreeCADCmd>
planforge model validate projects/<project-id>/workspace/engineering_model.yaml
planforge layout intent validate projects/<project-id>/workspace/layout_intent.yaml
planforge layout solve projects/<project-id>
planforge layout validate projects/<project-id>/workspace/layout_result.yaml
planforge drawing build projects/<project-id>/workspace/proposed_engineering_model.yaml --output projects/<project-id>/workspace/drawing_model.yaml
planforge drawing validate projects/<project-id>/workspace/drawing_model.yaml
planforge render dxf projects/<project-id>/workspace/drawing_model.yaml --output projects/<project-id>/output/generated_layout.dxf
planforge dxf validate projects/<project-id>/output/generated_layout.dxf

M37 expands the opt-in CPK v2 downstream path with reviewed typed source contracts, room references, categorized requirements, active operator constraints, requirement frames, and existing metric relationships. The VAEC equivalence report classifies semantic equality separately from provenance-only differences; the legacy CPK v1 compiler remains the default.

M38 makes downstream selection explicit and auditable: v1 remains the default, v2 requires an immutable binding and the cpk-v2-cutover-policy/v1 readiness gate, and rollback is an explicit v1 rerun. Cutover rehearsal is read-only; there is no silent fallback or default switch.

M39 adds immutable project-knowledge-selection/v1 sidecars. A project without one remains on v1; VAEC rev-0005 is explicitly selected for CPK v2 with its M39 revision binding and accepted M38 known-difference classes. Historical rev-0004 remains the pre-cutover v1 state. Normal compile project and project build resolve that selection, while --knowledge-version v1 is a non-mutating explicit rollback. The selected compiled input is consumed by the ordinary geometry loader and its identities are recorded in the build manifest.

M40 adds an immutable, revision-pinned equipment geometry authority record. VAEC rev-0006 records the exact Revolution Maxima v1 authority resource and fingerprints, while preserving its current geometry_state: unavailable status. The project DXF equipment outlines remain visual/reference-only and cannot satisfy physical geometry requirements.

Drawing Model v2 review SVGs resolve approved compact external visual resources only at render time. They verify source and local-geometry digests, retain visual/reference authority, and include separate current, proposed, and comparison SVGs; they do not replace the v1 DXF path.

The universal FreeCAD adapter is an additive downstream backend: it reads only validated CAD Exchange v1, produces a deterministic preparation manifest and stable object map, then may execute its reusable Python materializer in FreeCAD. M29 freezes its v1 naming, grouping, initial visibility, metadata, native annotation, and dimension-presentation behavior against the VAEC acceptance fixture. FCStd bytes are runtime-dependent and are not claimed deterministic; the R12 DXF renderer remains directly downstream of Drawing Model v1:

M30 extends this compatibility path with optional primitive authority/review metadata and text rotation. CAD Exchange and FreeCAD preserve these supplied semantics; neither treats surviving geometry as an approval signal.

M31 adds a read-only cognitive runtime foundation. A versioned cognitive session instantiates a workflow as an auditable DAG over immutable artifact references, records bounded deterministic tool calls and provisional observations/proposals, and stops before review or canonical promotion.

M32 adds a provider-neutral supervised model boundary inside that session. A model is a probabilistic interpreter: it may extract or classify a referenced artifact into a strict candidate observation. The runtime records the request, provider/model, exact raw response and parsed candidate; deterministic validators enforce the schema and human review remains the authority boundary. Models do not control canonical truth, engineering approval, geometry, CAD, or compliance.

M33 adds the explicit governance boundary: a separate immutable human review decision may accept, reject, or defer a candidate. Only a valid human acceptance can make the bounded deterministic promotion eligible. The first promotion target is additive knowledge-artifact/v1 numeric millimetre observation content; CPK v1 is deliberately untouched because its legacy fingerprint includes review metadata.

Drawing Model ─────────────→ DXF
      ↓
CAD Exchange v1
      ↓
FreeCAD Adapter v1
      ↓
FreeCAD

The knowledge validator strictly decodes knowledge-package/v1, verifies evidence-file hashes and source provenance, and validates declared Equipment Object Model companion files. It does not import CAD geometry or create drawings.

The first real package is knowledge/equipment/revolution-maxima/v1. Its GE HealthCare Pre-Installation Manual evidence is preserved and remains in human review; its referenced Equipment Object Model defines reusable components and interfaces, not room placement. See its review.md before using it for a project. Project validation pins a package version and EOM object definition; model validation checks the CAD-independent Canonical Engineering Model (CEM).

Customer identity is strict customer/v1 metadata stored at customers/<customer-id>/customer.yaml. A project remains at its existing projects/<project-id>/ path, declares exactly one customer_id, and retains its customer map only as legacy site metadata. planforge registry validate checks global IDs, directory identities, and ownership deterministically.

Original project and equipment bytes may also be registered in the immutable content-addressed evidence store. evidence/blobs/sha256/ holds deduplicated bytes; evidence/records/ holds immutable source context. Existing project and package paths remain supported compatibility inputs. The evidence commands never parse DXF, PDF, PIM, or operator text.

Projects may hold immutable compatibility-state revisions at projects/<project-id>/revisions/<revision-id>/. Each revision contains a full project snapshot, structural change set, reproducibility build manifest, and immutable file fingerprints. revisions/index.yaml atomically selects the current valid revision. This is revision infrastructure only: Canonical Project Knowledge and operator-intent runtime remain deferred.

Layout Intent is the boundary between customer/site goals and exact placement. It is strict YAML authored from evidence; the deterministic Go solver generates, filters, scores, and selects candidates. It never reads customer prose and creates proposed—not approved—CEM placements. The Revolution Maxima scaffold remains unresolved because its room and authoritative EOM geometry are absent.

Drawing Model and DXF rendering are deterministic derivatives of validated CEM geometry or a reviewed multi-room site-model/v1. Geometry ingestion produces a strict candidate with source/page/entity provenance and human review before it can become a site model; neither pixel scaling nor unreviewed CAD scale is authoritative. The renderer uses conservative ASCII R12 entities and does not create or alter engineering placement.

planforge room ingest validate <ingestion-result.yaml>
planforge room build <ingestion-result.yaml> --output <site-model.yaml>
planforge room validate <site-model.yaml>
planforge room drawing build <site-model.yaml> --output <drawing-model.yaml>
planforge room readiness <ingestion-result.yaml>
planforge room build <ingestion-result.yaml> --capability room-outline-rendering --output <site-model.yaml>
planforge provisional validate <provisional-equipment-planning.yaml>
planforge project build projects/<project> --geometry-mode project-provisional --layout-mode supplied

An ingestion artifact may remain in_review while reviewed facts make a limited capability ready. The builder consumes only approved facts and carries the remainder as structured unresolved diagnostics.

Project-derived DXF equipment graphics use a strict provisional-planning contract. They remain visual references until a distinct collision-proxy review and never upgrade the pinned manufacturer EOM geometry.

drawing-model/v1 can also carry reviewed visual resources and transformed visual instances. This renders open, project-derived source linework and multiple visual components of one assembly without promoting the evidence to a collision footprint, service zone, or manufacturer-authoritative geometry.

Planned CLI target

planforge knowledge validate knowledge/equipment/revolution-maxima/v1
planforge project validate projects/revolution-maxima-site
planforge model validate projects/revolution-maxima-site/workspace/engineering_model.yaml
planforge render projects/example-ct-room
planforge build projects/example-ct-room

planforge build shall validate inputs, render the drawing, create the report, and copy deliverables to the project's outbox/.

Development sequence

Read, in order:

1. AGENTS.md
2. docs/ARCHITECTURE.md
3. docs/ROADMAP.md
4. docs/MVP_SCOPE.md
5. the active file under plans/active/
6. PLANS.md when creating or updating an execution plan

The roadmap is milestone-driven. Implement one milestone at a time, validate it, document it, and archive its execution plan before starting the next.