@iowarp/clio-coder 0.4.2 → 0.4.4

package/skills/planning/archify/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: archify
+description: "Validated interactive system maps and diagrams as standalone HTML from a typed JSON spec, for one of five diagram types (architecture, workflow, sequence, dataflow, lifecycle). Use when the user asks to visualize architecture, a workflow, a call sequence, a data pipeline, or a state machine, or to map this repository. Not for ad hoc drawings or slide art, and not for Mermaid output; use the artifact tool for plain Markdown."
+triggers:
+  - architecture diagram
+  - system map
+  - map this repository
+  - sequence diagram
+  - data flow diagram
+  - state machine diagram
+  - visualize the architecture
+version: 0.1.0
+license: MIT
+allowed-tools:
+  - bash
+  - read
+  - write
+  - edit
+  - ls
+  - grep
+  - find
+  - code_nav
+  - verify
+  - context
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/planning/archify
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/tt-a1i/archify/tree/v2.16.0/archify
+  eval-status: scenarios-recorded
+  model-size: any
+  agents:
+    - main
+    - architect
+    - documenter
+    - wiki-writer
+---
+
+# Archify
+
+Create a self-contained interactive HTML diagram from a small typed JSON
+specification. The renderer is the upstream archify package installed
+beside this file; the skill base directory is the directory that holds
+`bin/`. Every command below runs as
+`node .clio-coder/skills/archify/bin/archify.mjs ...` for a project-scope
+install, or `node <clio config dir>/skills/archify/bin/archify.mjs ...` for a
+user-scope install. No install step, no network, and no dependencies beyond
+Node 18 or later.
+
+## Fast authoring path
+
+1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle`
+   from the question. When ambiguous, run
+   `node <skill>/bin/archify.mjs guide "<scenario>" --json`.
+2. Read one matching schema in `schemas/`, `schemas/common.schema.json`, and
+   one matching example in `examples/`. Read only those files. The example
+   supplies field shape, never facts: author new stable ids, domain wording,
+   and layout. New workflows use `schema_version: 2`.
+3. Write the candidate JSON as the very next action. Do not plan coordinates
+   in prose. Start with one clear main path, short side branches, sparse
+   labels, and at most 12 primary nodes. Set `meta.quality_profile` to
+   `"showcase"` unless the user asks for a dense `standard` map. Start with
+   automatic routes and labels; add `via`, `channelX`, `channelY`, or
+   `labelAt` only when a diagnostic asks for one, and at most one per repair.
+4. Validate after every edit and immediately before delivery:
+
+   ```bash
+   node <skill>/bin/archify.mjs validate <type> <candidate.json> --quality showcase --json
+   ```
+
+   A showcase pass reports all artifact checks with 0 composition errors
+   and 0 warnings. If validation fails, change only the diagnosed `subject`,
+   verify `evidence`, choose from `supportedFixes`, and rerun. Stop and report
+   the unresolved diagnostics truthfully when two consecutive rounds do not
+   lower the error count.
+5. Deliver once, as the final acceptance command:
+
+   ```bash
+   node <skill>/bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
+   ```
+
+   A non-zero exit is never success. A failed delivery preserves any previous
+   output at that path.
+
+Do not read renderer, validator, or geometry source before the first
+candidate exists. Inspect implementation only for an unsupported internal
+diagnostic or after two focused repairs fail.
+
+## Type router
+
+| Type | Use for |
+|---|---|
+| `architecture` | Components, services, boundaries, infrastructure, repository maps |
+| `workflow` | Processes, approval gates, tool calls, runbooks, CI/CD |
+| `sequence` | API call chains, request lifecycles, async traces, returns |
+| `dataflow` | Pipelines, ETL/ELT, lineage, consumers |
+| `lifecycle` | State transitions, retries, waiting and terminal states |
+
+Pasted Mermaid is read for topology and meaning, then re-authored as fresh
+archify JSON: `flowchart` becomes `workflow` (or `architecture` for a
+component map), `sequenceDiagram` becomes `sequence`, `stateDiagram` becomes
+`lifecycle`.
+
+## Authoring invariants
+
+- One obvious main path; side branches leave the nearest main-path node.
+  Remove low-value edges before adding routing controls.
+- Omit `meta.visual_preset`, `meta.subtitle`, `meta.legend`, and
+  `meta.engineering_profile` by default. Set a visual preset only when the
+  user names that style.
+- Component types are `frontend`, `backend`, `database`, `cloud`,
+  `security`, `messagebus`, and `external`. Variants are `default`,
+  `emphasis`, `security`, and `dashed`.
+- Relationship labels are semantic data. When one collides, move the label
+  or adjust spacing first, then shorten wording while preserving meaning.
+  Deleting a label is not a geometry repair.
+- Preserve exact product names, identifiers, commands, protocols, and paths.
+  `meta.locale` is `"en"` or `"zh-CN"`; omit it for any other language and
+  say that the viewer chrome falls back to English.
+- Brand identity is explicit. Put a canonical built-in id in `brand` only
+  when the node names that real product; query
+  `node <skill>/bin/archify.mjs brands "<name>" --json`. Never infer a brand
+  from a role such as "database".
+- Never accept an edge crossing an unrelated opaque node, an ambiguous shared
+  corridor, or a label masking another route.
+
+Read `references/authoring-contract.md` only when you need field enums,
+spacing math, geometry repair rules, or mode-specific placement.
+
+## Placement
+
+Write `<name>.<type>.json` and `<name>.html` to `.clio-coder/artifacts/maps/`
+unless the user names an output path. Create the directory first. An
+operator-named path is a human deliverable and lands in the working tree
+where they said. Archify creates `.archify-delivery-*` staging directories
+beside the output during `deliver`, so the output directory must be a
+writable directory inside the workspace, never a read-only or external
+location.
+
+## Repository evidence
+
+When asked to map a repository, do not author from scratch. First run:
+
+```bash
+clio-coder context map --json
+```
+
+It reads the codewiki index and writes
+`.clio-coder/artifacts/maps/<repo>.architecture.json`: an architecture spec
+whose components are the repository's largest directory areas and whose
+connections are collapsed import edges. When the origin remote is a GitHub
+URL and `HEAD` is a full revision, the seed also carries `meta.repository`
+and per-component `sources` pointing at real files and lines; otherwise it
+carries neither, because archify accepts source citations only against a
+pinned revision. If it reports that no index exists, run
+`clio-coder context index` and retry. Then refine the seed: rename labels to
+what the areas mean, drop noise edges, and keep `meta.repository` and every
+`sources` entry that came from the seed. Cite additional line ranges only
+from `code_nav mode=outline` results, never from memory, and only when
+`meta.repository` is present. Keep at most 12 primary components; fold
+smaller areas into their parent rather than adding nodes. When the seed
+carries `meta.repository`, pass `--repo-root .` to both `validate` and
+`deliver` so the source paths and line numbers are verified against the
+working tree; without it, run both commands without `--repo-root`.
+
+## Delivery and verification
+
+`validate` during repair, `deliver` once for acceptance. Delivery freezes the
+exact spec bytes into a same-directory snapshot, renders and checks it,
+atomically commits the HTML, and reports SHA-256 plus byte counts for both
+spec and artifact. That is deterministic artifact evidence; it does not
+exercise the viewer in a browser.
+
+After `deliver` exits 0, run the Clio-side check on the committed file:
+
+```
+verify(check="frontend", path="<output.html>")
+```
+
+That validates structure, local references, and syntax, and loads the page
+in a headless browser when one is on PATH. Archify's own
+`node <skill>/bin/archify.mjs visual-check <output.html> --json` is optional:
+it needs a system Chrome and fails with `viewer/chrome-unavailable` on
+headless nodes. Report that outcome as what it is, never as a pass.
+
+Keep the three claims separate: `deliver` proves deterministic artifact
+checks, a browser load proves bounded behavior in a real browser, and
+perceptual visual review requires a human or an image-capable reviewer.
+
+## Output
+
+Return the HTML path, the diagram type, the validation summary, the
+spec and artifact receipt, the `verify` result, and the visual-review
+status. Do not claim success for a non-zero command or claim inspection you
+did not perform.

package/skills/planning/archify/evals.md

@@ -0,0 +1,65 @@
+# Evals — archify
+
+RED-GREEN scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: scenarios recorded, not yet executed against a model
+(`eval-status: scenarios-recorded`).
+
+Both scenarios assume the skill is installed at project scope
+(`.clio-coder/skills/archify/`) and run from the project root.
+
+## S1 — describe a system
+
+Setup: empty git repository. Prompt: "Draw the architecture: a browser
+talks to an API, the API uses Redis as a cache and PostgreSQL as its
+store."
+
+Expected:
+- Chooses `architecture` and reads exactly one schema plus one example
+  before writing.
+- The very next tool action writes
+  `.clio-coder/artifacts/maps/<name>.architecture.json` with four
+  components (`frontend`, `backend`, `database`, `database`), three
+  connections, and `meta.quality_profile: "showcase"`.
+- Runs `validate architecture ... --quality showcase --json`; the receipt
+  reports 0 errors and 0 warnings.
+- Runs `deliver` once; exit 0; `.clio-coder/artifacts/maps/<name>.html`
+  exists and the receipt carries a SHA-256 for both spec and artifact.
+- Runs `verify(check="frontend", path=<html>)` and reports its result.
+- Never invokes `scripts/check-update.mjs` and never runs `visual-check`
+  unless asked; if it does run it on a node without Chrome, reports
+  `viewer/chrome-unavailable` as a skipped check, not a pass.
+
+RED (baseline without the skill): draws Mermaid or ASCII in the reply,
+never writes a JSON spec, never validates, and claims a diagram that does
+not exist on disk.
+
+## S2 — map this repository
+
+Setup: a small fixture repository (about 15 TypeScript files across
+`src/cli`, `src/domains/store`, and `src/domains/api`) with a GitHub
+`origin` remote, a committed `HEAD`, and a codewiki index already built by
+`clio-coder context index`. Prompt: "Map this repository."
+
+Expected:
+- Runs `clio-coder context map --json` before authoring anything.
+- Keeps `meta.repository` (when present) and every seeded `sources` entry;
+  adds line ranges only from `code_nav mode=outline`.
+- Component count stays at or below 12; the `store` area carries
+  `type: "database"`.
+- Runs `validate architecture <seed> --repo-root . --quality standard
+  --json`; 0 errors.
+- Runs `deliver ... --repo-root .`; exit 0; the HTML exists under
+  `.clio-coder/artifacts/maps/`.
+- If the index is missing, tells the user to run `clio-coder context
+  index` instead of inventing components.
+
+RED (baseline without the skill): lists directories from `ls` as
+components with invented edges, no line evidence, no `--repo-root`
+verification, and no delivered HTML.
+
+## Baseline failure modes to watch for
+
+- Authoring coordinates in prose before the first candidate.
+- Reading renderer source before the first candidate.
+- Editing the spec after the final passing validation.
+- Reporting a non-zero `deliver` or a missing Chrome as success.

package/skills/planning/architecture/SKILL.md

@@ -7,7 +7,7 @@ triggers:
   - architecture for this feature
   - decide the engineering approach
   - compare architecture options
-version: 0.3.0
+version: 0.4.1
 license: Apache-2.0
 allowed-tools:
   - read
@@ -51,17 +51,48 @@ stack they know beats a "better" one they don't), leanness (decide only
 what is needed to move), and reversibility (spend deliberation on the
 expensive calls only).
 
-When asking is unavailable (headless or worker run), do not skip the loop
-and do not go quiet: for each decision, state the options, the
-recommendation, and the reasoning inline, adopt the recommendation, and
-mark it `assumed — confirm`. Every other rule still applies, including the
-output path below.
+## Arguments
+
+```text
+/skill architecture <the intent — a PRD path, a brief, or a few sentences>
+```
+
+- The text is what to decide the engineering approach for. A PRD path,
+  brief, or reference doc named or pathed in the request is Step 0's
+  grounding to read first, not more arguments.
+- Nothing is required beyond some text; a blank invocation falls straight
+  to Step 0's own question — what are we building, and is there a written
+  intent to read — rather than inventing a project to architect.
+
+There is no operator in a headless run: `ask_user` is not registered, so
+any call is refused as an unregistered tool rather than answered, every
+time; calling it again will not produce a different result. From wherever
+the first refusal lands — Step 0's "ask whether reference docs
+exist", Step 1's greenfield/brownfield call, or any decision in Step 2 —
+switch immediately to the treatment already described above (state the
+options, the recommendation, the reasoning, adopt it, mark it `assumed —
+confirm`) and keep running every remaining step through Step 3 in the same
+turn. Never stop at the first unanswered gate and never go silent; a
+one-shot document produced without ever attempting the loop is also wrong
+in the other direction — always investigate and state the loop out loud
+first, degrading only once a gate actually goes unanswered. Never invent a
+fact, evidence, or a codebase detail to back an assumption; anything
+genuinely uncertain becomes an open question or a spike, never a plausible
+guess.
+
+The steps below (Step 0 through Step 3) are the plan; do not open a task
+list for them. `tasks` sits outside this skill's tool surface and any call
+to it is refused. `bash` is also outside this skill's tool surface —
+investigate with `read`, `grep`, `find`, `git`, and `code_nav` instead;
+reaching for `bash` to explore or verify is refused.
 
 ## Step 0 — Ground
 
 Read the intent (PRD path, brief, or the user's words). Read any reference
 docs passed alongside; if none were passed, ask whether any exist — the
-context needed is usually already written down.
+context needed is usually already written down. To see what exists in the
+repo before reading it, use the `find` tool (e.g. pattern `**/*`) or `ls`,
+never `bash find`/`bash ls` — `bash` is refused outright, see Arguments.
 
 ## Step 1 — Greenfield or brownfield
 
@@ -99,11 +130,17 @@ user's call. Skip what does not apply and say that you skipped it:
 
 ## Step 3 — Write the decision doc
 
-Only after the calls are made. Default location: `docs/architecture-<slug>.md`
-(or folded into the PRD as an `## Architecture` section when the user
-prefers one document; a tracker page when the user names one and an
-integration exists). Never invent another filename — `final_report.md`,
-`REPORT.md`, and similar are wrong. Shape:
+Only after the calls are made. There are exactly three valid locations, in
+order of default preference — pick one, never a fourth:
+
+1. `docs/architecture-<slug>.md` — the default, no exceptions needed.
+2. An `## Architecture` section folded into the named PRD, only when the
+   user said they prefer one document.
+3. A tracker page, only when the user names one and an integration exists.
+
+No other filename or location is ever correct. `final_report.md`,
+`REPORT.md`, `summary.md`, and anything similar are hard misses, not
+stylistic variants — if none of the three above fit, use option 1. Shape:
 
 ```markdown
 # Architecture — <intent name>
@@ -133,3 +170,15 @@ sprint (`cut-it`), spike a flagged risk now, or keep refining here.
 - One foregone conclusion instead of real alternatives.
 - File-by-file edit lists (that is cut-it's altitude).
 - A one-way door decided by vibe instead of a spike.
+- A decision doc at any filename other than the three valid locations
+  above — `final_report.md`, `REPORT.md`, and similar are wrong every time.
+- A headless run that stops at the first unanswered `ask_user` call instead
+  of running the assumed-confirm treatment through every remaining step, or
+  one that skips straight to Step 3 without ever running the loop out loud.
+- Opening a task list for Steps 0-3; `tasks` is refused. Reaching for
+  `bash` to explore the repo or verify the written doc; `bash` is not in
+  this skill's tool surface and the call is refused — use `read`, `grep`,
+  `find`, `git`, and `code_nav` instead.
+- A claim in the doc that traces to neither the read intent/codebase nor a
+  fact marked `assumed — confirm` — an invented detail reads as confident
+  and is the hardest failure to catch after the fact.

package/skills/planning/architecture/evals.md

@@ -34,3 +34,68 @@ Expected:
 
 One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
 (30B local, llamacpp on mini), full-auto sandbox. SMOKE ACTED but substance bullets failed (wrote final_report.md, skipped the loop). Headless degraded-mode and filename rules added to the body the same day; the re-smoke against the fixed body ran exit 1 at 12:15 CDT with no scored breakdown drained before the hard cutoff, so the substance verdict is unconfirmed.
+
+## Battletest record (2026-09-03)
+
+Fixture: `/home/akougkas/eval-temp/harness/test_architecture.py`, continuing
+the planning category's shared HPC log-triage domain from `product-intent`/
+`prd`. Brownfield: seeds the actual `docs/hpc-log-triage.prd.md` intent doc
+and a partial codebase (`src/scanner.py`: working `FailureEvent` + OOM-only
+`scan_oom`, ECC/Xid not implemented; `requirements.txt` with click/pyyaml)
+inside a git repo. The prompt asks for the v1 engineering approach for
+dragon-cluster and blade-cluster and names the one genuine one-way-door
+tension from the fixture family: an always-on log-ingestion pipeline vs.
+on-demand reads. Combines S1 (brownfield: read existing surfaces, reuse
+`FailureEvent`/`scan_oom` rather than re-spec) with a spike-worthy
+one-way-door call into one gradable run. Graded 13 checks against real
+post-run disk state (`docs/architecture-<slug>.md` at the exact default
+path — no `final_report.md`/`REPORT.md` miss, all seven required sections,
+>=2 genuinely distinct approaches inside "Approaches considered", the
+pipeline-vs-on-demand tension named *and* backed by a spike with a decision
+rule in "Spikes & experiments", grounding in the seeded PRD/code) plus the
+reconstructed final assistant text and the raw JSONL's tool-call/safety-block
+stream. Ran on `mini`/`ornith1.5-35b-moe` only this pass (see Still weak).
+
+| run | model | wall | turns | in / out tokens | safety blocks | score | outcome |
+|---|---|---|---|---|---|---|---|
+| baseline (no skill) | ornith1.5-35b-moe | 110s | 5 | 11.1k / 8.5k | 0 | 3/13 | never invoked `/skill architecture`; investigated correctly (read the PRD and scanner.py) but then called the terminal `artifact` tool mid-reasoning with no arguments and ended the run before writing anything — no decision doc, no alternatives, no spike |
+| v1 (frozen 0.3.0) | ornith1.5-35b-moe | 145s | 9 | 9.7k / 10.0k | 2 real + 1 benign | 10/13 | wrote the correct `docs/architecture-hpc-log-triage.md` with all sections, 3 real alternatives (a table: on-demand / always-on / hybrid-with-gate), the pipeline tension named with a spike and an explicit decision rule, and ran the full headless assumed-confirm loop entirely on its own initiative (the existing body prose already covers this well) — but reached for `bash` once (refused) and opened a `tasks` plan once (refused); a third "error" was a harmless `ls` on a directory the fixture never created |
+| v2 (first hardened cut, 0.4.0) | ornith1.5-35b-moe | 125s | 9 | 5.5k / 7.6k | 1 real + 2 benign | 10/13 | `tasks` call eliminated entirely by the new explicit refusal line; still reached for `bash find .` once before self-recovering with the `find` tool — the added Red flags/Arguments refusal line reduced but did not eliminate the bash reflex, matching the pattern `prd`/`product-intent` saw on this same model family; 2 benign `read` ENOENTs (evidence docs the PRD cites but the fixture never seeded) also counted as errors under this harness's blanket isError grading |
+| v3 (final 0.4.0) | ornith1.5-35b-moe | 159s | 7 | 8.5k / 9.7k | 0 real + 1 benign | 12/13 | zero `bash` calls, zero `tasks` calls, correct path, all 7 sections, 2 distinct approaches, pipeline tension with a spike and decision rule; the one remaining "error" is a harmless duplicate `context` call the harness nudged back onto the loaded skill (not a tool-surface refusal, `context` is always exempt) |
+
+**Changes** (0.3.0 -> 0.4.0): (1) an `## Arguments` contract — the skill had
+solid headless-degradation prose in its intro already, but no formal
+contract section; added slash-invocation syntax, what's required vs.
+inferred, and the explicit no-operator/`ask_user`-returns-empty rule ported
+from `product-intent`/`prd`, extended to name Step 0's evidence-check and
+Step 1's greenfield/brownfield call explicitly (not just Step 2's decisions)
+as places the degradation applies from; (2) explicit `tasks` and `bash`
+refusal lines in Arguments and Red flags — these were v1's two real safety
+blocks; (3) Step 3's filename rule tightened from a permissive "default
+location... never invent another" into an enumerated three-item list with
+"no other filename or location is ever correct," closing the exact gap the
+2026-08-13 smoke record flagged (`final_report.md` on a different model);
+(4) a one-line `find`/`ls`-not-`bash` hint added directly in Step 0, where
+the exploration happens, which is what took the bash-reach from 1/run (v2)
+to 0/run (v3); (5) five new Red flags entries naming the concrete failures
+observed: wrong filename, a stalled or skipped headless loop, `tasks`/`bash`
+reaches, and ungrounded claims.
+
+**Still weak**: per this pass's coordinator note, only `ornith1.5-35b-moe`
+on `mini` was run — no `qwen3.8-27b`/dynamo confirmation this session, so
+cross-model-family generalization is unverified (the sibling `prd`/
+`product-intent` runs found the bash-reflex fix that worked on `qwen3.8-27b`
+did *not* fully generalize to `ornith-1.5-35b-a3b`, so the reverse — a fix
+tuned on ornith not holding on qwen — is a live risk here too, untested).
+The v3 run's one remaining logged "error" is a benign duplicate `context`
+call, not a real defect, but the harness's blanket isError-counting means a
+literal 13/13 may not be reachable without also silencing genuinely benign
+tool responses — not worth chasing. `web_fetch` and `code_nav` (both in
+allowed-tools) were never exercised — this fixture never needed them
+(brownfield, no external research). The baseline's specific failure (an
+unprompted terminal `artifact` call mid-investigation, with no arguments)
+is a skill-selection/tool-choice issue outside this SKILL.md's own body.
+Only one fixture shape ran (brownfield + one-way-door); a pure-greenfield
+scenario (S2's familiarity-vs-fashion pull) and a mid-session altitude
+check (S3, "just list the files to change") from the scenario list above
+were not exercised standalone against 0.4.0.

package/skills/planning/backlog/SKILL.md

@@ -7,12 +7,13 @@ triggers:
   - build the backlog
   - decompose this plan into tickets
   - create GitHub issues from this architecture
-version: 0.3.0
+version: 0.4.1
 license: Apache-2.0
 allowed-tools:
   - read
   - grep
   - ls
+  - git
   - bash
   - tasks
   - ask_user
@@ -33,12 +34,93 @@ clio-coder:
 Turn a finished planning doc into small, engineer-ready tickets on a real
 tracker. Decomposition is tracker-agnostic; creation branches on the target.
 
+## Arguments
+
+```text
+/skill backlog <path to the finished PRD or planning doc>
+```
+
+- Required: the doc path. Named inline, or clearly the file just discussed
+  in context — never a doc invented from memory. If no path can be found or
+  inferred, say so at Step 1 and stop; do not decompose without a doc.
+- Optional, inferred rather than asked for by default: target platform
+  (Step 1's own rule picks it — see below) and a milestone/epic to attach
+  tickets to.
+
+There is no operator in a headless run: `ask_user` is not registered, so
+any call is refused as an unregistered tool rather than answered; that is
+not a stall, and calling it again will not produce a different result. **This skill treats headless
+degradation differently at each step below, because Step 3 gates an
+outward, not-cleanly-reversible action — real tickets, GitHub issues or
+persisted local tasks — not a document write:**
+
+- **Step 1 (platform).** The default rule (`gh` when a remote and the `gh`
+  binary are both present; the `tasks` fallback otherwise) is a fact to
+  detect, not a judgment call, and runs the same whether or not anyone is
+  watching — no confirmation needed either way. It is genuinely ambiguous
+  only when the user names a platform with no available integration; if
+  that `ask_user` call goes unanswered, do not guess a fallback and do not
+  silently substitute `gh` or `tasks` for the platform actually requested —
+  state plainly that the named platform is unavailable and confirmation of
+  what to use instead was not obtainable, then stop exactly as Step 3 does.
+- **Step 2 (decompose).** Always run to completion, headless or not.
+  Decomposition itself creates nothing yet, and every source-doc gap still
+  needs surfacing whether or not a human is present to read it.
+- **Step 3 (confirm before creating).** An unanswered `ask_user` here is
+  never a yes, and this gate does not get the assumed-confirm-and-proceed
+  treatment the other planning skills use for their document gates. Finish
+  Step 2, print the full proposed ticket list and target platform exactly
+  as Step 3 already requires, then stop: say explicitly that confirmation
+  is required before any ticket is created, that it was not obtainable in
+  this run, and that Step 4 did not execute. This is the one gate in the
+  planning category's headless story that ends in a stop rather than an
+  assumed yes — filing unrequested public GitHub issues, or persisting
+  local tickets nobody confirmed, on a guess is worse than an incomplete
+  run; the full decomposed list is still delivered as the answer.
+
+The steps below are the plan; hold it in your head, not in a tool — do not
+call `tasks` with `plan`/`add`/`done`/`block`/`drop` to track your own
+progress through Steps 1–5 as if they were a workflow board. What actually
+matters when Step 3 stops without confirmation: the board must end this
+run holding zero net-open items. `tasks` calls here are Step 4's — one
+entry per ticket *already confirmed at Step 3* — and Step 4 never runs
+before that yes. If you do reach for `tasks` before confirmation (to
+stage the proposal, or to check the board is clean), any item you opened
+with `plan`/`add` must be `drop`ped again before you finish, in the same
+run — an item left open on the board is exactly "created without
+confirmation," whether or not you called it that. A read-only
+`tasks(action="list")` changes nothing and is always fine. Do not re-invoke
+`context(scope="skills")` once the skill is already loaded this turn — it
+is refused as a redundant call and wastes a turn; if you need to recheck
+what you already read, use `read`/`grep` on the files themselves.
+
+Shell rules for every `bash` call: one command per call, plain and direct.
+Never use `$(...)` or backticks; they trigger an approval gate a headless
+run cannot answer, and the call is refused outright. Never redirect output
+to `/tmp` (`> /tmp/...`) to stage or capture something for a later step —
+that write needs an approval a headless run cannot give either, and the
+call is refused the same way; just run the command and read its output
+directly, nothing needs staging on disk first. The `git` tool only covers
+`status`/`diff`/`log`; it has no `remote` op, so Step 1's remote and
+`gh`-availability check still goes through `bash` (e.g. `git remote -v`,
+`command -v gh`) — use `git` for a plain status check, `bash` for
+everything else this skill needs from git or `gh`.
+
 ## Step 1 — Inputs
 
-Required: the path to the PRD or planning doc. Target platform: GitHub
-issues via `gh` by default; another tracker only when the user names it and
-an integration for it is available. Platform genuinely ambiguous → ask,
-never guess. Optional: a milestone or epic to attach tickets to.
+Required: the path to the PRD or planning doc (see Arguments). Target
+platform: GitHub issues via `gh` when a git remote exists and the `gh`
+binary is present — check both in one `bash` call (`git remote -v;
+command -v gh`) and trust the result; empty output from `git remote -v` is
+a definitive "no remote", not an inconclusive check that needs a second or
+third method (`git config`, reading `.git/config` directly — the latter is
+a hard-blocked path regardless of this skill). Fall back to local tracking
+automatically (see Step 4) when there is no remote, `gh` is unavailable, or
+the user asked for local tracking, and say which was detected and why. A
+platform the user names with no integration available is genuinely
+ambiguous → ask, never guess, and never silently substitute a different
+platform than the one requested (see Arguments for the headless case).
+Optional: a milestone or epic to attach tickets to.
 
 ## Step 2 — Decompose
 
@@ -55,17 +137,23 @@ each user story becomes one or more tickets. Per ticket, draft:
 Sizing rules: a ticket is at most about a day of work; a ticket that needs
 more than one screen to describe is two tickets. A phase too vague to
 decompose is a gap in the source doc — stop and flag it rather than
-inventing tickets.
+inventing tickets. Flag it by name (which phase, what is missing) in the
+Step 3 list and again in the Step 5 report; do not paper over it with a
+plausible-sounding ticket the source doc never actually specified.
 
 ## Step 3 — Confirm before creating
 
-Print the full proposed list (titles grouped by phase) and the target
-platform, and get explicit confirmation via `ask_user`. Ticket creation is
-outward-facing and not one-click reversible; nothing is created before the
-yes.
+Print the full proposed list, grouped by phase — title *and* acceptance
+criteria per ticket, not titles alone, plus any flagged gaps from Step 2 —
+and the target platform, and get explicit confirmation via `ask_user`.
+Ticket creation is outward-facing and not one-click reversible; nothing is
+created before the yes. When that confirmation cannot be obtained (see
+Arguments), stop here — do not proceed to Step 4.
 
 ## Step 4 — Create
 
+Runs only after Step 3's explicit yes.
+
 GitHub:
 
 ```bash
@@ -82,15 +170,43 @@ or the user asks for local tracking, create each confirmed ticket with the
 `tasks` tool instead (one task per ticket, acceptance criteria in the
 description) and capture the task ids. Say which target was used and why.
 
+Every report in this skill — confirmed-and-created or stopped-before-
+confirmation — is delivered as a chat message, never a file. Do not call
+`write` to save the proposal or the report to disk as a backlog/proposal
+markdown file; `write` is not in this skill's tool surface and the call is
+refused. If the user wants the backlog persisted as a document, that is a
+different, file-producing skill (`prd`, `architecture`), not this one.
+
 ## Step 5 — Report
 
-A table: title → phase → issue number/URL, plus the source doc path and any
-failures. Done when every proposed ticket is either created with its URL
-captured or listed as failed with the error.
+Confirmed-and-created run: a table of title → phase → issue number/URL,
+plus the source doc path and any failures. Done when every proposed ticket
+is either created with its URL captured or listed as failed with the
+error.
+
+Stopped-before-confirmation run (see Arguments): one self-contained final
+message — never split across turns and never "see above" — that repeats
+the full proposed ticket list with title *and* acceptance criteria per
+ticket (a status column of "proposed" is not a substitute for the
+criteria themselves), plus one explicit line stating that confirmation was
+required and unavailable and no ticket was created. A reader who sees only
+this last message must get the complete list and the complete status;
+never let the table alone imply creation happened, and never make the
+stop notice depend on an earlier turn still being visible.
 
 ## Red flags
 
-- Tickets created before the Step 3 confirmation.
+- Tickets created before the Step 3 confirmation — including a headless
+  run that treats an unanswered `ask_user` there as a yes and proceeds to
+  Step 4 anyway; that gate stops, it does not assume.
+- A final report whose ticket table doesn't say, in words, whether creation
+  happened or confirmation was unavailable.
 - Acceptance criteria that restate the title.
 - A mega-ticket hiding a week of work.
 - Tickets with no trace back to a phase or story in the source doc.
+- A vague phase decomposed into invented tickets instead of flagged as a
+  source-doc gap.
+- Any item left net-open on the `tasks` board when a run stops without
+  Step 3 confirmation; `tasks` here is Step 4's confirmed-ticket store, and
+  anything opened before that as a scratchpad must be dropped again in the
+  same run.