From 35264fb8175010e007ca70dfdce09b2dea6d778a Mon Sep 17 00:00:00 2001 From: James Sesler <124222483+TheAmericanMaker@users.noreply.github.com> Date: Tue, 21 Jul 2026 17:53:34 -0400 Subject: [PATCH] docs: launch forward synthesis experience --- docs.html | 44 ++++++++++++++++++++++++++--- features.html | 9 +++--- index.html | 27 ++++++++++++------ script.js | 8 ++++++ tests/upstream-consistency.test.mjs | 12 +++++++- 5 files changed, 83 insertions(+), 17 deletions(-) diff --git a/docs.html b/docs.html index 643454b..a1306d0 100644 --- a/docs.html +++ b/docs.html @@ -66,7 +66,8 @@

Copy one folder into any repository.

pipeline: workflow/pipeline.yaml # 5-phase pipeline: workflow/pipeline-defect-scan.yaml # 2-phase pipeline: workflow/pipeline-lite.yaml # 3-phase -pipeline: workflow/pipeline-architecture-only.yaml # 1-phase +pipeline: workflow/pipeline-architecture-only.yaml # 1-phase +pipeline: workflow/pipeline-synthesis.yaml # 4-phase forward synthesis (Pi/MCP only)
@@ -98,7 +99,7 @@

Slash commands, widgets, and tool gating.

# or, from a local checkout: pi install /absolute/path/to/CodeCartographer # or, from a git URL: -pi install git:github.com/your-user/CodeCartographer +pi install git:github.com/HuginnIndustries/CodeCartographer
@@ -192,10 +193,45 @@

10 tools for any MCP-compatible host.

+ +
+
+
04 · Forward synthesis
+

Turn confirmed software maps into a traceable build plan.

+

+ The synthesis pipeline runs through Pi or MCP. It combines a product vision with reusable, + versioned reimplementation specs, pauses for explicit human selection, preserves conflicts, + and produces work packages with a decision-level provenance ledger. +

+ +
+
+
Start
+ 
/codecarto-init synthesis
+# Fill .codecarto/inputs/vision.md
+/codecarto-next --auto
+

The first run creates a ranked proposal, completes that phase, and then intentionally stops at the confirmation preflight.

+
+
+
Confirm and resume
+ 
# In proposal.md:
+| [x] | event-router | v2 | ... |
+
+/codecarto-next --auto
+

Merge and finalization read only the checked, version-pinned specs. An unknown entry or version is rejected before any LLM phase starts.

+
+
+ +
+ Run the one-command demo +
+
+
+
-
04 · Deploy to Namecheap cPanel
+
05 · Deploy to Namecheap cPanel

Upload the static bundle and point the domain at it.

This site is plain HTML, CSS, and JavaScript. Drop it into public_html on your @@ -236,7 +272,7 @@

Upload the static bundle and point the domain at it.

-
05 · Token usage and cost
+
06 · Token usage and cost

What to expect on your first run.

CodeCartographer reads your source code multiple times across phases and produces thousands of diff --git a/features.html b/features.html index 2a1e59e..4bd1948 100644 --- a/features.html +++ b/features.html @@ -45,10 +45,10 @@

Features

01 · Pipeline variants
-

Six pipelines. Pick the depth that matches the job.

+

Seven pipelines. Map existing systems or plan a new one.

- Every pipeline starts with architecture. From there, you choose how far to go. The default is - a 7-phase full analysis with a split defect scan. Scale back when you only need orientation. + Six analysis variants scale from quick orientation to a deep audit. The forward synthesis + pipeline combines a vision with confirmed reusable specs to create a traceable project plan.

@@ -59,6 +59,7 @@

Six pipelines. Pick the depth that matches the job.

+
@@ -86,7 +87,7 @@

Full with deep audit

-

Phases form a DAG. Contracts and protocols can run in parallel after architecture. Porting waits for both. Reimplementation spec is last.

+

Two directions: analysis distills source code into reusable specifications; synthesis combines human-confirmed specifications with a product vision and preserves decision-level provenance in the resulting plan.

