geneseed 3.15.0 → 3.17.0

package/js/loop/graph.mjs

@@ -83,7 +83,8 @@ export function checkGraph(graph, bricks) {
     if (!brick) continue;
     for (const o of brick.outcomes) {
       const count = edges.filter((e) => e.from === n && e.on === o).length;
-      if (count === 0) problems.push(`node ${n}: no edge for outcome ${o}`);
+      // `error` is reserved: with no edge the engine routes it to $stop (`recordOutcome`).
+      if (count === 0 && o !== 'error') problems.push(`node ${n}: no edge for outcome ${o}`);
       else if (count > 1) problems.push(`node ${n}: ${count} edges for outcome ${o}`);
     }
   }

package/js/loop/state.mjs

@@ -288,6 +288,22 @@ function allowedEntries(graph, v) {
   return { allowed: widest ? 1 + widest.max : 1, loop: widest };
 }
 
+// The repair ring an edge closes: the smallest non-iteration loop whose FIRST node is the edge's
+// target and which also holds its source (test -> apply is apply-test's repair, review -> apply
+// review-fix's). Its own counter makes `max` the number of repairs that ring may spend, even when
+// a wider ring sharing the node raises the node budget above it — `max: 1` is one repair, then
+// `exhaust`'s fresh attempt, then a stop (arXiv 2607.24604: a second revision lowers accuracy).
+// Its key lives in `counters`, so every reset of a unit resets it too.
+function repairRing(graph, from, to) {
+  const iteration = iterationLoop(graph);
+  let ring = null;
+  for (const m of graph.loops) {
+    if (m === iteration || m.nodes[0] !== to || !m.nodes.includes(from)) continue;
+    if (!ring || m.nodes.length < ring.nodes.length) ring = m;
+  }
+  return ring;
+}
+
 // Porcelain lines are `XY <path>`; strip the 2-char status + space, slash-normalise, drop
 // LOOP.md rows (the engine rewrites it on every action — it is never part of the scored work)
 // and a lingering LOOP.md.tmp (the atomic writer's own sibling — see `writeLoopFile`'s docblock).
