@aperant/framework 0.6.4 → 0.6.6

package/skills/apt-diagram/SKILL.md

@@ -0,0 +1,342 @@
+---
+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
+
+Read `.aperant/config.json` and look at `diagram.mcpConsent`. 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.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 back to
+`.aperant/config.json` with a read-mutate-write JSON pattern:
+
+```bash
+node -e '
+  const fs = require("fs");
+  const path = require("path");
+  const cfgPath = path.join(process.cwd(), ".aperant/config.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: { mode: "mcp", mcpConsent: null } };
+  try { cfg = JSON.parse(fs.readFileSync(cfgPath, "utf-8")); } catch {}
+  cfg.diagram = cfg.diagram || { mode: "mcp", mcpConsent: null };
+  cfg.diagram.mcpConsent = {
+    host,
+    decision,
+    grantedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+'
+```
+
+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.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/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.

package/skills/apt-discuss/SKILL.md

@@ -46,6 +46,31 @@ never by asking:
 These are two postures of the same skill, not two different skills. The
 intent-detection step below decides which one to enter — same file, same
 artifact layout, different section populated.
+
+**Decision-lock posture loader (Pocock adoption ID-02 + ID-04 — AC11).**
+When entering decision-lock posture, you MUST load
+`appendices/grill-discipline.md` into reasoning context. It carries the
+validated 100-token reframe sentence ("Your job is not to emit a plan;
+your job is to resolve the design tree until planning is mechanical.")
+and the autonomy-aware degradation table (Autonomy 1 grills everything;
+Autonomy 2 batches recommendations; Autonomy 3 auto-locks with three
+escalation triggers — conflict with prior locked decision, critical-path
+file touched, or no defensible default). This appendix is the canonical
+source for the autonomy-aware rule; downstream skills (`apt:improve`,
+`apt:triage`) reference it rather than re-stating the policy. Brainstorm
+posture does NOT load this appendix.
+
+**Brainstorm posture zoom-out helper (Pocock adoption AC6 + AC11).**
+When in brainstorm posture and the user's turn contains a zoom-out
+trigger phrase ("give me a broader picture", "I'm lost in this area",
+"explain how this fits", "what's the surrounding architecture", "zoom
+out from X"), load `appendices/zoom-out-helper.md` and follow its
+3-6-line compressed orientation pattern. The brainstorm posture stays
+active — this is an augmentation, not a pivot. The full router-invocable
+`/apt:zoom-out` skill is the right answer when the user invokes it
+explicitly; this helper is the right answer when the request surfaces
+inside an active brainstorm discussion. Decision-lock posture does NOT
+load this helper (orientation is descriptive, not normative).
 </objective>
 
 <your_environment>

package/skills/apt-discuss/appendices/grill-discipline.md

@@ -0,0 +1,104 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs
+Licensed under MIT. Modifications: ported as an apt:discuss posture loader,
+extended with the validated 100-token reframe sentence and the
+autonomy-aware degradation table from the Pocock adoption brainstorm
+(Architectural principles to lock §2).
+-->
+
+# Grill Discipline — apt:discuss posture loader
+
+This appendix loads into `apt:discuss`'s reasoning context whenever the
+skill is invoked in decision-lock posture (or as a sub-step inside
+`apt:improve` / `apt:triage`'s grill loop). It carries two load-bearing
+artifacts:
+
+1. The 100-token **reframe sentence** validated by the V2 grill-comparison
+   experiment (43/44 vs 38/44 blind-judge score against Pocock's verbatim
+   `grill-with-docs`).
+2. The **autonomy-aware degradation table** that prevents full-auto runs
+   from grinding to a halt grilling every gray area.
+
+## The reframe sentence (validated, 43/44 vs 38/44)
+
+> **Your job is not to emit a plan; your job is to resolve the design
+> tree until planning is mechanical.**
+
+This sentence is the *first thing* you load into your reasoning context
+when entering decision-lock posture. It does two things at once:
+
+- It refuses the "I'll just emit a plan and let the executor figure
+  out the gaps" anti-pattern. Plans with unresolved gray areas push the
+  cost into execution where rollbacks are 10× more expensive.
+- It frames the goal as *resolving a design tree*, not *answering a
+  questionnaire*. The interview-style "ask the user 47 clarifying
+  questions" is the failure mode this reframe blocks.
+
+The empirical V1 + V2 evidence is in
+`.aperant/experiments/grill-comparison-20260513/SUMMARY-FOR-AGENT-REVIEW.md`.
+
+## Autonomy-aware degradation table (load-bearing)
+
+The grill discipline runs at every autonomy level — the *interaction
+shape* degrades, not the discipline itself. This is the canonical
+source for this rule; new skills (apt:improve, apt:triage) reference
+THIS table rather than re-stating the policy.
+
+| Autonomy | Mode | Behavior |
+|---|---|---|
+| **1 (Supervised)** | Grill everything | Ask the user for every load-bearing decision. The user reviews each Q&A turn before the next one fires. |
+| **2 (Balanced / Semi)** | Batch-recommend | Auto-recommend per decision; collect all recommendations into a single batch the user reviews at the end. This is the existing `--review-auto` pattern. |
+| **3 (Full auto / YOLO)** | Auto-lock with escalation triggers | Auto-recommend and lock decisions silently. Escalate to the user only when one of THREE triggers fires (below). |
+
+## The three escalation triggers (Autonomy 3 only)
+
+At Autonomy 3, the agent locks recommendations silently — **EXCEPT** when:
+
+1. **Conflict with a prior locked decision.** The new recommendation
+   contradicts a decision already written to
+   `.aperant/context/notes/{task-id}.md` (or any other notes file under
+   `.aperant/context/notes/`). Re-litigating a locked decision needs
+   human sign-off.
+2. **Critical-path file touched.** The decision's downstream effect
+   modifies a file matching a glob in
+   `.aperant/config.json.risk_map.critical_paths` (e.g., auth, billing,
+   migration paths). Critical-path changes always escalate at every
+   autonomy level — this trigger is the autonomy-3 surface for the same
+   policy.
+3. **No defensible default exists.** Neither AGENTS.md nor an existing
+   codebase pattern provides a defensible answer. "Just pick one" is
+   not a defensible default; the agent must say "I see two viable
+   paths and no precedent — which do you want?"
+
+These three triggers cover the cases where a silent auto-lock would
+cause real harm. Everything else gets locked, logged, and surfaced in
+the final report only — not as a blocking prompt.
+
+## Practical consequence for new skills
+
+When `apt:improve`'s deepening loop, `apt:triage`'s priority resolution,
+or any other agent reaches a gray area:
+
+- It loads THIS appendix into reasoning context.
+- It reads the current autonomy from `.aperant/config.json` (or the
+  per-task autonomy from `apt-tools task get`).
+- It enters the matching row of the degradation table.
+- At Autonomy 3, it walks the three triggers before deciding to lock or
+  escalate.
+
+The "ask first vs lock first" decision is NOT a per-skill policy.
+Reasoning lives here; every grill-loop-bearing skill references it.
+
+## When NOT to load this appendix
+
+This appendix is for **decision-lock** posture (convergent discussion
+where the user has a concrete task with implicit gray areas). The
+**brainstorm** posture (divergent — user has a rough vision, exploring
+options) does NOT load this appendix; brainstorm has its own posture
+encoded in apt:discuss's `<objective>` block.
+
+`apt:zoom-out` (a sibling skill, also Pocock-adopted) does NOT load
+this appendix. Zoom-out is descriptive ("show me the broader picture"),
+not normative ("lock this decision"). Loading grill-discipline there
+would mis-fire the reframe sentence on a read-only operation.

package/skills/apt-discuss/appendices/zoom-out-helper.md

@@ -0,0 +1,79 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/zoom-out
+Licensed under MIT. Modifications: ported as a loaded-helper for apt:discuss
+brainstorm mode so the discipline activates without spawning the full
+apt:zoom-out skill (the latter is a router-invocable verb on its own).
+-->
+
+# Zoom-Out Helper — apt:discuss brainstorm mode loaded helper
+
+This appendix loads into `apt:discuss` brainstorm mode when the user's
+turn contains a zoom-out trigger phrase. The full
+`/apt:zoom-out` skill (router-invocable) is the right answer when the
+user invokes it explicitly; this helper is the right answer when the
+zoom-out request surfaces *inside* a brainstorm discussion.
+
+## When to load this appendix
+
+Inside an active `apt:discuss --brainstorm` session, if the user's turn
+contains any of these phrases (or their natural-language variants):
+
+- "give me a broader picture"
+- "I'm lost in this area"
+- "explain how this fits"
+- "what's the surrounding architecture"
+- "zoom out from {topic}"
+
+…load this appendix into reasoning context and follow the helper
+process below. The brainstorm posture stays active — you don't pivot
+out of `apt:discuss`; you augment its reasoning with the orientation
+discipline.
+
+## Process (helper mode, not full skill)
+
+1. **Identify the area.** Pull the noun phrase from the user's message
+   (e.g., "the sparring engine"). If ambiguous, ask a single targeted
+   clarifying question — do NOT enter a 20-question interview.
+
+2. **Load CONTEXT.md term-blocks if matching.** Same as the full
+   `apt:zoom-out` skill: if the area name matches a term or alias in
+   `CONTEXT.md`, pre-load that term-block's definition + flagged
+   ambiguities into the orientation.
+
+3. **Emit a compressed orientation INLINE in the discussion.** Format:
+
+   > **Purpose:** {one sentence}
+   > **Entry points:** `{file1}`, `{file2}`
+   > **State owners:** `{file3}` ({what state})
+   > **External boundaries:** `{file4}` ({what external})
+   > **Watch out for:** {one-line fragile area}
+
+   Three to six lines. The full one-page `apt:zoom-out` report is
+   overkill when the user is mid-discussion — they want enough context
+   to keep brainstorming, not a separate artifact.
+
+4. **Resume brainstorm posture.** After the orientation block, ask:
+   "Want me to keep zooming, lock a decision, or stay in brainstorm?"
+   so the user explicitly drives whether to deepen.
+
+## When NOT to load this appendix
+
+- In decision-lock posture (the user wants to *resolve* a decision, not
+  *orient* themselves) — load `grill-discipline.md` instead.
+- When the user explicitly types `/apt:zoom-out` — they invoked the
+  full skill; let that skill run unmodified.
+- In `apt:plan` — the planner's Phase-0 codebase investigation already
+  covers orientation. Loading this helper there would duplicate work.
+
+## Relationship to the full apt:zoom-out skill
+
+| | `apt:discuss + zoom-out-helper` | `/apt:zoom-out` (full skill) |
+|---|---|---|
+| Invocation | Detected mid-brainstorm | User-explicit verb |
+| Output | 3-6 line inline orientation | One-page report |
+| Side effects | None | None (read-only) |
+| Posture after | Brainstorm continues | Skill exits — no continuation |
+
+Same underlying discipline; different surface shapes for different
+work contexts.