diff --git a/index.html b/index.html index 9d02e4a..84929f9 100644 --- a/index.html +++ b/index.html @@ -3,11 +3,11 @@ -CodeCartographer | Structured reverse-engineering for unfamiliar codebases - +CodeCartographer | Map existing software. Plan what comes next. + - + @@ -41,24 +41,26 @@
- Reverse-engineering toolkit · v0.11.0 + Evidence-backed software cartography · v0.11.0
-

Understand unfamiliar codebases with a process instead of a lucky prompt.

+

Understand existing software. Plan what comes next.

- CodeCartographer turns "explain this repo" into a staged investigation. Architecture, defect - scan, behavioral contracts, protocol notes, porting synthesis, and a reimplementation spec. - Each finding is evidence-tagged so confidence stays visible. + CodeCartographer turns “explain this repo” into a staged, evidence-backed investigation—then + combines explicitly confirmed specifications with a new product vision to create a traceable + implementation plan.

Start with the docs Install from npm Tour the pipeline + Build Week demo
Pi extension MCP server Drop-in template MIT licensed + Human-gated synthesis
@@ -107,6 +109,11 @@

Confidence stays visible.

Pick up where you left off.

The filesystem—not the conversation—is durable memory. A fresh LLM session reads the status and findings, then resumes without depending on compacted chat history.

+
+ Synthesis +

Specs become a project plan.

+

Versioned library entries are proposed against a vision, explicitly confirmed by a human, merged with conflicts intact, and transformed into work packages with a decision-level provenance ledger.

+
@@ -142,6 +149,10 @@

Porting bundle

Reimplementation spec

Language-agnostic build plan with modules, acceptance scenarios, and known unknowns.

+
+

Evidence-backed project plan

+

Confirmed specifications become architecture, work packages, acceptance gates, conflict dispositions, and a decision-level provenance ledger.

+
diff --git a/script.js b/script.js index 6441f8f..45d10ab 100644 --- a/script.js +++ b/script.js @@ -64,6 +64,14 @@ const pipelineData = { phases: ["Architecture"], note: "Ideal as a low-cost first pass when you only need to orient yourself.", }, + synthesis: { + kicker: "4 phases · forward flow", + title: "Synthesis", + description: + "Combines a product vision with explicitly confirmed, versioned library specifications to create an implementation-ready plan without losing provenance.", + phases: ["Vision capture", "Candidate proposal + human confirmation", "Specification merge", "Project plan"], + note: "Pi/MCP only. Runtime preflight refuses to merge or finalize until a human confirms at least one version-pinned input.", + }, }; function initPipelineSwitcher() { diff --git a/tests/upstream-consistency.test.mjs b/tests/upstream-consistency.test.mjs index da6a031..3a19fdc 100644 --- a/tests/upstream-consistency.test.mjs +++ b/tests/upstream-consistency.test.mjs @@ -31,7 +31,7 @@ test("every public version label matches the authoritative package version", asy assert.match(footer, new RegExp(`v${pkg.version.replaceAll(".", "\\.")}`), `${name} footer must show v${pkg.version}`); } const index = await read(join(SITE_ROOT, "index.html")); - assert.match(index, new RegExp(`Reverse-engineering toolkit · v${pkg.version.replaceAll(".", "\\.")}`)); + assert.match(index, new RegExp(`Evidence-backed software cartography · v${pkg.version.replaceAll(".", "\\.")}`)); }); test("MCP documentation names every tool registered by the upstream server", async () => { @@ -53,6 +53,16 @@ test("pipeline selector mirrors the authoritative pipeline variants", async () = assert.equal((features.match(/class="pipeline-tab/g) ?? []).length, pipelineFiles.length); }); +test("synthesis documentation preserves the human confirmation and provenance contracts", async () => { + const docs = await read(join(SITE_ROOT, "docs.html")); + const features = await read(join(SITE_ROOT, "features.html")); + assert.match(docs, /explicit human selection/i); + assert.match(docs, /version-pinned/i); + assert.match(docs, /provenance ledger/i); + assert.match(features, /human-confirmed/i); + assert.match(features, /decision-level provenance/i); +}); + test("continuity copy treats THREAD_LOG as a closeout index, not the durable summary store", async () => { const features = await read(join(SITE_ROOT, "features.html")); const card = features.match(/]*>THREAD_LOG\.md<\/code><\/h3>\s*

(.*?)<\/p>/s)?.[1] ?? "";