@aperant/framework 0.6.7 → 0.7.3

package/dist/plugin/skills/apt-debug/SKILL.md

@@ -21,6 +21,19 @@ gates: []
 ---
 <objective>
 Debug an issue using the scientific method: observe symptoms, form hypotheses, test them systematically, and reach a conclusion. State persists across context resets via `.aperant/debug/{session-id}/DEBUG.md`.
+
+**Diagnose-discipline posture loader (Pocock adoption AC10).** You MUST
+load `appendices/diagnose-discipline.md` into reasoning context at
+session start. It carries the 6-phase loop (Reproduce → Minimise →
+Hypothesise → Instrument → Fix → Regression-test) and the **Phase-1
+prerequisite** constraint: do NOT advance from Observe (Section 2) to
+Hypothesize (Section 3) until DEBUG.md records `repro_loop_verified:
+true`. The appendix carries the rationale, the anti-pattern list
+(sprint-to-hypothesis, stack-trace cargo cult, test-the-fix-not-the-bug,
+logging-without-minimising), and the distinction between Phase 1
+"reproduce" and Phase 2 "minimise". Open question #1 was verified —
+apt:debug's existing Section 2 conflates symptom-gathering with
+reproduction, so loading this appendix is non-trivial.
 </objective>
 
 <your_environment>
@@ -59,18 +72,38 @@ mkdir -p .aperant/debug/{session-id}
 mkdir -p .aperant/debug/{session-id}/checkpoints
 ```
 
-## 2. Observe — Gather Symptoms
+## 2. Observe — Gather Symptoms + Phase 1 (Reproduce — prerequisite)
+
+Collect all available evidence about the bug, then establish a
+**reliable repro loop as a hard prerequisite** before advancing to
+Section 3 (Hypothesize). The Phase-1-reproduce constraint comes from
+`appendices/diagnose-discipline.md` and is load-bearing — you do NOT
+emit any hypothesis until DEBUG.md records `repro_loop_verified: true`.
 
-Collect all available evidence about the bug:
+Sub-steps (the existing 4 + 1 prerequisite check):
 
 1. **User description:** Extract from `$ARGUMENTS` what the issue is
 2. **Error output:** If the user provided error messages, record them verbatim
-3. **Reproduce:** Attempt to reproduce the issue:
-   - Run relevant test commands
-   - Check logs, console output
-   - Identify the exact failure point
+3. **Phase 1 — Reproduce (prerequisite, per appendices/diagnose-discipline.md):**
+   Establish a reliable repro loop. The loop MUST be:
+   - Deterministic (same input → same failure)
+   - Cheap (under 10 seconds preferred; certainly under 60)
+   - Minimal (no irrelevant setup; just enough to fail)
+   Record the repro command + verification in DEBUG.md as
+   `repro_command: "..."` and `repro_loop_verified: true`. If you
+   cannot reproduce reliably, do NOT proceed to Section 3 — instead,
+   loop here: gather more environment context, add logging to the
+   target environment, ask the user for repro details. Hypothesis-driven
+   debugging without a reliable repro is just hope, dressed up as
+   method.
 4. **Context:** Note environment details (branch, recent commits, dependencies)
 
+After Phase 1 succeeds, run **Phase 2 — Minimise** (also from the
+appendix): strip the repro to the smallest case that still fails.
+Record the minimised repro in DEBUG.md as `minimised_repro: "..."`.
+Phase 2 prevents Sections 3-5 from anchoring on the first plausible
+cause inside a 200-line repro.
+
 ```bash
 git log --oneline -10
 git diff --stat

package/dist/plugin/skills/apt-debug/appendices/diagnose-discipline.md