@@ -348,10 +364,17 @@ export function recordOutcome(state, bricks, outcome, { card = null, porcelain =
   // this call closes the unit, re-splits, or stops the loop. `notes` is never reset mid-run
   // (only `exhaust`'s own push and `decideAwaiting` add to it otherwise), so it survives
   // `resetUnit`/`finishUnit` — which a card does not: `resetUnit` clears it.
+  // A fresh verdict: `test`'s latest report supersedes its earlier ones, so a repair never reads
+  // findings about code that has since changed (stale traces broke 34 of 135 correct attempts
+  // in arXiv 2607.24604, fresh ones 4). Every other brick's notes are a record and are kept.
+  if (from === 'test') state.notes = state.notes.filter((n) => !/^iteration \d+ \(test\): /.test(n));
   if (note) state.notes.push(`iteration ${state.iteration} (${from}): ${note}`);
   state.visited.push(from);
 
-  const edge = state.graph.edges.find((e) => e.from === from && e.on === outcome);
+  // `error` is reserved: a check that produced no verdict stops for a human, never a repair. A
+  // brick may declare it without an edge (`checkGraph` allows that); the engine routes it here.
+  const edge = state.graph.edges.find((e) => e.from === from && e.on === outcome)
+    ?? (outcome === 'error' ? { from, on: 'error', to: '$stop' } : null);
   if (!edge) throw new Error(`no edge from ${from} on ${outcome}`);
   if (brick.gate === 'human' && (!brick.gateOn || brick.gateOn.includes(outcome))) {
     state.status = 'awaiting';
@@ -385,6 +408,12 @@ function transition(state, bricks, from, edge) {
     finishUnit(state, false);
     return state.status === 'stopped' ? { stopped: state.reason } : { node: state.node };
   }
+  const ring = repairRing(state.graph, from, edge.to);
+  if (ring) {
+    const key = `ring:${ring.name}`;
+    state.counters[key] = (state.counters[key] ?? 0) + 1;
+    if (state.counters[key] > ring.max) return exhaust(state, ring);
+  }
   state.counters[edge.to] = (state.counters[edge.to] ?? 0) + 1;
   const { allowed, loop } = allowedEntries(state.graph, edge.to);
   if (state.counters[edge.to] > allowed) return exhaust(state, loop ?? { name: edge.to, max: 0 });

package/js/maintain/setup.mjs

@@ -277,11 +277,18 @@ export function collectSetupLines() {
   // `setupBuildArgs` spell `--exclude-rules none`, and that string would land in the
   // "About to run:" line every recorded wizard probe compares byte for byte.
   const excludeRules = inst.excludeRules?.length ? inst.excludeRules : null;
+  // Skills left out are preserved the same way, and elide when there are none.
+  const excludeSkills = inst.excludeSkills?.length ? inst.excludeSkills : null;
   printOut(`\nAbout to run:  geneseed build ${
     setupBuildArgs(theme, emit, out, root, footprint, posture, mode, doctrines, allPacks,
-      excludeRules).join(' ')}\n`);
+      excludeRules, undefined, excludeSkills).join(' ')}\n`);
   if (!confirm('Proceed?', true)) return null;
-  return { theme, posture, mode, doctrines, excludeRules, emit, out, root, footprint };
+  // The key only when there is something to carry, so a selection that excludes no skill is
+  // the same object it was before the flag existed.
+  return {
+    theme, posture, mode, doctrines, excludeRules, ...(excludeSkills ? { excludeSkills } : {}),
+    emit, out, root, footprint,
+  };
 }
 
 // --------------------------------------------------------------------------------------
@@ -463,7 +470,7 @@ export function setupLines() {
   }
   const {
     theme, emit, out, root, footprint = 'lean', posture = 'peer', mode = 'direct',
-    doctrines = null, excludeRules = null,
+    doctrines = null, excludeRules = null, excludeSkills = null,
   } = sel;
   if (emit === 'opencode-global') {
     // The build below overwrites the deployed global harness, and the self-improvement loops
@@ -482,7 +489,7 @@ export function setupLines() {
   // runs must carry the pack selection the plan line just previewed, or the wizard would print
   // one command and run another.
   const argv = setupBuildArgs(theme, emit, out, root, footprint, posture, mode, doctrines,
-    doctrineOptions().map(([n]) => n), excludeRules);
+    doctrineOptions().map(([n]) => n), excludeRules, undefined, excludeSkills);
   printOut(`Running:  geneseed build ${argv.join(' ')}\n`);
   const rc = driverMain(argv);
   if (rc !== 0) {

package/js/maintain/update.mjs

@@ -617,7 +617,7 @@ export async function installAxes(dir, { installProfile, setupBuildArgs }) {
   if (!existsSync(path.join(String(dir), '.geneseed-emit'))) return [];
   const p = installProfile('opencode', 'global', String(dir));
   return setupBuildArgs('', 'files', null, null, p.footprint, p.posture, p.mode, p.doctrines,
-    undefined, p.excludeRules, p.trust).slice(4);
+    undefined, p.excludeRules, p.trust, p.excludeSkills).slice(4);
 }
 
 /**

package/js/web/actions.mjs

@@ -46,7 +46,8 @@ import {
   opencodeConfigDir, resolvePath,
 } from '../hosts/hosts.mjs';
 import {
-  EMIT_HOST_SCOPE, doctrinesForBuild, excludedRulesOfDir, footprintOfDir, installState,
+  EMIT_HOST_SCOPE, doctrinesForBuild, excludedRulesOfDir, excludedSkillsOfDir, footprintOfDir,
+  installState,
   installTargets, modeOfDir, postureOfDir, trustOfDir,
 } from '../hosts/installs.mjs';
 import {
@@ -550,6 +551,7 @@ export function apiRestore(state, files) {
       // The excluded rules for the same boundary reason: without them a restored AGENT.md
       // re-states a rule whose hook gate the install deliberately left unwired.
       excludeRules: excludedRulesOfDir(target),
+      excludeSkills: excludedSkillsOfDir(target),
     }));
     for (const raw of (isTruthy(files) ? files : [])) {
       const rel = stripWhitespace(formatValue(raw).replace(/\\/g, '/')).replace(/^\/+/, '');
@@ -622,7 +624,7 @@ export function apiInstallCmd(state, body) {
   const excludeRules = bodyExcludeRules(body) ?? excludedRulesOfDir(root);
   const out = scope === 'global' ? null : String(root);
   const argv = setupBuildArgs(theme || 'neutral', emit, out, out, fp, pos, mode, doctrines,
-    PACK_ORDER, excludeRules, trust);
+    PACK_ORDER, excludeRules, trust, excludedSkillsOfDir(root));
   return { cmd: [process.execPath, path.join(ROOT, 'bin', 'build-driver.mjs'), ...argv] };
 }
 
@@ -716,6 +718,6 @@ export function apiDeployCmd(state, body) {
   const excludeRules = bodyExcludeRules(body) ?? excludedRulesOfDir(root);
   // project-scope emit name == host name (opencode / claude / bob / openclaude)
   const argv = setupBuildArgs(theme || 'neutral', host, root, root, fp, pos, mode, doctrines,
-    PACK_ORDER, excludeRules, trust);
+    PACK_ORDER, excludeRules, trust, excludedSkillsOfDir(root));
   return { cmd: [process.execPath, path.join(ROOT, 'bin', 'build-driver.mjs'), ...argv] };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
   "name": "geneseed",
-  "version": "3.15.0",
+  "version": "3.17.0",
   "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
   "keywords": [
     "ai",

package/src/AGENT.md.tmpl

@@ -295,7 +295,7 @@ inventory — that list is the catalogue and it is authoritative. Each written
 procedure is in [`{{DIR_SKILLS}}/`]({{DIR_SKILLS}}/) and the host loads it on
 demand.
 <!-- CATALOG:end -->
-
+{{EXCLUDED_SKILLS_LINE}}
 When a task repeats and no {{SKILL}} covers it, forge one through the
 [skill-forge]({{DIR_SKILLS}}/skill-forge.md) {{SKILL}}: copy
 [`{{DIR_SKILLS}}/_template.md`]({{DIR_SKILLS}}/_template.md), keep it to one coherent

package/src/agents/docs.md

@@ -24,6 +24,11 @@
    that the code does not implement ({{LAW:verify-before-asserting}}).
 2. Write for the stated audience; lead with what the reader needs to do.
 3. Keep examples runnable; update any example that the change broke.
+4. Write each page in the format it is already in — Markdown or AsciiDoc; never convert one.
+   A new page follows the `Docs format:` line in the root `AGENTS.md`, else the format the
+   project's docs already use (only AsciiDoc when it has none yet). Agent-runtime files —
+   `AGENTS.md`, `CLAUDE.md`, specs, ADRs loops read — stay Markdown. In AsciiDoc, never add
+   an `include::` to a page agents read.
 
 ## Output contract
 - The doc files written/updated, a one-line note of what changed and why,

package/src/bricks/apply.md

@@ -9,6 +9,9 @@ Implement the card's intent exactly, touching only the files in its `writeSet`.
 carries an `amend`, that supersedes the original intent — follow the amendment, not the plan it
 replaced.
 
+When this is a repair after `test`, act on the latest `test` note only — it is the verdict on
+the code as it stands. Fix every finding it lists in this one pass: there is no second repair.
+
 Make no unrelated edits: no drive-by rename, no incidental cleanup, no touching a file the card
 did not declare. If the change genuinely needs a file outside the write set, stop and report that
 rather than widening scope unasked — the diff is scored against the declared set, not your

package/src/bricks/docs-update.md

@@ -10,6 +10,8 @@ flag, a moved file, a behaviour the README or docs still describe the old way.
 
 Update only those docs, only to match what the diff actually changed. Do not rewrite unrelated
 prose, reorganize a page, or fix an unrelated staleness you happen to notice while in there.
+Keep each doc in the format it is already in (Markdown or AsciiDoc) — never convert one; a new
+page follows the `Docs format:` line in the root `AGENTS.md`.
 
 Report `pass` once every doc the diff touched is back in sync, naming the files you changed — or
 that none needed it, if the diff left nothing stale.

package/src/bricks/test.md

@@ -1,14 +1,24 @@
 ---
 name: test
-description: Run the suite and linter over this iteration's change.
+description: Run the project's checks over this iteration's change, in order, and report every finding.
 effect: read
 agent: tester
-outcomes: pass, fail
+outcomes: pass, fail, error
 ---
-Run this project's full test suite and its linter over the current change. Never edit any file —
-this brick only observes; a fix belongs in `apply`, not here.
+Run this project's checks over the current change, in this order. Never edit any file — this
+brick only observes; a fix belongs in `apply`, not here.
 
-Report `pass` only if both exit clean.
+1. **Gate** — the build or compile step. If it fails, mark every check below `SKIPPED (gate
+   failed)` and report.
+2. **Focused checks** — the linter and the tests the change can reach. Run every one even after a
+   failure: they check independent properties, and the one repair must see every finding at once.
+3. **Full suite** — only when everything above passed; otherwise `SKIPPED (an earlier check failed)`.
 
-Report `fail` otherwise, with the raw failures (not a paraphrase) so `apply` can act on the actual
-error rather than your summary of it. Name every failing test and lint violation you saw.
+List every check with `PASS`, `FAIL`, `ERROR` or `SKIPPED (reason)` — one that did not run is
+never left out, and silence is never a pass. Write each failure as four lines: the check's
+purpose, the property it guards, a one-line diagnostic (not the raw log), and the command that
+reruns it alone. Keep full logs in a file, and write the list to the note file.
+
+Report `pass` only if every check passed. Report `error` if a check crashed or could not be run —
+no test runner, a missing tool, evidence never wired: that is a stop for a human, not a repair.
+Report `fail` otherwise.

package/src/doctrines/process.md

@@ -114,9 +114,11 @@ legitimate rewrite). The host gates both at the tool boundary.
 Every autonomous loop needs an exit you set before you enter it. Before iterating —
 retrying, searching, generating-and-checking — fix the bounds: a cap on attempts, a
 budget of time or tokens, and an explicit definition of success *and* of failure.
-Then watch for the loop that has stopped progressing: if you are issuing the same
-call, hitting the same error, or trying variations of one approach with no new
-information, that is not persistence, it is thrashing — break out, change strategy,
+A check-and-repair loop gets one repair, then a fresh attempt or a hand-back — a second
+revision lowers accuracy. Only a verdict on the final artifact counts: a pass from before
+an edit is void, and old check output is never fed back. Then watch for the loop that has stopped progressing:
+if you are issuing the same call, hitting the same error, or trying variations of one
+approach with no new information, that is not persistence, it is thrashing — break out, change strategy,
 gather different context, or stop. When a bound is reached or progress stalls, do
 not grind on: halt and hand back a structured summary of what was tried, what was
 learned, and what remains ({{LAW:surface-failures}}, {{DOCTRINE:plan-before-acting}}). {{DOCTRINE:context-economy}}
@@ -124,8 +126,10 @@ economises *within* a step; this bounds the *number* of steps. An agent that can
 stop itself is a cost without a limit.
 <!-- LEAN:else -->
 Fix an autonomous loop's bounds before you enter it: an attempt cap, a time or token
-budget, an explicit definition of success *and* failure. Watch for the loop that has
-stopped progressing: the same call, the same error, variations with no new information are
+budget, an explicit definition of success *and* failure. A check-and-repair loop spends
+one repair, then a fresh attempt or a hand-back; accept only a verdict on the final
+artifact — a pass from before an edit is void, old check output is never fed back.
+Watch for the loop that has stopped progressing: the same call, the same error, variations with no new information are
 thrashing; break out, change strategy, or stop. When a bound is reached or progress
 stalls, halt with a structured summary of what was tried, learned, and remains ({{LAW:surface-failures}},
 {{DOCTRINE:plan-before-acting}}).

package/src/loops/api-endpoint.json

@@ -24,7 +24,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "bruno-test", "security-scan", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
     { "name": "review-fix", "nodes": ["apply", "test", "bruno-test", "security-scan", "review"], "max": 3 }
   ],
   "contracts": ["**/openapi*.yaml", "**/openapi*.yml", "**/openapi*.json", "**/swagger*.yaml", "**/swagger*.yml", "**/swagger*.json"]

package/src/loops/bugfix.json

@@ -17,7 +17,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ]
 }

package/src/loops/ci-repair.json

@@ -14,6 +14,6 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["ci-triage", "ci-fix", "test"], "max": 10, "iteration": true },
-    { "name": "fix-test", "nodes": ["ci-fix", "test"], "max": 3 }
+    { "name": "fix-test", "nodes": ["ci-fix", "test"], "max": 1 }
   ]
 }

package/src/loops/deps-upgrade.json

@@ -22,7 +22,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["upgrade-scout", "apply", "test", "deps-audit", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
     { "name": "review-fix", "nodes": ["apply", "test", "deps-audit", "review"], "max": 3 }
   ],
   "ignoreDeletions": ["**/package-lock.json", "**/yarn.lock", "**/pnpm-lock.yaml", "**/*.lock", "**/gradle.lockfile"]

package/src/loops/enforce-architecture-rule.json

@@ -22,7 +22,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ]
 }

package/src/loops/feature.json

@@ -18,7 +18,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "review", "done-check"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ]
 }

package/src/loops/fix-flaky-tests.json

@@ -24,7 +24,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "flake-check", "test", "review"], "max": 10, "iteration": true },
-    { "name": "stabilise", "nodes": ["apply", "flake-check"], "max": 4 },
+    { "name": "stabilise", "nodes": ["apply", "flake-check"], "max": 1 },
     { "name": "review-fix", "nodes": ["apply", "flake-check", "test", "review"], "max": 3 }
   ]
 }

package/src/loops/legacy-refactor.json

@@ -19,7 +19,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ],
   "weights": { "logic": 0.6 }

package/src/loops/legacy-tests.json

@@ -22,7 +22,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "characterize", "test", "mutation-check"], "max": 20, "iteration": true },
-    { "name": "write-run", "nodes": ["characterize", "test"], "max": 3 },
+    { "name": "write-run", "nodes": ["characterize", "test"], "max": 1 },
     { "name": "kill-mutants", "nodes": ["characterize", "test", "mutation-check"], "max": 3 }
   ],
   "weights": { "new-file": 0.2 }

package/src/loops/refactor.json

@@ -18,7 +18,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 }
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 }
   ],
   "weights": { "logic": 0.6 }
 }

package/src/loops/remove-dead-code.json

@@ -22,7 +22,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ],
   "weights": { "delete": 0.5 },

package/src/loops/spec-first-feature.json

@@ -23,7 +23,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "review", "done-check"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ]
 }

package/src/loops/tdd.json

@@ -19,7 +19,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "red-test", "apply", "test", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ]
 }

package/src/loops/update-contract.json

@@ -23,7 +23,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "compat-check", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
     { "name": "review-fix", "nodes": ["apply", "test", "compat-check", "review"], "max": 3 }
   ],
   "contracts": [

package/src/skills/document-project.md

@@ -5,34 +5,57 @@
 **Trigger:** the project's docs are missing or have drifted from the code, or it needs a PRD, a design system, an architecture document or an AGENTS.md. Existing codebases only — every document is extracted from the code, never written ahead of it.
 
 **Argument:** `[prd|design|architecture|agents|all]` — optional. It names the doc-set members to
-write; with none, step 3 proposes them.
+write; with none, step 5 proposes them.
 
 ## Procedure
 1. **Find the doc home.** Look for an existing `docs/`, `doc/`, `documentation/`, or
    `wiki/` folder at the project root, or a `context.json` pointer to one (the same
    convention [repo-map {{SKILL}}](repo-map.md) and the context loader use). Reuse the one
    that exists — never create a second. If none exists, create `docs/` at the root.
-2. **Survey the code, not the intent.** Map entry points, the public API / modules,
+2. **Pick the docs format** — Markdown or AsciiDoc, once per project. A `Docs format:
+   markdown|asciidoc` line in the root `AGENTS.md` decides; never re-decide it. Otherwise
+   look at the project's existing docs (the doc home and the root `README`), ignoring the
+   agent-runtime files below: only `.md` → Markdown; only `.adoc` → AsciiDoc; both → ask
+   the user; no docs yet → AsciiDoc. Record the result as that line under *Non-obvious
+   conventions* in `AGENTS.md`.
+   - **Agent-runtime files stay Markdown whatever the format:** `AGENTS.md`, `CLAUDE.md`,
+     `SKILL.md`, and the specs and ADR files that loops read — the tools need them so.
+   - **In a Markdown project, propose — never impose — a switch to AsciiDoc** when the docs
+     would gain from it: complex tables, many diagrams, content reused across pages,
+     several versions, or PDF output. Say which need you saw, once; the user decides, and a
+     yes rewrites the recorded line.
+   - **In AsciiDoc,** apply *AsciiDoc mode* below wherever this skill shows Markdown.
+3. **Interview first when the project has no docs yet** — before writing anything. The code
+   gives the *what*; only the user gives the *why*. Ask one question at a time, offering
+   options where you can: the audience and what they need to do — which also sets the C4
+   levels: L1 and L2 always, L3 only for the containers the user calls complex; the project's purpose;
+   goals and non-goals; the key decisions and the reason for each; constraints; what is out
+   of scope. Read any spec, ADRs or design notes that exist, for facts. When an answer
+   explains a decision, offer to record it as an ADR (in `architecture`'s *Decisions*) —
+   accept or skip. Draft only once the user says the interview is done. Skip this step on a
+   re-run or when docs exist: their prose already carries the intent.
+4. **Survey the code, not the intent.** Map entry points, the public API / modules,
    commands, config, and key directories — read the actual behaviour ({{LAW:verify-before-asserting}},
    {{DOCTRINE:read-the-docs-first}}). If there is no `ARCHITECTURE.md`, run [repo-map {{SKILL}}](repo-map.md)
    first so you have the orientation map to build on.
-3. **Select the doc set.** Unless the argument names the targets, propose which of the four
+5. **Select the doc set.** Unless the argument names the targets, propose which of the four
    documents apply and wait for the user's go-ahead — e.g. "no UI detected (no stylesheet,
    theme, or component tree) — skipping `DESIGN.md`". `AGENTS.md`, `PRD.md` and
    `architecture.md` apply to every project; `DESIGN.md` only when a UI exists.
    `all` still skips `DESIGN.md` when no UI exists, and says so in one line.
-4. **Write or refresh each selected document** from its template in *The doc set* below,
+6. **Write or refresh each selected document** from its template in *The doc set* below,
    under the rules in *Re-runs*. **Invent nothing**: every claim cites `path:line`, or carries
    the marker `⚠ to confirm` (in the user's language). When drafting is done, put every `⚠` to
    the user as **one** batch of questions — not one at a time — and fold the answers in as plain
    text. A command you could not run is recorded as `⚠ fails: <error>`, never as working.
-   Every document follows the three page conventions in step 5.
-5. **Reconcile the markdown (whole tree).** Check every existing page against the current
+   Every document follows the three page conventions in step 7.
+7. **Reconcile the docs (whole tree).** Check every existing page against the current
    implementation — renamed or removed APIs, changed flags, dead examples — and fix the
    drift. Add pages for significant undocumented surfaces; remove docs for features that no
    longer exist ({{LAW:deletion-is-deliberate}}). For substantial writing, dispatch
    the [docs {{AGENT}}](../{{DIR_AGENTS}}/docs.md). Keep examples runnable — run them.
-   Every generated page follows three conventions:
+   Every generated page follows three conventions (in AsciiDoc mode, their *AsciiDoc mode*
+   forms):
    - **Typed frontmatter.** Open each page with YAML frontmatter carrying `type:` (one of
      `overview`, `module`, `api`, `flow`, `how-to`, `prd`, `design-system`, `architecture`),
      `mirrors-commit: <sha>`, and `generated: <date>` — so drift is auditable per page, not only
@@ -43,15 +66,15 @@ write; with none, step 3 proposes them.
      `<!-- geneseed:doc:start -->` and `<!-- geneseed:doc:end -->` markers — one pair per
      section, so prose a reader adds between sections survives — and on re-runs rewrite *only*
      inside them; hand-authored prose outside the markers is never touched.
-   - **Diagrams as Mermaid, keyed by purpose.** In the markdown, render diagrams as fenced
+   - **Diagrams as Mermaid, keyed by purpose.** In the doc pages, render diagrams as fenced
      `mermaid` code blocks — they render natively on GitHub, Obsidian, and VS Code with no
      dependency. Pick the kind by what you are showing: sequence for runtime/request flows,
      ER for data models, state for lifecycles, flowchart for control flow and C4 views. Reserve
-     hand-authored inline SVG for the offline HTML only (step 7).
-6. **Keep an index.** Ensure the doc home has an index/README linking every page, the doc-set
+     hand-authored inline SVG for the offline HTML only (step 9).
+8. **Keep an index.** Ensure the doc home has an index/README linking every page, the doc-set
    members included, current with the set you just reconciled.
-7. **Regenerate the HTML** — self-contained files at the doc home, a visual parallel to the
-   markdown and never a source of truth: regenerate them whole from the markdown each run
+9. **Regenerate the HTML** — self-contained files at the doc home, a visual parallel to the
+   doc pages and never a source of truth: regenerate them whole from the pages each run
    ({{DOCTRINE:edit-the-source-not-the-surface}}).
    Overwrite the previous ones, but confirm each is the generated artifact before clobbering
    ({{LAW:verify-before-asserting}}, {{LAW:deletion-is-deliberate}}). Both files:
@@ -65,7 +88,7 @@ write; with none, step 3 proposes them.
    **`overview.html`** (always) must:
    - **Carry the digest** — hero (project name + one-line purpose), a quick-facts strip
      (language, entry point, build/test/run, license), an architecture section (component
-     cards and an inline-SVG or CSS directory tree), and links out to the markdown docs for
+     cards and an inline-SVG or CSS directory tree), and links out to the doc pages for
      depth.
    - **Go deep on the hard parts** — identify the few subsystems that carry the project's
      essential complexity (the core engine, the load-bearing algorithms, the non-obvious
@@ -83,7 +106,7 @@ write; with none, step 3 proposes them.
    sizes and weights; spacing, radius and shadow on sample squares; components as cards
    (variants, states, path) — no live rendering, which would need the project's framework; and
    the hard-coded-value drift in a separate callout.
-8. **Do not auto-publish.** Leave the changes for the user to review; stage and commit only
+10. **Do not auto-publish.** Leave the changes for the user to review; stage and commit only
    on consent, via the [commit {{SKILL}}](commit.md) ({{DOCTRINE:consent-before-push}}).
 
 ## The doc set
@@ -121,26 +144,67 @@ The detailed architecture. Open with a link to the root `ARCHITECTURE.md` (repo-
 map) and make sure the map links back — one fenced `geneseed:doc` line at its top, nothing else
 in that file touched; repeat nothing between the two.
 1. **Context (C4 L1)** — the system, its actors, and the external systems (APIs, SSO, shared
-   databases), as a Mermaid flowchart.
+   databases).
 2. **Containers (C4 L2)** — the deployable units and the protocols between them.
-3. **Components (C4 L3)** — one diagram per *significant* container, not one per module. On a
-   monorepo, work one container or package at a time.
+3. **Components (C4 L3)** — only for the containers the user called complex in the interview
+   (on a re-run, the ones already drawn), one diagram each. On a monorepo, work one container
+   or package at a time. Never draw L4 (code) — the code is its own diagram.
 4. **Decisions** — lightweight inline ADRs, `ADR-001`, …, four lines each: *context · decision ·
    consequences · evidence*. Structural choices only (framework, storage, architectural style,
    decomposition) — not details.
 
+**C4 notation.** Every diagram is a Mermaid `flowchart` styled as C4 — not the `C4Context` /
+`C4Container` diagram types, which Mermaid still marks experimental and lays out by hand. Each
+node reads `name [type · technology]` (type: person, software system, container, component,
+database), each edge `intent · protocol`, and each diagram carries a `title:` and a `Legend`
+subgraph keying its shapes (c4model.com notation). Each diagram sits inside its section's
+`geneseed:doc` fences, so a re-run redraws it there and nowhere else.
+
+```mermaid
+---
+title: Containers (C4 L2) — shop
+---
+flowchart LR
+  user(["Customer [person]"]) -->|"browses · HTTPS"| web["web [container · React SPA]"]
+  web -->|"reads orders · HTTPS/JSON"| api["api [container · Node/Express]"]
+  api -->|"reads/writes · SQL"| db[("orders [database · PostgreSQL]")]
+  subgraph Legend
+    l1(["person"]) ~~~ l2["container"] ~~~ l3[("database")]
+  end
+```
+
 ### `AGENTS.md` — repo root, at most ~60 lines
 The short manual an agent reads before touching the repo.
 1. **Commands** — build, test, lint, run: exact, and verified by running each one.
-2. **Non-obvious conventions**.
+2. **Non-obvious conventions** — first, the `Docs format:` line from step 2.
 3. **Do not touch** — generated files, vendored code, applied migrations.
-4. **Before you change…** — targeted pointers: a UI → `docs/DESIGN.md`; a new flow or
-   container → `docs/architecture.md`; a feature → `docs/PRD.md` (its FR ID).
+4. **Before you change…** — targeted pointers: a UI → `docs/DESIGN.md`; a change that crosses
+   containers → read the L2 diagram in `docs/architecture.md` first; a new flow or container →
+   `docs/architecture.md`; a feature → `docs/PRD.md` (its FR ID) — with the extension the docs
+   format gives them.
 
 Geneseed may own a block in this file, between `<!-- BEGIN GENESEED -->` and
 `<!-- END GENESEED -->` — never write inside it. Create the file if it is absent; if it holds
 only that block, add the project sections below it.
 
+## AsciiDoc mode
+When step 2 picks AsciiDoc, every doc page this skill writes is AsciiDoc; `AGENTS.md` and
+the other agent-runtime files stay Markdown.
+- **Page names:** `.adoc` for every page — `PRD.adoc`, `DESIGN.adoc`, `architecture.adoc`,
+  `index.adoc`. A `README.adoc` is fine: GitHub shows it as the repo homepage.
+- **Typed header, not frontmatter:** the page title (`= Title`) followed by attributes —
+  `:geneseed-type: prd`, `:geneseed-mirrors-commit: <sha>`, `:geneseed-generated: <date>`.
+  `index.adoc` carries none.
+- **Fences:** `// geneseed:doc:start` and `// geneseed:doc:end` comment lines, one pair per
+  section, with the same rewrite-only-inside rule.
+- **Diagrams:** Mermaid in a `[source,mermaid]` listing block delimited by `----` — GitHub
+  renders it like a Markdown `mermaid` fence; the C4 notation is unchanged. Not `[mermaid]` blocks (asciidoctor-diagram)
+  and no STEM: GitHub renders neither.
+- **No `include::`** in a generated page — GitHub does not resolve it, and an agent reading
+  the raw file would see the directive instead of the content. Each page reads whole on its
+  own, and no Markdown copy is kept beside it: two sources drift.
+- **Tables** use `|===` blocks; the FR/NFR columns are unchanged.
+
 ## Re-runs
 - **Reader prose is sacred.** Rewrite only inside a section's `geneseed:doc` fences. A
   document that already exists **without** fences (a hand-written `PRD.md`, say) is never
@@ -159,12 +223,17 @@ only that block, add the project sections below it.
 ## Done when
 - Every selected doc-set member exists, follows its template, and cites its evidence or
   carries `⚠`; the batch of `⚠` questions has been put to the user.
-- The doc home mirrors the current implementation: every markdown page carries typed
-  frontmatter, wraps its generated sections in `geneseed:doc` markers, and is verified against
+- The doc home mirrors the current implementation: every page carries typed frontmatter
+  (header attributes in AsciiDoc mode), wraps its generated sections in `geneseed:doc` markers, and is verified against
   the code or flagged; examples run, Mermaid fences are well-formed, and the index links
   them all.
 - `overview.html` opens offline and shows the digest, the complex-core deep-dives, and the
   doc set; `design.html` does too wherever `DESIGN.md` exists; and any surface left
   undocumented is named explicitly.
+- `AGENTS.md` records the `Docs format:` line.
+- In AsciiDoc mode, every page written passes `asciidoctor --failure-level=WARN -o - <page>`
+  (output discarded) when `asciidoctor` is on PATH. Without it, the report says
+  `asciidoctor lint: SKIPPED — not installed` — never silently passed over, never installed
+  for the user.
 
 <!-- INCLUDE: skills/_self-improvement.md -->