-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathfeatures.html
More file actions
378 lines (353 loc) · 19.1 KB
/
Copy pathfeatures.html
File metadata and controls
378 lines (353 loc) · 19.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Features — CodeCartographer</title>
<meta name="description" content="A tour of CodeCartographer: pipeline variants, evidence classification, phase-gating, cross-session continuity, and output artifacts.">
<meta name="theme-color" content="#141413">
<link rel="canonical" href="https://codecarto.dev/features.html">
<link rel="icon" href="logo.svg" type="image/svg+xml">
<link rel="stylesheet" href="site.css">
<script defer src="script.js"></script>
</head>
<body>
<header class="site-nav">
<div class="site-nav-inner">
<a href="index.html" class="brand">
<span class="brand-mark" aria-hidden="true"></span>
<span>CodeCartographer</span>
</a>
<nav>
<a href="index.html">Overview</a>
<a href="features.html" class="active">Features</a>
<a href="docs.html">Docs</a>
<a href="showcase.html">Showcase</a>
</nav>
<a href="https://github.com/HuginnIndustries/CodeCartographer" class="btn btn-secondary">View on GitHub</a>
</div>
</header>
<!-- =================== Page header =============== -->
<section class="hero" style="padding:72px 0 48px">
<div class="container">
<div class="hero-eyebrow"><span class="dot"></span> The system in detail</div>
<h1 style="font-size:clamp(36px, 4.5vw, 56px)">Features</h1>
<p class="hero-sub">
A tour of every piece: pipeline variants, evidence classification, phase-gating, cross-session
continuity, and the output artifacts you end up with.
</p>
</div>
</section>
<!-- =================== Pipelines ================= -->
<section class="section">
<div class="container">
<div class="overline">01 · Pipeline variants</div>
<h2>Seven pipelines. Map existing systems or plan a new one.</h2>
<p class="section-sub">
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.
</p>
<div class="pipeline-panel" data-reveal>
<div class="pipeline-switcher" role="tablist" aria-label="Pipeline variants">
<button class="pipeline-tab is-active" type="button" role="tab" data-pipeline="full-with-deep-audit">Full with deep audit</button>
<button class="pipeline-tab" type="button" role="tab" data-pipeline="full-with-audit">Full with audit</button>
<button class="pipeline-tab" type="button" role="tab" data-pipeline="full">Full</button>
<button class="pipeline-tab" type="button" role="tab" data-pipeline="defect-scan">Defect scan</button>
<button class="pipeline-tab" type="button" role="tab" data-pipeline="lite">Lite</button>
<button class="pipeline-tab" type="button" role="tab" data-pipeline="architecture-only">Architecture only</button>
<button class="pipeline-tab" type="button" role="tab" data-pipeline="synthesis">Synthesis</button>
</div>
<div class="pipeline-detail" aria-live="polite">
<p class="pipeline-kicker" id="pipeline-kicker">7 phases</p>
<h3 id="pipeline-title">Full with deep audit</h3>
<p id="pipeline-description">
Complete analysis with a two-pass defect scan. An early mechanical sweep catches
surface-level issues; a later semantic pass re-examines defects with full contracts
and protocols context before reimplementation planning.
</p>
<ol class="phase-list" id="pipeline-phases">
<li>Architecture</li>
<li>Defect scan (mechanical)</li>
<li>Contracts</li>
<li>Protocols</li>
<li>Defect scan (semantic)</li>
<li>Porting</li>
<li>Reimplementation spec</li>
</ol>
<p class="pipeline-note" id="pipeline-note">
The default pipeline. Best when you need the deepest defect analysis grounded in full
behavioral understanding.
</p>
</div>
</div>
<div class="compatibility-band" style="margin-top:32px" data-reveal>
<p style="margin:0"><strong>Two directions:</strong> 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.</p>
</div>
</div>
</section>
<!-- =================== Evidence classification === -->
<section class="section">
<div class="container">
<div class="overline">02 · Evidence classification</div>
<h2>Every finding tagged with a confidence level.</h2>
<p class="section-sub">
An LLM can sound certain about things it inferred. CodeCartographer requires every finding to
carry an evidence tag so you know what was observed, what was deduced, and what remains an
open question.
</p>
<div class="evidence-grid" data-reveal>
<div class="evidence-badge">
<div class="icon">🔍</div>
<h4>Observed fact</h4>
<p>Directly visible in source code or documentation. Not inferred.</p>
</div>
<div class="evidence-badge">
<div class="icon">🧠</div>
<h4>Strong inference</h4>
<p>Deduced from patterns and structure. High confidence but not directly stated.</p>
</div>
<div class="evidence-badge">
<div class="icon">⚠️</div>
<h4>Portability hazard</h4>
<p>Behavior or assumption that may not survive a rewrite or language change.</p>
</div>
<div class="evidence-badge">
<div class="icon">❓</div>
<h4>Open question</h4>
<p>Could not determine from available sources. Needs human input or deeper analysis.</p>
</div>
</div>
<div class="card-elevated" style="margin-top:28px;background:var(--color-surface-alt)" data-reveal>
<div class="overline" style="margin-bottom:6px">Discipline rule</div>
<p style="color:var(--color-text);font-size:16px;line-height:1.55;margin:0">
If an LLM cannot classify a finding with one of these four tags, the finding is not specific
enough to be useful. Vague assertions get rejected by the validation protocol.
</p>
</div>
</div>
</section>
<!-- =================== Phase-gating ============== -->
<section class="section">
<div class="container">
<div class="overline">03 · Phase-gating</div>
<h2>No phase advances until the current output validates.</h2>
<p class="section-sub">
Each phase produces a structured output against a template. The validation protocol checks
completion criteria: are all required sections present, are findings tagged with evidence
levels, are open questions logged in <code>status.yaml</code>.
</p>
<div class="grid-2">
<div class="card" data-reveal>
<div style="display:flex;align-items:center;gap:10px;margin-bottom:8px">
<span class="pill pill-sand"><code style="background:none;padding:0">templates/</code></span>
</div>
<h3 style="font-size:18px">Output templates</h3>
<p>Structured Markdown templates enforce consistent sections across projects and sessions. Every artifact has the same shape regardless of which LLM produced it.</p>
</div>
<div class="card" data-reveal>
<div style="display:flex;align-items:center;gap:10px;margin-bottom:8px">
<span class="pill pill-sand"><code style="background:none;padding:0">VALIDATE.md</code></span>
</div>
<h3 style="font-size:18px">Validation protocol</h3>
<p>Run after every phase. Checks that outputs match templates, evidence tags are applied, and partial results are logged properly before allowing the status to advance.</p>
</div>
</div>
</div>
</section>
<!-- =================== Progressive distillation == -->
<section class="section">
<div class="container">
<div class="overline">04 · Progressive distillation</div>
<h2>The codebase gets smaller in context and richer in meaning.</h2>
<p class="section-sub">
CodeCartographer does not ask one context window to remember the entire investigation. Each
phase turns a large body of source evidence into a smaller, more task-specific artifact that
downstream phases can read and validate.
</p>
<div class="pipeline-panel" data-reveal>
<div class="pipeline-detail" style="grid-column:1 / -1">
<p class="pipeline-kicker">Evidence-tagged distillation</p>
<ol class="phase-list">
<li>Raw source → architecture map</li>
<li>Architecture + targeted source reads → contracts, protocols, and defect findings</li>
<li>Validated findings → self-contained porting bundle + source index</li>
<li>Porting bundle + targeted deep reads → reimplementation spec</li>
</ol>
<p class="pipeline-note">
This is deliberate distillation, not incidental chat summarization. Templates, evidence
labels, open questions, and validation gates reduce the risk of an unsupported claim
becoming “fact” as information moves downstream.
</p>
</div>
</div>
<div class="grid-2" style="margin-top:24px">
<div class="card" data-reveal>
<h3 style="font-size:18px">Cross-phase context is durable</h3>
<p>Each phase gets a fresh context window and re-reads the upstream findings declared by the pipeline. Progress, open questions, carry-forward items, decisions, and closeouts live under <code>.codecarto/</code> rather than only in the conversation.</p>
</div>
<div class="card" data-reveal>
<h3 style="font-size:18px">Intra-phase limits stay visible</h3>
<p>Compaction inside one oversized phase can still be lossy. When full coverage will not fit, the phase records <code>PARTIAL</code> validation and routes unresolved work through <code>open_questions</code> or <code>carry_forward</code> instead of hiding the gap.</p>
</div>
</div>
<div class="compatibility-band" style="margin-top:28px" data-reveal>
<p style="margin:0"><strong>Practical result:</strong> compacting or replacing the orchestrator session does not erase pipeline progress. The next host session can reopen the durable state and continue; Pi users run <code>/codecarto-open</code> to attach without resetting it.</p>
</div>
</div>
</section>
<!-- =================== Cross-session continuity === -->
<section class="section">
<div class="container">
<div class="overline">05 · Cross-session continuity</div>
<h2>A fresh LLM session picks up exactly where the last one stopped.</h2>
<p class="section-sub">
Large codebases need multiple sessions. <code>status.yaml</code> is the single source of
truth. After the host opens the workspace, the new session reads the guide, checks the status
file, sees what is complete, and starts the next eligible phase. No explaining what happened before.
</p>
<div class="grid-2">
<div class="card" data-reveal>
<h3 style="font-size:18px"><code>status.yaml</code></h3>
<p>Mutable per-project state. Tracks phase completion, current phase, open questions, carry-forward work, and the active pipeline.</p>
</div>
<div class="card" data-reveal>
<h3 style="font-size:18px"><code>THREAD_LOG.md</code></h3>
<p>Append-only index pointing to per-session closeout files. Durable findings stay in phase outputs and closeouts; the log gives new sessions a compact route into that evidence without becoming a second summary store.</p>
</div>
</div>
<div class="card-elevated" style="margin-top:24px;background:var(--color-surface-alt)" data-reveal>
<div class="overline" style="margin-bottom:6px">Pi extension bonus</div>
<p style="color:var(--color-text);font-size:16px;line-height:1.55;margin:0">
In the Pi extension, <code>/codecarto-open</code> safely activates existing state in a fresh
orchestrator session. Phase sub-agents persist transcripts alongside that session.
<code>/resume</code>, <code>/tree</code>, and <code>/export</code> browse them as
first-class sessions with lineage back to the orchestrator.
</p>
</div>
</div>
</section>
<!-- =================== FAQ ======================== -->
<section class="section">
<div class="container">
<div class="overline">06 · Frequently asked questions</div>
<h2>Context, compaction, and delivery surfaces.</h2>
<div class="grid-2">
<div class="card" data-reveal>
<h3 style="font-size:18px">Is this repeatedly summarizing summaries?</h3>
<p>It is better described as progressive, evidence-tagged distillation. Each phase produces a purpose-built artifact with templates, evidence levels, known unknowns, and a validation gate before downstream phases use it.</p>
</div>
<div class="card" data-reveal>
<h3 style="font-size:18px">What happens when conversation context is compacted?</h3>
<p>Cross-phase state is reconstructed from files under <code>.codecarto/</code>, so compacting or replacing the orchestrator does not erase progress. Pi phase compaction now uses a phase-aware continuation summary, writes <code>scratch/checkpoints/<phase>.md</code>, and records compaction outcomes in local usage telemetry. The summary is still lossy, so material gaps remain explicit as <code>PARTIAL</code>, <code>open_questions</code>, or <code>carry_forward</code>.</p>
</div>
<div class="card" data-reveal>
<h3 style="font-size:18px">Who controls phase sessions?</h3>
<p>The Pi extension automatically runs phases in isolated, file-backed sessions and applies phase-aware compaction only to sessions named <code>CodeCartographer phase: <id></code>. An MCP host controls its own LLM sessions and compaction, so it should dispatch one fresh session per phase. The MCP server itself does not run an agent.</p>
</div>
<div class="card" data-reveal>
<h3 style="font-size:18px">What about the drop-in template?</h3>
<p>Drop-in mode uses the same durable files and phase protocol, but isolation is procedural rather than enforced. Start each phase in a fresh session, read the declared upstream artifacts, and preserve unresolved work on disk.</p>
</div>
<div class="card" data-reveal>
<h3 style="font-size:18px">Does the final spec reload every prior report?</h3>
<p>No. The porting bundle is the final intentional compression boundary. Its source index carries load-bearing claims, defect dispositions, coverage gaps, and deep-read triggers. Final synthesis opens lower-level findings only for a named gap, conflict, missing acceptance detail, or defect rationale.</p>
</div>
<div class="card" data-reveal>
<h3 style="font-size:18px">How is incomplete coverage reported?</h3>
<p>Every phase has a <code>Coverage and limits</code> section naming inspected scope, skipped scope, evidence basis, and blind spots. Material gaps produce <code>PARTIAL</code> validation and remain visible in <code>open_questions</code> or <code>carry_forward</code>.</p>
</div>
</div>
</div>
</section>
<!-- =================== Output artifacts ========== -->
<section class="section-dark">
<div class="container">
<div class="overline">07 · Output artifacts</div>
<h2>The bundle you end up with.</h2>
<p class="section-sub">
Each artifact targets a different audience: engineers, reviewers, maintainers, and the next
LLM session.
</p>
<div class="artifact-grid" style="margin-top:8px">
<div class="artifact" data-reveal>
<h3>Architecture map</h3>
<p>Layers, public surfaces, runtime lifecycle, dependency direction, porting priorities.</p>
</div>
<div class="artifact" data-reveal>
<h3>Defect report</h3>
<p>Multi-pass scan: logic, error handling, concurrency, security, API drift, config risks.</p>
</div>
<div class="artifact" data-reveal>
<h3>Behavioral contracts</h3>
<p>User-visible behavior, defaults, side effects, error modes, black-box acceptance checks.</p>
</div>
<div class="artifact" data-reveal>
<h3>Protocols and state</h3>
<p>Events, state machines, persistence notes, compatibility hazards, internal message flow.</p>
</div>
<div class="artifact" data-reveal>
<h3>Porting bundle</h3>
<p>Synthesis layer ranking what matters, what is risky, what needs special treatment in a rewrite.</p>
</div>
<div class="artifact" data-reveal>
<h3>Reimplementation spec</h3>
<p>Language-agnostic build plan with modules, acceptance scenarios, and known unknowns.</p>
</div>
</div>
</div>
</section>
<!-- =================== CTA ======================= -->
<section class="section">
<div class="container-narrow" style="text-align:center">
<h2 style="margin:0 auto 18px;text-align:center">Ready to try it on your own codebase?</h2>
<p class="section-sub" style="margin:0 auto 32px;text-align:center">
Read the installation docs for drop-in setup, Pi extension commands, or MCP server configuration.
</p>
<div style="display:flex;gap:12px;justify-content:center;flex-wrap:wrap">
<a href="docs.html" class="btn btn-primary">Read the docs</a>
<a href="https://github.com/HuginnIndustries/CodeCartographer/archive/refs/heads/main.zip" class="btn btn-secondary">Download ZIP</a>
</div>
</div>
</section>
<!-- =================== Footer ==================== -->
<footer class="site-footer">
<div class="site-footer-inner">
<div>
<div style="display:flex;align-items:center;gap:10px;font-family:var(--font-serif);font-weight:500;font-size:18px;color:#f5efd8">
<span class="brand-mark" style="width:28px;height:28px;border-radius:8px;flex-shrink:0" aria-hidden="true"></span>
CodeCartographer
</div>
<p class="tagline">A structured reverse-engineering toolkit for unfamiliar codebases.</p>
</div>
<div>
<h4>Site</h4>
<a href="index.html">Overview</a>
<a href="features.html">Features</a>
<a href="docs.html">Docs</a>
<a href="showcase.html">Showcase</a>
</div>
<div>
<h4>Project</h4>
<a href="https://github.com/HuginnIndustries/CodeCartographer">GitHub</a>
<a href="https://github.com/HuginnIndustries/CodeCartographer/blob/main/CHANGELOG.md">Changelog</a>
<a href="https://github.com/HuginnIndustries/CodeCartographer/blob/main/LICENSE">License</a>
<a href="https://github.com/HuginnIndustries/CodeCartographer/archive/refs/heads/main.zip">Download ZIP</a>
</div>
<div>
<h4>Guides</h4>
<a href="https://github.com/HuginnIndustries/CodeCartographer/blob/main/GUIDE.md">Usage guide</a>
<a href="https://github.com/HuginnIndustries/CodeCartographer/blob/main/MANUAL.md">Manual</a>
<a href="https://github.com/HuginnIndustries/CodeCartographer/blob/main/CONTRIBUTING.md">Contributing</a>
</div>
<div>
<h4>Package</h4>
<a href="https://www.npmjs.com/package/codecartographer-pi">npm</a>
</div>
</div>
<div class="site-footer-bottom">
<span>v0.12.11 · MIT License</span>
<span>codecarto.dev</span>
</div>
</footer>
</body>
</html>