@@ -0,0 +1,119 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/diagnose
+Licensed under MIT. Modifications: ported as an apt:debug posture loader
+so the 6-phase loop attaches to the existing 5-phase apt:debug body
+without forking apt:debug's control flow. Aligned with apt:debug's
+DEBUG.md state file and checkpoint conventions.
+-->
+
+# Diagnose Discipline — apt:debug posture loader (6-phase loop)
+
+This appendix loads into `apt:debug`'s reasoning context as a posture
+upgrade. The existing apt:debug body has 5 phases (Observe → Hypothesize
+→ Checkpoint → Test → Conclude) but its Section 2 "Observe" conflates
+symptom-gathering with reproduction. Open question #1 was verified — the
+gap is real, the appendix is non-trivial.
+
+This appendix carries the 6-phase Pocock discipline. The skill body
+loads it and uses Phase 1 (Reproduce) as a **hard prerequisite** before
+advancing from Observe to Hypothesize.
+
+## The 6-phase loop
+
+1. **Reproduce.** Establish a reliable repro loop. Until you can
+   trigger the bug at will, no hypothesis is testable — you'd be
+   guessing about a moving target. The loop MUST be:
+   - Deterministic (same input → same failure)
+   - Cheap (under 10 seconds preferred; certainly under 60)
+   - Minimal (no irrelevant setup; just enough to fail)
+
+2. **Minimise.** Once you can repro, strip the repro to the smallest
+   case. Remove every component that isn't load-bearing for the
+   failure. A 200-line repro is a hypothesis space; a 10-line repro is
+   a near-confirmed cause.
+
+3. **Hypothesise.** ONLY after minimise: write 3-5 ranked falsifiable
+   hypotheses. Each hypothesis must:
+   - Predict an observable consequence
+   - Be testable by changing ONE variable
+   - Be ordered by prior probability + cost-to-test
+
+4. **Instrument.** Add the minimum logging / breakpoint / probe to test
+   the highest-ranked hypothesis. Change ONE variable. Re-run the
+   minimal repro. Observe.
+
+5. **Fix.** When a hypothesis confirms, write the fix. Run the minimal
+   repro again — it must now PASS (no more failure). Run the full test
+   suite — no new regressions.
+
+6. **Regression-test.** Write a test that pins the fix. The test must
+   fail on the pre-fix code and pass on the fixed code. This is what
+   stops the bug from coming back six months later when someone
+   refactors.
+
+## The Phase-1 prerequisite (load-bearing)
+
+apt:debug's body enforces this constraint: **you do NOT advance from
+Observe to Hypothesize until Phase 1 produces a reliable repro loop**.
+
+If you cannot reproduce reliably:
+
+- Spend the budget on getting the repro working before guessing causes
+- Add logging in the production / target environment to gather more
+  evidence of the failure trigger
+- Ask the user for more context (when does it happen? on what input?
+  intermittent or consistent?)
+
+It is better to spend 80% of your debug budget on the repro and 20% on
+the fix than to spend 100% guessing at causes. Hypothesis-driven
+debugging without a reliable repro is just hope, dressed up as method.
+
+## Distinguishing Phase 1 from apt:debug's existing "Observe"
+
+apt:debug's existing Section 2 collects symptom evidence (error
+messages, user reports, environment). That's still valuable — it's the
+*input* to Phase 1. But "I read the error and inferred the cause"
+DOES NOT count as a repro. The repro is a callable artifact: a
+command-line invocation, a test, a script — something the agent can
+run on demand to trigger the failure.
+
+## Distinguishing Phase 2 (Minimise) from Phase 3 (Hypothesise)
+
+These are different mental modes. Minimise asks "what's the smallest
+thing that still fails?" — a reductive activity. Hypothesise asks
+"WHY does it fail?" — an explanatory activity. Pocock's discipline
+separates them because skipping Phase 2 and going straight from "I can
+repro" to "here's why" tends to anchor on the first plausible cause
+and miss alternatives.
+
+## Practical consequence for the apt:debug body
+
+When this appendix is loaded, apt:debug's Section 2 (Observe) renames
+its "Reproduce" sub-step to **Phase 1 (Reproduce — prerequisite)** and
+adds a gate: the skill MUST NOT emit any hypothesis (Section 3) until
+DEBUG.md records a `repro_loop_verified: true` field.
+
+The appendix's Phase 2 (Minimise) becomes a new sub-section between
+apt:debug's Section 2 (Observe) and Section 3 (Hypothesize). DEBUG.md
+gains a `minimised_repro` field.
+
+apt:debug's Sections 3-5 (Hypothesize / Checkpoint / Test / Conclude)
+align with Phases 3-6 of this appendix; no structural change there.
+
+## Anti-patterns this discipline prevents
+
+- **Sprint-to-hypothesis.** Agent reads the error, picks the first
+  plausible cause, writes a fix, and ships. The bug comes back two
+  days later under different inputs.
+- **Stack-trace cargo cult.** Agent assumes the line at the top of the
+  stack trace IS the bug. Often it's an effect, not a cause.
+- **Test the fix, not the bug.** Agent writes a test that proves the
+  fix works but doesn't exercise the original buggy condition. The
+  regression test is a no-op against the future regression.
+- **Logging without minimising.** Agent adds 50 log lines in a 200-line
+  repro, then drowns in noise. Minimise first; THEN instrument the
+  minimal repro.
+
+Loading this appendix and following its Phase 1 prerequisite cuts most
+of these failure modes by structural constraint.

package/dist/plugin/skills/apt-diagram/SKILL.md

@@ -0,0 +1,378 @@
+---
+name: apt:diagram
+description: "Generate .excalidraw or MCP-canvas diagrams"
+apt-skill-version: {{APT_VERSION}}
+stage: design
+intent: design
+when_to_use: "The user wants to generate a diagram from a prompt — system architecture sketch, flowchart, data-flow picture. Produces either a local .excalidraw file (default) or a live Excalidraw MCP canvas."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: self-managed
+# default_track omitted — self-managed skill, router does not consult this field
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Read, Write, Edit, Bash, Grep, Glob"
+argument-hint: "apt:diagram [prompt] [--mode=file|--mode=mcp] [--depth=default|comprehensive]"
+gates: []
+---
+
+<objective>
+Turn a natural-language prompt into a diagram. The skill splits the
+work into two phases: (1) the agent itself produces a `DiagramScene`
+JSON (a minimal graph of labelled `nodes` and directed `edges`) from
+the user prompt, and (2) a deterministic renderer turns that scene
+into Excalidraw geometry — either a local `.excalidraw` file under
+`docs/diagrams/<slug>.excalidraw` or a live canvas via the Excalidraw
+MCP server.
+
+There are exactly two render modes — `file` (offline, default) and
+`mcp` (live canvas). There is no `auto` mode and no automatic
+degradation between them: if the chosen renderer fails, the skill
+hard-errors with a message telling the user to re-run with the other
+mode. This is intentional in v1 — diagnostics over magic.
+</objective>
+
+<process>
+
+## 1. Parse arguments
+
+`$ARGUMENTS` may contain free-text prompt material plus at most one
+`--mode=<value>` flag and at most one `--depth=<value>` flag. Extract the
+prompt by removing any flags (if present) and trimming. Extract each
+flag value if any.
+
+- If a `--mode=...` flag is present and its value is anything other
+  than `"file"` or `"mcp"`, emit a hard error of the exact shape:
+  `Unknown --mode value: <value>. Expected file or mcp.` and exit.
+- Empty prompt → emit `apt:diagram requires a prompt describing what to draw.` and exit.
+- If a `--depth=...` flag is present and its value is anything other
+  than `"default"` or `"comprehensive"`, emit a hard error of the exact
+  shape: `Unknown --depth value: <value>. Expected default or comprehensive.`
+  and exit. The default value when absent is `default`. When the value
+  is `comprehensive`, before generating the scene in Step 3 load
+  `appendices/design-discipline.md` into reasoning context (mirrors
+  apt:discuss's `appendices/grill-discipline.md` load pattern). The flag
+  is per-call only — it is NOT persisted to `.aperant/config.json`.
+
+## 2. Resolve mode
+
+Resolution order: --mode flag > .aperant/config.json#diagram.mode > "file" default
+
+Read `.aperant/config.json` and look for `diagram.mode`. The lookup
+runs through the same in-skill Node one-liner pattern apt:quick uses
+for `preferences.quick_task_post_verify` (see apt-quick/SKILL.md
+Step 8):
+
+```bash
+node -e '
+  const fs = require("fs");
+  const path = require("path");
+  const cfgPath = path.join(process.cwd(), ".aperant/config.json");
+  let mode = "file"; // default
+  try {
+    const cfg = JSON.parse(fs.readFileSync(cfgPath, "utf-8"));
+    if (cfg && cfg.diagram && (cfg.diagram.mode === "file" || cfg.diagram.mode === "mcp")) {
+      mode = cfg.diagram.mode;
+    }
+  } catch {}
+  // The flag override (if present) is layered on top in the agent step,
+  // not in this snippet — this only reads the persisted default.
+  process.stdout.write(mode);
+'
+```
+
+If the user passed `--mode=file` or `--mode=mcp`, that wins
+unconditionally over whatever the file says — the flag is a one-call
+override and is not persisted to config.
+
+## 3. Generate a `DiagramScene`
+
+The agent itself produces a JSON object of shape:
+
+```json
+{
+  "nodes": [{ "id": "<stable-id>", "label": "<short-label>", "x": <number>, "y": <number> }, ...],
+  "edges": [{ "from": "<id>", "to": "<id>", "label": "<optional>" }, ...]
+}
+```
+
+Constraints the agent MUST honour while producing the scene:
+
+- **Stable string ids.** Every node has a short, stable `id` (lowercase
+  kebab works well — `auth-service`, `db`, `cdn`). Edges reference
+  these ids in `from`/`to`. NEVER use positional ids like `n0`/`n1`.
+- **Endpoint validity.** Every `edge.from` and `edge.to` MUST appear in
+  the `nodes` array. The renderer hard-errors on a missing endpoint
+  with `DiagramScene edge references unknown node id: <id>` — that is
+  a failure of scene generation, not a renderer bug, so the agent
+  MUST validate this before dispatching to the renderer.
+- **Coordinates.** Use a rough grid to avoid overlap — e.g. 200px
+  horizontal spacing between sibling nodes, 150px vertical between
+  layers. Nodes default to ~180x70 px in the renderer; keep ≥200px
+  centre-to-centre.
+- **Scope.** v1 has no groups, containers, or layout constraints.
+  Don't invent extra fields — the renderer ignores them at best,
+  rejects the scene at worst.
+
+## 4. File mode — dispatch to `renderToFile`
+
+When the resolved mode is `file`:
+
+1. Derive a slug from the prompt by calling `deriveSlug(prompt)` from
+   `@aperant/core/workflows/diagram`. The slug becomes the filename
+   under `docs/diagrams/<slug>.excalidraw`.
+2. Invoke `renderToFile({ scene, slug, projectDir })` via a small Node
+   invocation — same precedent as apt:design Step 3 ("invoke the
+   library entry point via a small Node invocation"). The agent
+   serialises the scene into the command via a temp file or
+   `JSON.stringify`-ed env var:
+
+   ```bash
+   node -e '
+     import("@aperant/core/workflows/diagram").then(async (m) => {
+       const scene = JSON.parse(process.env.APT_DIAGRAM_SCENE);
+       const slug = m.deriveSlug(process.env.APT_DIAGRAM_PROMPT || "diagram");
+       const result = await m.renderToFile({
+         scene,
+         slug,
+         projectDir: process.cwd(),
+       });
+       process.stdout.write(result.absolutePath);
+     }).catch((err) => {
+       process.stderr.write("renderToFile failed: " + err.message + "\n");
+       process.exit(1);
+     });
+   '
+   ```
+
+   Pass the scene as `APT_DIAGRAM_SCENE` env (JSON-encoded) and the raw
+   prompt as `APT_DIAGRAM_PROMPT`. The wrapper prints the absolute path
+   to stdout on success.
+
+3. On success, print to the user:
+
+   ```
+   Diagram written to <absolutePath>. Open it in Excalidraw (drag-drop the file into excalidraw.com or open via Aperant's Excalidraw integration).
+   ```
+
+   Relative path under the project: `docs/diagrams/<slug>.excalidraw`.
+
+4. On failure (any `Error` thrown from `renderToFile`, including the
+   `unknown node id` validation case), surface the message to the user
+   verbatim with no retry and no fallback. Keep the generated scene
+   JSON visible in the chat so the user can inspect what was
+   produced — that is the diagnostic.
+
+## 5. MCP mode — consent gate + renderer dispatch
+
+When the resolved mode is `mcp`, the skill runs three sub-steps in
+order: (a) consent gate, (b) renderer dispatch, (c) failure handling.
+
+### 5a. Consent gate
+
+Per FRAMEWORK-AUDIT-001, `mcpConsent` is per-user state and lives in
+`.aperant/config.local.json` (gitignored), NOT the shared
+`.aperant/config.json`. The `diagram.mode` field stays in `config.json` as
+team policy. Read the MERGED config (config.json deep-merged with
+config.local.json — local wins on collision) and look at
+`diagram.mcpConsent` via the same in-skill `node -e` pattern Step 2 uses:
+
+```bash
+node -e '
+  const fs = require("fs");
+  const path = require("path");
+  const aperantDir = path.join(process.cwd(), ".aperant");
+  function readJson(p) {
+    try { return JSON.parse(fs.readFileSync(p, "utf-8")); } catch { return null; }
+  }
+  const shared = readJson(path.join(aperantDir, "config.json")) || {};
+  const local = readJson(path.join(aperantDir, "config.local.json")) || {};
+  // Deep-merge — local wins on collision; matches loadMergedProjectConfig semantics.
+  function merge(a, b) {
+    if (a === null || typeof a !== "object" || Array.isArray(a)) return b;
+    if (b === null || typeof b !== "object" || Array.isArray(b)) return b;
+    const out = { ...a };
+    for (const k of Object.keys(b)) out[k] = (k in a) ? merge(a[k], b[k]) : b[k];
+    return out;
+  }
+  const cfg = merge(shared, local);
+  const consent = cfg && cfg.diagram ? cfg.diagram.mcpConsent : null;
+  process.stdout.write(JSON.stringify(consent || null));
+'
+```
+
+The shape is:
+
+```json
+{ "host": "<host string>", "decision": "granted" | "denied", "grantedAt": "<ISO 8601 timestamp>" }
+```
+
+or `null` if no decision has ever been recorded.
+
+Determine the "configured MCP host" from the connected Excalidraw MCP
+server. The skill does NOT manage MCP server installation — it reads
+the host name from whatever `mcp__excalidraw__*` namespace is already
+present on the agent's tool surface. (For most setups the host is
+something like `mcp.excalidraw.com` or a self-hosted URL — use
+whatever the surface reports.)
+
+Decide whether to prompt:
+
+- If `diagram.mcpConsent` is `null` → prompt.
+- If `diagram.mcpConsent.host !== <configured MCP host>` → prompt.
+- If `diagram.mcpConsent.host === <configured MCP host>` AND `diagram.mcpConsent.decision === "denied"` → hard-error immediately with the exact denied text (no re-prompt):
+  ```
+  diagram MCP consent denied; re-run with `--mode=file` or change diagram.mcpConsent in .aperant/config.local.json
+  ```
+- Otherwise (host matches AND decision is `"granted"`) → the existing consent applies; proceed to 5b.
+
+When prompting, print a single line naming the host and ask `granted / denied`:
+
+```
+apt:diagram is about to send diagram data to the Excalidraw MCP server at <host>. Type `granted` to allow, `denied` to refuse.
+```
+
+Read one line of input. Persist the decision to
+`.aperant/config.local.json` (NOT `config.json` — `mcpConsent` is per-user
+state per FRAMEWORK-AUDIT-001; the local file is gitignored). The
+read-mutate-write JSON pattern targets the local file only:
+
+```bash
+node -e '
+  const fs = require("fs");
+  const path = require("path");
+  const cfgPath = path.join(process.cwd(), ".aperant/config.local.json");
+  const decision = process.env.APT_DIAGRAM_DECISION; // "granted" | "denied"
+  if (decision !== "granted" && decision !== "denied") {
+    process.stderr.write("invalid decision\n");
+    process.exit(1);
+  }
+  const host = process.env.APT_DIAGRAM_HOST;
+  let cfg = { diagram: { mcpConsent: null } };
+  try { cfg = JSON.parse(fs.readFileSync(cfgPath, "utf-8")); } catch {}
+  cfg.diagram = cfg.diagram || { mcpConsent: null };
+  cfg.diagram.mcpConsent = {
+    host,
+    decision,
+    grantedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+'
+```
+
+Note: the write target above is `config.local.json` (gitignored, per-user).
+The shared `config.json` is not touched — `diagram.mode` lives there and
+stays team-shared policy.
+
+If the decision is `"denied"`, exit with EXACTLY this text (verbatim,
+no rewording, no extra punctuation):
+
+```
+diagram MCP consent denied; re-run with `--mode=file` or change diagram.mcpConsent in .aperant/config.local.json
+```
+
+If the decision is `"granted"`, proceed to 5b.
+
+### 5b. Renderer dispatch
+
+The skill IS the MCP renderer — there is no shared TS module here. The
+agent dispatches MCP tool calls directly:
+
+1. Iterate `scene.nodes` FIRST. For each node, call the Excalidraw MCP
+   `create_element` tool (expected name `mcp__excalidraw__create_element`;
+   if the connected server exposes a different equivalent, use that
+   discovered name) with rectangle parameters: position from
+   `node.x`/`node.y`, default size 180x70, and the `node.label` as
+   text content. Record the element id the MCP server returns.
+2. Then iterate `scene.edges`. For each edge, call the same tool with
+   arrow parameters, setting `startBinding.elementId` to the rectangle
+   id created for `edge.from` and `endBinding.elementId` to the
+   rectangle id created for `edge.to`. If `edge.label` is set, pass it
+   as the arrow's label.
+
+Nodes MUST be created before edges so the edge bindings have valid
+element ids on both ends.
+
+On success, surface whatever stable identifier the MCP server returned
+(session id, canvas URL, or scene id) so the user can open the live
+canvas — e.g. `Live canvas: <url>`.
+
+### 5c. Failure handling
+
+If ANY `mcp__excalidraw__*` tool call fails — tool error, transport
+error, or the expected tool is missing from the surface — emit EXACTLY
+this message (verbatim) and exit:
+
+```
+Excalidraw MCP renderer failed: <reason>. Re-run with `--mode=file` to generate an offline .excalidraw file.
+```
+
+No retries. No automatic switch to file mode. No partial cleanup of
+already-created MCP elements (v1 leaves them as a debugging artifact;
+v2 may add cleanup).
+
+## 7. Quality pass loop (file mode only)
+
+(Step 6 is intentionally reserved for future MCP-side quality work; v2
+ships Step 7 for file mode only.)
+
+After Step 4 (file written), if Playwright is installed, run a visual
+quality-pass loop. The loop is capped at **3 iterations**. If
+`validateScene(scene).score >= 70` AND the vision review reports no
+critical issues, exit early.
+
+### 7a. Detect Playwright
+
+Probe with:
+
+```bash
+node -e 'import("playwright").then(() => process.stdout.write("yes"), () => process.stdout.write("no"))'
+```
+
+If the result is `no`, skip Step 7 silently and append the following
+one-line tip to the success message printed in Step 4:
+
+```
+Tip: install playwright to enable visual quality-pass on future runs (pnpm add -D playwright && npx playwright install chromium).
+```
+
+### 7b. Loop body (max 3 iterations)
+
+For each iteration `i` in `0..2`:
+
+1. Call `renderToPng({ excalidrawPath })` from `@aperant/core/workflows/diagram`
+   via the same Node-invocation pattern Step 4 uses. Capture the
+   absolute PNG path.
+2. Call `validateScene(scene)` from the same module. Capture
+   `{warnings, score}`.
+3. Read the PNG via the `Read` tool (multimodal vision review).
+4. Decide:
+   - If `score >= 70` AND the vision review reports no critical issues
+     (overlaps, off-canvas elements, illegible text), exit the loop
+     and return success.
+   - Else: emit IR patches as a JSON delta. Mutable fields are
+     exactly `DiagramNode.x`, `DiagramNode.y`, and `DiagramNode.label`.
+     Apply the patches to `scene`, re-call `renderToFile` (re-using
+     the slug from Step 4), and continue to the next iteration.
+5. After 3 iterations: return final state. If unresolved warnings
+   remain, print exactly:
+
+```
+Quality pass: <N> warning(s) remain after 3 iterations. See <png-path> to inspect.
+```
+
+### 7c. Hard rules
+
+- Iteration cap is exactly **3** (hard-coded, not configurable in v2).
+- Score threshold is exactly **70** (hard-coded, not configurable in v2).
+- Patch grammar is `{x, y, label}` — no other `DiagramNode`/
+  `DiagramEdge` fields are mutable.
+- If `renderToPng` throws `DiagramMissingDep`, treat the same as Step
+  7a's `no` branch (silent skip + tip). Any OTHER `renderToPng` error
+  fails the loop and surfaces verbatim to the user.
+
+</process>

package/dist/plugin/skills/apt-diagram/appendices/design-discipline.md

@@ -0,0 +1,97 @@
+# apt:diagram — design-discipline appendix
+
+Loaded into `apt:diagram`'s reasoning context when the skill is invoked
+with `--depth=comprehensive`. Aperant-authored — not a verbatim port. The
+goal: emit a diagram that earns its space on the page, not a free-floating
+box graph that "looks like a diagram."
+
+This appendix is a posture loader. It does not change the IR. It changes
+what the agent decides to put *in* the IR.
+
+## Visual pattern library
+
+Excalidraw exposes rectangles, ellipses, diamonds, arrows, text, and
+free-form shapes. When you have a choice, the shape should encode
+information the label can't:
+
+- **Rectangle** — a unit of work, a service, a process, a system
+  component. Default for "this is a thing that exists." The boring,
+  honest shape.
+- **Ellipse** — a state, a phase, a "moment in time." Use when the noun
+  is more like a place a flow visits than a thing that owns state.
+- **Diamond** — a decision point, a branching condition. If the
+  outgoing arrows have different semantics ("yes" / "no" / "retry"),
+  the source should be a diamond.
+
+v2 only emits rectangles. The IR has no `shape` field on `DiagramNode`,
+and `renderToFile` hard-codes rectangle elements. The choice above is
+informational — it tells you *what richer shapes would mean* so you can
+note the missing semantics in the diagram's accompanying prose if a
+node really wants to be a diamond. Richer shapes are scheduled for v3.
+
+## Isomorphism test
+
+The diagram should be *the same shape* as the thing it depicts.
+
+If the system has three layers (edge / app / data), the diagram has
+three visually-distinct horizontal zones. If the system has a single
+hub that talks to four leaves, the diagram has a single central node
+with four spokes — not five nodes in a line.
+
+Concretely:
+
+- Count the "structural axes" in the thing being depicted. Layers?
+  Phases? Owners? Each axis should map to a visual axis (vertical /
+  horizontal / radial) in the diagram.
+- If you cannot draw the structural axis, the diagram is lying. Either
+  add the missing axis or admit you're depicting a different thing.
+- Symmetry in the system should appear as symmetry in the layout.
+  Asymmetry is a flag — either it's load-bearing (good — show it) or
+  it's noise (bad — fix it).
+
+The `validateStructure` validator codifies one slice of this: it checks
+that nodes occupy the top / middle / bottom thirds of the canvas in
+roughly the expected counts. That's a weak proxy — the real check is in
+your eyes.
+
+## Depth assessment
+
+Every diagram answers one of two questions: **what** or **what + how**.
+
+- A **what** diagram shows the inventory of things and the connections
+  between them. "These are the services. They talk to each other."
+  v2 targets this depth.
+- A **what + how** diagram additionally encodes the protocol on each
+  connection — request shape, retry policy, idempotency key, transport.
+  This often requires labels on every edge, sub-groups around clusters
+  of services, and sometimes a second pass at a different zoom level.
+  v2 does not target this. The IR has no edge-protocol field.
+
+Before generating the scene, decide which question the diagram answers.
+If the user prompt implies "what + how" and you can only render "what,"
+say so in the chat so the user knows they're getting the shallower
+picture.
+
+## Multi-zoom architecture
+
+A real system has multiple zoom levels:
+
+- **Far zoom** — one diagram showing the 4-7 top-level components and
+  their primary connections. Fits on a slide.
+- **Mid zoom** — one diagram per top-level component, showing its
+  internal modules. 4-7 boxes each, again.
+- **Near zoom** — one diagram per critical interface, showing the
+  protocol/sequence.
+
+v2 generates one diagram per `apt:diagram` invocation. If a user prompt
+implies a multi-zoom set ("system architecture for the auth flow,"
+where "the auth flow" is itself worth a deeper drawing), the agent
+should:
+
+1. Generate the far-zoom diagram for v2.
+2. State in the chat that a mid-zoom diagram for the named subsystem
+   would be a natural follow-up.
+3. NOT chain a second `renderToFile` call automatically.
+
+The default is one diagram per prompt. Multi-zoom orchestration is a
+v3 problem.