@seanmars/tospec 0.26.0 → 0.27.0

package/dist/core/templates/workflows/apply.js

@@ -1,5 +1,6 @@
 import { VERIFY_DOC, VERIFY_POINTER } from '../fragments/verify.js';
 import { VALIDATE_VERDICT_RULE } from '../fragments/validate.js';
+import { PERF_CONFIRMATION, PREMISE_CHECK } from '../fragments/debugging.js';
 /** One parameterized template literal, not a template engine. */
 function buildApplyBody(v) {
     return `**Task tracking is file-based only.** The tracks file's checkboxes (\`- [ ]\` / \`- [x]\`) are the single source of truth for progress. Never use a built-in todo or task-tracking tool — editing the checkbox in the file is the only way progress gets recorded.
@@ -48,10 +49,14 @@ function buildApplyBody(v) {
 
    Before checking an item off, re-read its description and confirm every part of it is covered by your changes and the behavior it describes actually works. An item checked off half-finished is the most expensive mistake in this loop.
 
+   "Actually works" means you ran it: a test, the feedback loop, or a command that drives the real code and would fail if you were wrong. Pointing at the line or walking through the code is not that check. When nothing you can run reaches the behavior (it needs the user's environment or credentials), name the item in your report as not verified by a run rather than present it as proven.
+
    **Pause if** the item is unclear, implementation reveals a design issue (suggest \`tospec-update\`), or you hit an error or blocker — report it and wait for guidance. Don't guess.
 
    **Pause too if** the item turns out to need work beyond what the specs and the tracks file describe, or you catch yourself wanting to drop, narrow, defer, or make an exception to specified behavior so the item fits — say what the extra scope is and ask. Absorbing it silently is worse than the delay: it turns "done" into a claim the user has no way to check.
 
+   **Stopping mid-item.** Whenever you stop with an item started but not finished (a pause above, the user stopping you, the session running out), leave its box unchecked and put one line directly under it as a nested bullet: \`  - Resume: <done so far>; <what is left>; <next action>\`. Never open the line with \`[\`, which validate reads as a mistyped checkbox. Nothing else records a half-done item: the box says only "not done", so the next pass would redo the finished part or skip the unfinished one. When the item you take has a \`Resume:\` line, start from it: check what it claims is done against the code, then continue rather than redo. Delete the line when you check the item off.
+
 ${v.sddBranch}
 
 ${v.issueBranch}
@@ -74,6 +79,7 @@ ${v.guardrailsHead}
 - Keep code changes minimal and scoped to the item at hand
 - Any test you do write goes at the pre-agreed seam (design.md for sdd; the existing/new seam identified for issue) — never against internals
 - Fix root cause: check every caller of a shared function before declaring a fix complete
+- Callers are not a change's whole reach: when the code you change reads or writes data that leaves the function (a persisted file or database column, a serialized or wire format, a config key, a feature flag), find the other readers and writers of that data too — a symbol search does not find them
 - Don't hand off to archive until the full test suite is green`;
 }
 // An assertion that recomputes the expected value the way the code does can
@@ -84,6 +90,12 @@ const TAUTOLOGICAL_ASSERTIONS = "tautological ones (the expected value computed
 // can be found again; nothing else removed it, so it rode into the fix's diff.
 // Only the issue branches carry it: no other workflow adds the tag.
 const DEBUG_LOG_CLEANUP = 'Before checking a task off, grep the project for `[DEBUG-` and delete every tagged log line diagnosis added.';
+// Fixes that keep failing the feedback loop are evidence the diagnosis is
+// wrong, and a fix cannot be right on a wrong Root Cause. Apply never edits
+// task.md's diagnosis on its own, so the way out is a report, not a third fix.
+// The guard sentence points back at Fix Plan, where issue settled whether the
+// triggering state is legitimate, instead of restating that test here.
+const ISSUE_FIX_DISCIPLINE = `A guard, a retry, or a swallowed error at the line that broke is a fix only when \`task.md\`'s Fix Plan found the triggering state legitimate. ${PREMISE_CHECK} Here the assumption is usually \`task.md\`'s Root Cause: if the test shows it is wrong, stop and report it, because no fix is right on a wrong diagnosis, and revising \`task.md\` is \`tospec-update\`'s work.`;
 // Default apply — implement per slice; tests beyond the listed steps are optional, not mandated.
 const APPLY_VARIANT = {
     checkOffRule: 'Take the next unchecked item, implement it, confirm it works against its specs, check it off (\`- [ ]\` → \`- [x]\`), then move to the next.',
@@ -97,7 +109,7 @@ For each tracer-bullet slice in \`tasks.md\`:
 Test steps that \`tasks.md\` lists for a slice are part of that slice. Beyond those, writing a new test is **not required** in this loop — add one when it earns its keep. If you do, put it at the seam \`design.md\` named and don't test internals or add implementation-coupled assertions (mocking internal collaborators, reaching into private state, checking the database instead of the interface) or ${TAUTOLOGICAL_ASSERTIONS}.`,
     issueBranch: `### issue branch — fix root cause
 
-Read \`task.md\`'s feedback loop, then fix the root cause, not the symptom — if the same defect is reachable through multiple callers of a shared function, the fix belongs in the shared function, not patched into just the caller the ticket named (grep every caller of the function you're touching). Confirm the fix with \`task.md\`'s feedback loop and keep the existing suite green. ${DEBUG_LOG_CLEANUP}
+Read \`task.md\`'s feedback loop, then fix the root cause, not the symptom — if the same defect is reachable through multiple callers of a shared function, the fix belongs in the shared function, not patched into just the caller the ticket named (grep every caller of the function you're touching). Confirm the fix with \`task.md\`'s feedback loop and keep the existing suite green. ${PERF_CONFIRMATION} ${ISSUE_FIX_DISCIPLINE} ${DEBUG_LOG_CLEANUP}
 
 Test steps that \`task.md\` lists are part of the fix. Beyond those, writing a new regression test is **not required** here — add one when the bug is likely to recur, extending the existing test if there's one at the right seam.`,
     // Scoped to tests beyond the listed steps: both branches make those part of
@@ -140,7 +152,9 @@ Read \`task.md\`'s feedback loop. Then:
 - **Existing test, passing** → the bug is an edge case the existing test doesn't cover. Add a new failing test for that edge case first, run it and confirm it fails on the asserted behavior (a compile, import or setup error is not red), then fix.
 - **No existing test** → write the red regression test from \`task.md\`'s feedback loop first, run it and confirm it fails on the asserted behavior (a compile, import or setup error is not red), then fix.
 
-Fix root cause, not symptom — if the same defect is reachable through multiple callers of a shared function, the fix belongs in the shared function, not patched into just the caller the ticket named.
+Fix root cause, not symptom — if the same defect is reachable through multiple callers of a shared function, the fix belongs in the shared function, not patched into just the caller the ticket named. ${ISSUE_FIX_DISCIPLINE}
+
+${PERF_CONFIRMATION}
 
 ${DEBUG_LOG_CLEANUP}`,
     guardrailsHead: `- Red before green, always — never write the implementation before its failing test

package/dist/core/templates/workflows/apply.js.map

@@ -1 +1 @@
-{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/apply.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAcjE,iEAAiE;AACjE,SAAS,cAAc,CAAC,CAAe;IACrC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mEAwC0D,CAAC,CAAC,YAAY;;;;;;;;;;EAU/E,CAAC,CAAC,SAAS;;EAEX,CAAC,CAAC,WAAW;;;;;;wMAMyL,qBAAqB;;EAE3N,cAAc;;;;;;;EAOd,CAAC,CAAC,cAAc;;;;;+DAK6C,CAAC;AAChE,CAAC;AAED,4EAA4E;AAC5E,8EAA8E;AAC9E,2EAA2E;AAC3E,MAAM,uBAAuB,GAC3B,yOAAyO,CAAC;AAE5O,6EAA6E;AAC7E,+EAA+E;AAC/E,oEAAoE;AACpE,MAAM,iBAAiB,GACrB,8GAA8G,CAAC;AAEjH,iGAAiG;AAEjG,MAAM,aAAa,GAAiB;IAClC,YAAY,EACV,8IAA8I;IAChJ,SAAS,EAAE;;;;;;;kZAOqY,uBAAuB,GAAG;IAC1a,WAAW,EAAE;;iYAEkX,iBAAiB;;qOAE7K;IACnO,4EAA4E;IAC5E,iFAAiF;IACjF,cAAc,EAAE;;wFAEsE;CACvF,CAAC;AAEF,MAAM,UAAU,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;AAEjD,MAAM,UAAU,2BAA2B;IACzC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,wIAAwI;QACrJ,YAAY,EAAE;;;;EAIhB,UAAU,EAAE;QACV,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC;QAC3F,UAAU,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE;KACxC,CAAC;AACJ,CAAC;AAED,6CAA6C;AAE7C,MAAM,iBAAiB,GAAiB;IACtC,YAAY,EACV,sIAAsI;IACxI,SAAS,EAAE;;;obAGua,uBAAuB;;;4JAG/S;IAC1J,WAAW,EAAE;;;;;;;;;EASb,iBAAiB,EAAE;IACnB,cAAc,EAAE;yCACuB;CACxC,CAAC;AAEF,MAAM,cAAc,GAAG,cAAc,CAAC,iBAAiB,CAAC,CAAC;AAEzD,MAAM,UAAU,kCAAkC;IAChD,OAAO;QACL,IAAI,EAAE,uBAAuB;QAC7B,WAAW,EAAE,oJAAoJ;QACjK,YAAY,EAAE;;;;EAIhB,cAAc,EAAE;QACd,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC;QAC3F,UAAU,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE;KACxC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/apply.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAc7E,iEAAiE;AACjE,SAAS,cAAc,CAAC,CAAe;IACrC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mEAwC0D,CAAC,CAAC,YAAY;;;;;;;;;;;;;;EAc/E,CAAC,CAAC,SAAS;;EAEX,CAAC,CAAC,WAAW;;;;;;wMAMyL,qBAAqB;;EAE3N,cAAc;;;;;;;EAOd,CAAC,CAAC,cAAc;;;;;;+DAM6C,CAAC;AAChE,CAAC;AAED,4EAA4E;AAC5E,8EAA8E;AAC9E,2EAA2E;AAC3E,MAAM,uBAAuB,GAC3B,yOAAyO,CAAC;AAE5O,6EAA6E;AAC7E,+EAA+E;AAC/E,oEAAoE;AACpE,MAAM,iBAAiB,GACrB,8GAA8G,CAAC;AAEjH,0EAA0E;AAC1E,4EAA4E;AAC5E,+EAA+E;AAC/E,8EAA8E;AAC9E,uEAAuE;AACvE,MAAM,oBAAoB,GAAG,kJAAkJ,aAAa,kNAAkN,CAAC;AAE/Y,iGAAiG;AAEjG,MAAM,aAAa,GAAiB;IAClC,YAAY,EACV,8IAA8I;IAChJ,SAAS,EAAE;;;;;;;kZAOqY,uBAAuB,GAAG;IAC1a,WAAW,EAAE;;iYAEkX,iBAAiB,IAAI,oBAAoB,IAAI,iBAAiB;;qOAE1N;IACnO,4EAA4E;IAC5E,iFAAiF;IACjF,cAAc,EAAE;;wFAEsE;CACvF,CAAC;AAEF,MAAM,UAAU,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;AAEjD,MAAM,UAAU,2BAA2B;IACzC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,wIAAwI;QACrJ,YAAY,EAAE;;;;EAIhB,UAAU,EAAE;QACV,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC;QAC3F,UAAU,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE;KACxC,CAAC;AACJ,CAAC;AAED,6CAA6C;AAE7C,MAAM,iBAAiB,GAAiB;IACtC,YAAY,EACV,sIAAsI;IACxI,SAAS,EAAE;;;obAGua,uBAAuB;;;4JAG/S;IAC1J,WAAW,EAAE;;;;;;;0MAO2L,oBAAoB;;EAE5N,iBAAiB;;EAEjB,iBAAiB,EAAE;IACnB,cAAc,EAAE;yCACuB;CACxC,CAAC;AAEF,MAAM,cAAc,GAAG,cAAc,CAAC,iBAAiB,CAAC,CAAC;AAEzD,MAAM,UAAU,kCAAkC;IAChD,OAAO;QACL,IAAI,EAAE,uBAAuB;QAC7B,WAAW,EAAE,oJAAoJ;QACjK,YAAY,EAAE;;;;EAIhB,cAAc,EAAE;QACd,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC;QAC3F,UAAU,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE;KACxC,CAAC;AACJ,CAAC"}

package/dist/core/templates/workflows/explore.js

@@ -28,11 +28,11 @@ ${INTERVIEW_MECHANICS}
 
 3. **Converge**
 
-   You're done when you can fully restate the requirement back to the user in your own words and they confirm it's correct — not when you run out of questions. If they correct your restatement, that's a sign there's still a hidden branch; keep going.
+   You're done when you can fully restate the requirement back to the user in your own words and they confirm it's correct — not when you run out of questions. Step 4 is where that confirmation happens.
 
-4. **Restate**
+4. **Restate the whole explore and get it confirmed**
 
-   Deliver the converged understanding back in the conversation — the problem, the decisions made (with reasoning), and anything explicitly ruled out — so \`tospec-propose\`/\`tospec-issue\` can synthesize it straight from context (that's exactly the input they expect).
+   Run the \`tospec-restate-your-goal\` workflow as a sub-step over the whole explore, not just the last answer: the goal, the problem, the decisions made (with reasoning), and anything explicitly ruled out. It ends by asking the user to confirm or correct. A correction means there's still a hidden branch: go back to step 2 with it, then restate again. Only a confirmed restatement moves on to step 5; it stays in the conversation, so \`tospec-propose\`/\`tospec-issue\` can synthesize it straight from context (that's exactly the input they expect).
 
 5. **Record any settled decision — don't ask first**
 

package/dist/core/templates/workflows/grill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grill.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/grill.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAiDjD,wBAAgB,qBAAqB,IAAI,aAAa,CAerD"}
+{"version":3,"file":"grill.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/grill.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAmDjD,wBAAgB,qBAAqB,IAAI,aAAa,CAerD"}

package/dist/core/templates/workflows/grill.js

@@ -30,7 +30,9 @@ ${INTERVIEW_MECHANICS}
 
 **Converge**
 
-You're done only when you can fully restate the shared understanding — the claims that held up, the assumptions now made explicit, the questions answered, and anything left deliberately open — and the user confirms it's right. Running out of questions is not convergence. If the user corrects your restatement, there's still a hidden branch; keep grilling.
+You're done only when you can fully restate the shared understanding and the user confirms it's right. Running out of questions is not convergence.
+
+Run the \`tospec-restate-your-goal\` workflow as a sub-step over the whole grill, with the grill's findings as the extra items: the claims that held up (and any that fell), the assumptions now made explicit, the questions answered, and anything left deliberately open. It ends by asking the user to confirm or correct. If the user corrects the restatement, there's still a hidden branch; keep grilling, then restate again. Only a confirmed restatement moves on to the handoff.
 
 **Hand off once the understanding is confirmed**
 

package/dist/core/templates/workflows/grill.js.map

@@ -1 +1 @@
-{"version":3,"file":"grill.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/grill.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;EA0BjB,mBAAmB;;;;;;;;;;;0DAWqC,iBAAiB,CAAC,mCAAmC,EAAE,sDAAsD,CAAC;;;;;;oHAMpD,CAAC;AAErH,MAAM,UAAU,qBAAqB;IACnC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,mVAAmV;QAChW,YAAY,EAAE;;;;EAIhB,UAAU,EAAE;QACV,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,iEAAiE;QACjE,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,2BAA2B,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KACzG,CAAC;AACJ,CAAC"}
+{"version":3,"file":"grill.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/grill.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;EA0BjB,mBAAmB;;;;;;;;;;;;;0DAaqC,iBAAiB,CAAC,mCAAmC,EAAE,sDAAsD,CAAC;;;;;;oHAMpD,CAAC;AAErH,MAAM,UAAU,qBAAqB;IACnC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,mVAAmV;QAChW,YAAY,EAAE;;;;EAIhB,UAAU,EAAE;QACV,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,iEAAiE;QACjE,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,2BAA2B,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KACzG,CAAC;AACJ,CAAC"}

package/dist/core/templates/workflows/how.d.ts

@@ -0,0 +1,3 @@
+import type { SkillTemplate } from '../types.js';
+export declare function getTospecHowSkillTemplate(): SkillTemplate;
+//# sourceMappingURL=how.d.ts.map

package/dist/core/templates/workflows/how.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"how.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/how.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAmPjD,wBAAgB,yBAAyB,IAAI,aAAa,CA0BzD"}

package/dist/core/templates/workflows/how.js

@@ -0,0 +1,283 @@
+/**
+ * How Workflow Template
+ *
+ * Adapted from pstack's `how`: explain how part of the codebase works at the
+ * level a senior engineer needs before changing it. pstack answers in chat with
+ * mermaid; this one writes an offline HTML page with interactive diagrams to the
+ * system temp directory, so the explanation is easier to follow and the working
+ * tree stays untouched.
+ *
+ * Diagrams are JSON specs the page lays out on a grid in the browser, not
+ * mermaid: a mermaid bundle would add ~3 MB to every page, and asking the agent
+ * for raw SVG coordinates produces overlaps. The skeleton and `page.mjs` ship
+ * as files under `assets/how/` because they are HTML and JS, not prompt prose.
+ *
+ * The agent writes only the sections, and `page.mjs build` wraps them in the
+ * skeleton: retyping the skeleton's ~38 KB per page cost ~10k output tokens
+ * and could break the diagrams with one wrong character.
+ */
+import { readFileSync } from 'node:fs';
+// dist/core/templates/workflows → package root, as for the other shipped assets.
+const ASSET_DIR = new URL('../../../../assets/how/', import.meta.url);
+const EXPLORER_DOC = `# Explorer brief
+
+You are one of several explorers tracing different slices of the same subsystem in parallel. The prompt that sent you here gives the question and your angle. Do not try to cover everything: go deep on your angle. You are read-only: read and search, change nothing.
+
+## Report
+
+### Components
+The key types, functions, modules and services. For each: name, \`path:line\`, and one sentence on what it does.
+
+### Flow
+Step by step: what runs, in which file, what it does, what it calls next, and the data passed between steps. Name each decision point and what it branches on.
+
+### State
+What persists, what is held only in memory, and what changes it. List any status values and the events that move between them.
+
+### Boundaries
+Where this slice meets the rest of the codebase: its inputs, its outputs, and who calls in.
+
+### Non-obvious things
+Behavior that is surprising, historically motivated, or easy to get wrong: things that look like they work one way and work another.
+
+### Files read
+Every file you read, so the synthesis can cite them.
+
+### Open questions
+What you could not trace. Say so plainly: a guess reported as a finding is worse than a gap.
+`;
+const WRITING_DOC = `# Writing the page
+
+## The content file
+
+You write only the content; \`page.mjs build\` wraps it in \`skeleton.html\`, whose stylesheet, script and Content-Security-Policy reach the page unchanged. Never read, copy or edit the skeleton or the built page. The file starts with four header lines, then a line that is exactly \`---\`, then the sections:
+
+\`\`\`html
+lang: zh-Hant-TW
+title: How the CLI derives artifact status
+question: How does the status command know each artifact's state?
+meta: my-project · 2026-10-23
+---
+<section id="overview">
+  <h2>Overview</h2>
+  <p class="lede">...</p>
+</section>
+\`\`\`
+
+- \`lang\` is the language you answer in (\`zh-Hant-TW\`, \`en\`, ...); it also picks the language of the page's buttons.
+- \`title\`, \`question\` (the user's question) and \`meta\` (project name and date) are plain text: the build escapes them, so write \`<\` and \`&\` as they are. \`meta\` may be empty.
+- Everything after \`---\` is HTML and goes into the page as written, so escape \`<\`, \`>\` and \`&\` in the text there yourself. No \`<html>\`, \`<head>\`, \`<body>\` or \`<style>\`: the skeleton has them.
+
+## Sections
+
+Each section is a \`<section>\` with an \`<h2>\`; the page builds its table of contents from them. Use the ones that apply, in this order:
+
+- **Overview** — one or two paragraphs: what this is, what it does, why it exists. Open with \`<p class="lede">\`. A reader who stops here can still decide whether to read on.
+- **Key Concepts** — the types, services and abstractions the rest depends on, as a concept grid. Short definitions, not an inventory.
+- **How It Works** — the core, and the longest section. What triggers it, what happens step by step, where data goes, where it branches. Lead with the diagram, then walk it in prose or a numbered step list.
+- **Where Things Live** — a short file map: only what someone needs to start working here.
+- **Gotchas** — non-obvious behavior, historical context, pitfalls, and every place the code disagrees with a spec or an ADR. Skip it when there is nothing.
+- **Open Questions** — what could not be traced. Skip it when there is nothing.
+
+## Style
+
+- Concrete over abstract: "\`archive\` calls \`applySpecs()\`", not "the command delegates to a helper".
+- When something is complex, say why it is complex, not only what it does. When it is simple, do not pad it.
+- Prose, not pseudocode. Cite \`path:line\` so the reader knows where to look; quote code only when a snippet is essential to the point.
+- Use an analogy when one helps; never force one.
+- Write in the language of the conversation. Identifiers, paths and established technical terms stay as they are.
+
+## Choosing diagrams
+
+| The reader needs to see | Diagram |
+| --- | --- |
+| Which parts exist and what depends on what | architecture: \`flow\` with \`groups\` for layers or processes |
+| Who calls whom, in what order, for one request or command | \`sequence\` |
+| The lifecycle of one thing: its statuses and what moves it | state: \`flow\` with \`state\` nodes, \`start\` / \`end\`, and events on the edges |
+| Branching logic | flowchart: \`flow\` with \`decision\` nodes |
+
+A diagram has to explain something the prose would explain worse; skip it when prose covers the point. Keep each one to 12 nodes or fewer (a sequence: 6 participants, 14 messages). Split a bigger picture into an overview and a zoom-in. Add \`steps\` when order matters: the reader walks them with Previous / Next (or the arrow keys), and each step lights up its part of the diagram.
+
+## Diagram specs
+
+Put a spec in a figure and the page draws it:
+
+\`\`\`html
+<figure class="diagram">
+  <script type="application/json">{ "type": "flow", ... }</script>
+  <figcaption>What this diagram shows</figcaption>
+</figure>
+\`\`\`
+
+The JSON must be valid (double quotes, no trailing commas, no comments) and must not contain \`</script\`.
+
+### flow
+
+\`\`\`json
+{
+  "type": "flow",
+  "groups": [{ "label": "CLI process", "cols": [0, 1], "rows": [0, 0] }],
+  "nodes": [
+    { "id": "cli", "label": "commander program", "col": 0, "row": 0, "note": "Parses argv and dispatches to a command.", "ref": "src/cli/index.ts:422" },
+    { "id": "cmd", "label": "statusCommand", "col": 1, "row": 0 },
+    { "id": "fs", "label": "change directory", "kind": "store", "col": 1, "row": 1 }
+  ],
+  "edges": [
+    { "from": "cli", "to": "cmd", "label": "status --json" },
+    { "from": "cmd", "to": "fs", "label": "reads files", "dashed": true }
+  ],
+  "steps": [
+    { "title": "Dispatch", "text": "commander matches the subcommand.", "show": ["cli", "cli->cmd"] },
+    { "title": "Derive status", "text": "Status comes from which files exist.", "show": ["cmd->fs"] }
+  ]
+}
+\`\`\`
+
+- **Grid**: \`col\` and \`row\` count from 0. Each cell is 220 × 116 px and holds one node; two nodes in one cell is an error. A fractional value (\`0.5\`) centres a node between two cells.
+- **Layout**: run the main path left to right (or top to bottom) in reading order. Put a store below or beside what writes it, and external systems at the edges. An edge that would cross another node bends around it by itself; set \`"bend": 60\` (px, the sign picks the side) to override.
+- **Groups**: \`cols\` and \`rows\` are inclusive \`[first, last]\` ranges. Use them for a layer, a process or a package boundary.
+- **Node kinds**: \`box\` (the default: module, function, service), \`store\` (database, file, cache), \`external\` (outside the codebase), \`actor\` (a person or a calling tool), \`decision\` (a branch; label it as a question), \`state\`, \`start\`, \`end\`.
+- **Labels**: a name, not a sentence. About 20 Latin or 10 CJK characters a line, three lines at most; \`\\n\` forces a break. The explanation goes in \`note\`, shown when the reader clicks the node or edge; \`ref\` adds a copyable \`path:line\`.
+- **Edges**: \`label\` names what moves (a call, an event, data). \`"dashed": true\` marks an async, optional or read-only link. In a state diagram the label is the event or condition.
+- **Steps**: \`show\` lists node ids and \`"from->to"\` edges; an edge lights its two ends with it.
+
+### sequence
+
+\`\`\`json
+{
+  "type": "sequence",
+  "participants": [
+    { "id": "user", "label": "User", "kind": "actor" },
+    { "id": "cmd", "label": "archive command", "ref": "src/commands/archive.ts" },
+    { "id": "merge", "label": "specs-apply" },
+    { "id": "fs", "label": "file system", "kind": "store" }
+  ],
+  "messages": [
+    { "from": "user", "to": "cmd", "label": "archive <name>" },
+    { "divider": "Validate" },
+    { "from": "cmd", "to": "cmd", "label": "re-validate deltas", "note": "Any ERROR stops the archive here." },
+    { "divider": "Merge" },
+    { "from": "cmd", "to": "merge", "label": "applySpecs()" },
+    { "from": "merge", "to": "fs", "label": "write specs/" },
+    { "from": "merge", "to": "cmd", "label": "merged", "reply": true }
+  ]
+}
+\`\`\`
+
+- Participants are columns, left to right in the order a request first reaches them.
+- Each message is a row. \`"reply": true\` draws a dashed return; \`from\` equal to \`to\` is a self-call; \`{ "divider": "..." }\` labels a phase.
+- Every message is a step on its own, with its \`note\` as the step text. Set \`"steps": false\` to turn that off.
+
+### Hand-drawn SVG
+
+When neither type fits, put an \`<svg viewBox="...">\` straight into the figure, with no \`<script>\`. Use the page's classes so it matches: \`<g class="node k-store">\` around a shape and its \`<text>\`, \`<g class="edge">\` around a \`<path class="line">\`. Add \`data-key\`, \`data-title\` and \`data-note\` to a group to make it clickable. Nothing lays this out for you, so check every coordinate.
+
+## Components
+
+\`\`\`html
+<section id="overview">
+  <h2>Overview</h2>
+  <p class="lede">The answer in one paragraph.</p>
+</section>
+
+<dl class="concepts">
+  <div><dt>Artifact graph <code class="ref">src/core/artifact-graph/</code></dt><dd>What it is, in one or two sentences.</dd></div>
+</dl>
+
+<ol class="steps">
+  <li><strong>Resolve the root.</strong> Walk up to the nearest directory holding the project folder. <code class="ref">src/core/root-selection.ts:12</code></li>
+</ol>
+
+<table>
+  <tr><th>Path</th><th>What lives there</th></tr>
+  <tr><td><code class="ref">src/commands/</code></td><td>One file per command body.</td></tr>
+</table>
+
+<aside class="callout warn"><strong>Title</strong><p>A gotcha.</p></aside>
+<aside class="callout open"><strong>Title</strong><p>An open question.</p></aside>
+<aside class="callout note"><strong>Title</strong><p>A side note.</p></aside>
+
+<details><summary>Deep dive: ...</summary><p>Detail most readers can skip.</p></details>
+\`\`\`
+
+A \`<code class="ref">\` copies its text when clicked: use it for every path and \`path:line\`, and plain \`<code>\` for identifiers.
+
+## Before reporting
+
+\`page.mjs build\` checks the page it writes. It fails on a missing header value, a whole page pasted in as content, an unknown node id, two nodes in one cell, a label too long for three lines, invalid JSON, anything loaded from outside the file, and a file outside the temp directory. Fix every FAIL line in the content file and build again. It cannot judge the writing, so also confirm that every claim about the code carries a \`path\` or \`path:line\`.
+`;
+const HOW_BODY = `**This is read-only on the project.** Read files, search code, and run read-only \`tospec\` commands; write no code, source edits, or artifact files. The one write is the HTML page, and it goes to the system temp directory, never inside the project, so explaining leaves the working tree as it was.
+
+**Steps**
+
+1. **Start from what the project already says**
+
+   If \`tospec/specs/\` has a capability this question touches, read its spec first: it says what the code is meant to do, which tells you what to look for. Do the same with the \`accepted\` ADRs in \`tospec/decisions/\` (\`index.md\` lists them) for why it is shaped this way. The code is what runs: where it disagrees with a spec or an ADR, explain the code and report the gap under Gotchas.
+
+2. **Size the question**
+
+   - **Simple** — one module, one utility, one function: explore it yourself, then go to step 4.
+   - **Complex** — a subsystem across several files or services, a cross-cutting feature, an architectural overview: go to step 3.
+
+   When in doubt, take the simple path.
+
+3. **Explore in parallel (complex only)**
+
+   Split the question into 2–4 angles, each a distinct slice (for example: entry points and wiring, the core data flow, persistence and state, error paths). If your tool can spawn subagents, spawn one read-only explorer per angle in a single message. Each prompt holds only the question, that explorer's angle, and the instruction to read \`EXPLORER.md\` at its path in this skill's directory and report in its shape; never paste the file into the prompt, which retypes it once per explorer. Otherwise work the angles yourself, one at a time, keeping notes in the shape \`EXPLORER.md\` gives. Then reconcile: merge overlaps, and settle any contradiction by reading the code yourself rather than picking one account.
+
+4. **Plan the page**
+
+   Follow \`WRITING.md\`: which sections apply, and which diagram answers which part of the question. Decide the diagrams before writing prose: the prose then walks the reader through them.
+
+5. **Write the page**
+
+   1. Get the output folder from \`page.mjs\` beside this file (it creates the folder if needed):
+      \`\`\`bash
+      node <this skill's directory>/page.mjs dir
+      \`\`\`
+   2. Write the content file \`<output folder>/<topic-slug>-<yyyyMMdd-HHmmss>.content.html\` in the format \`WRITING.md\` gives: the header lines, \`---\`, then the sections built from its components and diagram specs. Write only that: the build wraps it in \`skeleton.html\` beside this file, so never read or copy the skeleton.
+   3. Build the page; it is written beside the content file as \`<same name>.html\` and checked:
+      \`\`\`bash
+      node <this skill's directory>/page.mjs build <content file>
+      \`\`\`
+      Fix every FAIL line in the content file and build again. Never edit the built page: the next build overwrites it.
+
+6. **Report**
+
+   In the conversation, answer the question in 2–4 sentences (the gist of the Overview) and give the page's absolute path. Do not paste the whole explanation into the chat: the page is the explanation. Offer to open it in the default browser, and open it only when the user says so.
+
+**Guardrails**
+- **Never write inside the project** — the page lives only in the temp directory
+- **Explain the code that runs** — not the code a spec or ADR describes; report the difference instead
+- **Name the gaps** — whatever you could not trace goes under Open Questions; never paper over it`;
+function readAsset(name) {
+    return readFileSync(new URL(name, ASSET_DIR), 'utf-8');
+}
+export function getTospecHowSkillTemplate() {
+    return {
+        name: 'tospec-how',
+        description: 'Explain how part of the codebase works as an offline HTML page with architecture, sequence, state and flow diagrams, written to the system temp directory. Covers "how does X work", walkthroughs before changing something, and placement or layering questions ("where should this live", "which layer owns this"). Use for /tospec-how.',
+        instructions: `Explain how part of this codebase works — a subsystem, a flow, a module — at the level a senior engineer needs to build a working mental model before changing it, as an offline HTML page with diagrams.
+
+**Input**: The question: "how does X work", a code path to walk through before a change, or a placement question ("where should this live", "which layer owns this"). When the scope is ambiguous, state your interpretation and go; the user can redirect.
+
+${HOW_BODY}`,
+        license: 'MIT',
+        compatibility: 'Requires tospec CLI and Node.js.',
+        metadata: { author: 'tospec' },
+        // Explicit invocation only, as pstack's original is. "How does X work" is
+        // an everyday question, and auto-triggering on it turns a two-sentence
+        // answer into subagents, an HTML page and three permission prompts. No
+        // workflow runs this as a sub-step, so nothing depends on the model
+        // reaching it on its own.
+        disableModelInvocation: true,
+        allowedTools: ['Bash(tospec:*)', 'Read', 'Grep', 'Glob'],
+        extraFiles: {
+            'EXPLORER.md': EXPLORER_DOC,
+            'WRITING.md': WRITING_DOC,
+            'skeleton.html': readAsset('skeleton.html'),
+            'page.mjs': readAsset('page.mjs'),
+        },
+    };
+}
+//# sourceMappingURL=how.js.map

package/dist/core/templates/workflows/how.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"how.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/how.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,iFAAiF;AACjF,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,yBAAyB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;AAEtE,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BpB,CAAC;AAEF,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+JnB,CAAC;AAEF,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kGA2CiF,CAAC;AAEnG,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,YAAY,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,yBAAyB;IACvC,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,4UAA4U;QACzV,YAAY,EAAE;;;;EAIhB,QAAQ,EAAE;QACR,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,kCAAkC;QACjD,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,0EAA0E;QAC1E,uEAAuE;QACvE,uEAAuE;QACvE,oEAAoE;QACpE,0BAA0B;QAC1B,sBAAsB,EAAE,IAAI;QAC5B,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;QACxD,UAAU,EAAE;YACV,aAAa,EAAE,YAAY;YAC3B,YAAY,EAAE,WAAW;YACzB,eAAe,EAAE,SAAS,CAAC,eAAe,CAAC;YAC3C,UAAU,EAAE,SAAS,CAAC,UAAU,CAAC;SAClC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/templates/workflows/issue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"issue.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/issue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAyEjD,wBAAgB,2BAA2B,IAAI,aAAa,CAc3D"}
+{"version":3,"file":"issue.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/issue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAsFjD,wBAAgB,2BAA2B,IAAI,aAAa,CAc3D"}

package/dist/core/templates/workflows/issue.js

@@ -1,4 +1,6 @@
 import { VALIDATE_VERDICT_RULE } from '../fragments/validate.js';
+import { GIT_COMMAND_RULE } from '../fragments/change-diff.js';
+import { LEGITIMATE_STATE_RULE, PERF_MEASUREMENT, PREMISE_CHECK } from '../fragments/debugging.js';
 const ISSUE_BODY = `Diagnose before you propose a fix. Jumping to a hypothesis before you can reproduce the bug on command is the exact failure this workflow prevents.
 
 **Planning boundary**: The request that triggered this workflow authorizes diagnosis only, even if it asks to fix something. Diagnosis includes the feedback loop's failing test (step 3) and temporary \`[DEBUG-xxxx]\` logging (step 5). Do not edit project code beyond those, and do not start implementation in the same response: present the ticket and \`task.md\`, then wait for a new user request before starting \`tospec-apply\`.
@@ -29,20 +31,28 @@ const ISSUE_BODY = `Diagnose before you propose a fix. Jumping to a hypothesis b
 
    Do not skip this to go read code and form a theory. No red-capable command, no hypotheses.
 
+   ${PERF_MEASUREMENT}
+
 4. **Rank falsifiable hypotheses**
 
+   Two sources are worth a look before you rank. **A regression** (it used to work): the commit that broke it is a candidate. \`git log -S '<symbol>'\` or \`git log -L <start>,<end>:<file>\` on the code the loop drives lists the commits that changed it. \`git bisect run\` with the loop's command finds the commit directly, but it moves the checkout, so ask the user before starting it. A commit is not a cause: read its diff and rank the mechanism it changed. **A symptom that appears only after a restart**: suspect persisted state first (config files, caches, lock files, serialized data). ${GIT_COMMAND_RULE}
+
    List as many as the evidence genuinely supports — when the feedback loop already points at one cause, one or two is fine. Each hypothesis must predict something checkable: "if X is the cause, changing Y makes the bug disappear." A hypothesis you can't falsify is a vibe — sharpen it or drop it. Show the ranked list to the user before testing; they often have context that instantly re-ranks it ("we just touched that module"). Then continue verifying without waiting for a reply: if the user later supplies information that changes the order, re-rank and continue from the new top.
 
 5. **Verify hypotheses one at a time**
 
    Change one variable per probe. Tag any temporary debug logging with a unique prefix (\`[DEBUG-xxxx]\`) so cleanup is one grep. Stop at the first hypothesis the loop from step 3 confirms.
 
+   ${PREMISE_CHECK} If the assumption is false, re-rank from what the failed probes share that it did not predict. If every hypothesis is refuted, go back to step 4 with the new evidence: task.md is written on a confirmed cause only.
+
 6. **Write the diagnosis into task.md**
    \`\`\`bash
    tospec instructions task --change "<name>" --json
    \`\`\`
    Include: the symptom and how to reproduce it, the verified root cause (not a guess — how you verified it), why existing tests didn't already catch this, the fix plan, the test plan, and a checkbox task list for \`tospec-apply\`. This is where the issue's detail lives (the ticket only summarizes).
 
+   **Place the fix before you plan it.** ${LEGITIMATE_STATE_RULE} Then name the one fact the fix is safe because of (e.g. "no other caller passes null"), and how you established it: by running code that would fail if the fact were false, or, when nothing can run it, by the \`file:line\` that shows it, marked unproven. Fix Plan carries both.
+
    **Before moving on, reconcile Test Plan against Tasks.** Walk the Test Plan's "tests to add" items one by one and name the task that covers each. Every item must either map to a numbered task or say in the Test Plan why it needs none. Nothing checks this later: \`tospec validate\` sees two prose sections, and apply reports done when the Tasks boxes are ticked — so an item that never became a task is silently lost, and the change still looks complete.
 
 7. **Delta specs — only if behavior changes**
@@ -63,8 +73,11 @@ Summarize the confirmed root cause, the fix plan, and prompt: "Run \`tospec-appl
 - The request that invoked this workflow authorizes diagnosis only. Any fix instruction in it does not carry forward: don't edit project code beyond the feedback loop's failing test and temporary \`[DEBUG-xxxx]\` logging, and don't start \`tospec-apply\` in the same response — stop after presenting the ticket and \`task.md\` and wait for a new request
 - The ticket file and its timestamp are CLI-generated — never create, rename, or move ticket files; only edit the Summary in the existing stub
 - No hypotheses before a red-capable feedback loop exists
+- A performance loop's number carries its run count, range, and limiter before any hypothesis rests on it
 - Ranked, falsifiable hypotheses — as many as the evidence supports, never an unverified guess
 - Root cause must be verified, not assumed — state how you confirmed it
+- Two failed probes on one assumption: test the assumption before a third probe
+- Fix Plan says why the fix is not a guard over an illegitimate state, and names the one fact it is safe because of, proven or marked unproven
 - Every secret in pasted commands and output becomes \`<REDACTED>\`; steps that need the user's login are theirs to run, uncaptured
 - Every Test Plan item maps to a task, or the Test Plan says why it needs none
 - Don't write \`specs\` unless the fix actually changes external behavior`;

package/dist/core/templates/workflows/issue.js.map

@@ -1 +1 @@
-{"version":3,"file":"issue.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/issue.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAsDd,qBAAqB;;;;;;;;;;;;;;0EAcgD,CAAC;AAE3E,MAAM,UAAU,2BAA2B;IACzC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,6NAA6N;QAC1O,YAAY,EAAE;;;;EAIhB,UAAU,EAAE;QACV,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KACnF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"issue.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/issue.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAEnG,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA8Bd,gBAAgB;;;;mlBAI8jB,gBAAgB;;;;;;;;KAQ9lB,aAAa;;;;;;;;2CAQyB,qBAAqB;;;;;;;;;;;;KAY3D,qBAAqB;;;;;;;;;;;;;;;;;0EAiBgD,CAAC;AAE3E,MAAM,UAAU,2BAA2B;IACzC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE,6NAA6N;QAC1O,YAAY,EAAE;;;;EAIhB,UAAU,EAAE;QACV,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KACnF,CAAC;AACJ,CAAC"}

package/dist/core/templates/workflows/restate-your-goal.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Restate-Your-Goal Workflow Template
+ *
+ * Adapted from pstack's `in-your-own-words`: the agent says back, in its own
+ * words, what it thinks the user wants and why, so a misunderstanding surfaces
+ * before work builds on it. Read-only; unlike grill it interrogates nothing and
+ * hands off nothing — the user's reply decides what happens next.
+ *
+ * pstack's original is explicit-invocation only. This one stays model-invocable
+ * because `tospec-explore` and `tospec-grill` run it as the sub-step that
+ * confirms their conclusion, so it also has to say how to hand control back
+ * to a host workflow. Its prose names no host: a `tospec-<id>` mention reads
+ * as a dependency to findWorkflowReferenceGaps, and restate needs neither host.
+ */
+import type { SkillTemplate } from '../types.js';
+export declare function getTospecRestateYourGoalSkillTemplate(): SkillTemplate;
+//# sourceMappingURL=restate-your-goal.d.ts.map

package/dist/core/templates/workflows/restate-your-goal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restate-your-goal.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/restate-your-goal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAgCjD,wBAAgB,qCAAqC,IAAI,aAAa,CAcrE"}

package/dist/core/templates/workflows/restate-your-goal.js

@@ -0,0 +1,45 @@
+const RESTATE_BODY = `**This is a check on your understanding, not a step forward.** Read files and run read-only \`tospec\` commands if they help; write no code, source edits, or artifact files.
+
+**Ground it in what is already here**
+
+1. **The conversation** is the primary source: what the user asked for, what they corrected, what they rejected.
+2. **The change under discussion**, if the conversation is about exactly one: read its planning artifacts (\`tospec status --change "<name>" --json\` lists them) so the restatement agrees with what is written, or says where it does not.
+3. **Nothing to restate** — no request in context and no change under discussion: say so and stop. Do not invent a goal.
+
+**Write the restatement**
+
+Use your own words. Echoing the user's phrasing hides a misunderstanding; a paraphrase exposes it. Keep it short:
+
+- **Goal** — what the user wants to be true when this is done.
+- **Problem** — what is wrong or missing now, and who it affects.
+- **Decided** — choices the conversation settled, each with the reason it won. Omit when nothing was settled.
+- **Out of scope** — what was explicitly ruled out. Omit when nothing was.
+- **Assumptions** — what you inferred but the user never said. Mark each one as your guess.
+
+A host workflow that runs this as a sub-step may name extra items to cover (e.g. a grill's claims that held up and questions left open); add them after these.
+
+Restate the goal, not the solution. When the user asked for a specific implementation, name the problem it is meant to solve; when you cannot tell what that problem is, say so instead of filling the gap.
+
+**Stop and let the user answer**
+
+End by asking the user to confirm or correct the restatement, then stop. If they correct it, restate again with the correction folded in. Running out of things to say is not confirmation; only the user's "yes" is.
+
+After the user confirms:
+- **Run as a sub-step of another workflow**: return to that workflow's next step. The confirmed restatement stays in the conversation as its input.
+- **Run on its own**: stop there. Do not resume earlier work in the same turn; the user's next message decides what happens.`;
+export function getTospecRestateYourGoalSkillTemplate() {
+    return {
+        name: 'tospec-restate-your-goal',
+        description: "Restate in your own words what you think the user's goal is and what problem they are trying to solve, then wait for them to confirm or correct it. Use when the user asks you to restate, summarize what they want, or check you are on the same page, and when a discussion has converged and its conclusion needs the user's confirmation before anything is written.",
+        instructions: `Restate in your own words what you think the user's goal is and what problem they are trying to solve.
+
+**Input**: Optional. A focus for the restatement (a change name, or one part of the request). When empty, restate the goal behind the whole conversation so far.
+
+${RESTATE_BODY}`,
+        license: 'MIT',
+        compatibility: 'Requires tospec CLI.',
+        metadata: { author: 'tospec' },
+        allowedTools: ['Bash(tospec:*)', 'Read', 'Grep', 'Glob'],
+    };
+}
+//# sourceMappingURL=restate-your-goal.js.map

package/dist/core/templates/workflows/restate-your-goal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restate-your-goal.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/restate-your-goal.ts"],"names":[],"mappings":"AAgBA,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;6HA4BwG,CAAC;AAE9H,MAAM,UAAU,qCAAqC;IACnD,OAAO;QACL,IAAI,EAAE,0BAA0B;QAChC,WAAW,EAAE,0WAA0W;QACvX,YAAY,EAAE;;;;EAIhB,YAAY,EAAE;QACZ,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KACzD,CAAC;AACJ,CAAC"}

package/dist/core/templates/workflows/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/update.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA8EjD,wBAAgB,4BAA4B,IAAI,aAAa,CAc5D"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/update.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA+EjD,wBAAgB,4BAA4B,IAAI,aAAa,CAc5D"}

package/dist/core/templates/workflows/update.js

@@ -39,6 +39,7 @@ const UPDATE_BODY = `**Steps**
 
    This is the only step that writes files.
    - Show each drafted revision and why. Write it only after the user confirms.
+   - Apply a confirmed revision as edits to the passages it changes, and leave the rest of the file as it is. Rewrite a whole file only when the revision replaces most of it: retyping an artifact to change one paragraph costs its full length, and any slip on the way alters text the user never saw in the revision.
    - If the user rejects a revision, leave that artifact unchanged.
    - When a substantial rewrite is needed, get that artifact's rules and template first:
      \`\`\`bash

package/dist/core/templates/workflows/update.js.map

@@ -1 +1 @@
-{"version":3,"file":"update.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/update.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8CAmD0B,qBAAqB;;;KAG9D,iBAAiB,CAAC,mCAAmC,EAAE,uDAAuD,CAAC;;;;;;;;;;;;;;;;;;oLAkBgE,CAAC;AAErL,MAAM,UAAU,4BAA4B;IAC1C,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,oPAAoP;QACjQ,YAAY,EAAE;;;;EAIhB,WAAW,EAAE;QACX,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KAC7F,CAAC;AACJ,CAAC"}
+{"version":3,"file":"update.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/update.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8CAoD0B,qBAAqB;;;KAG9D,iBAAiB,CAAC,mCAAmC,EAAE,uDAAuD,CAAC;;;;;;;;;;;;;;;;;;oLAkBgE,CAAC;AAErL,MAAM,UAAU,4BAA4B;IAC1C,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,oPAAoP;QACjQ,YAAY,EAAE;;;;EAIhB,WAAW,EAAE;QACX,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;KAC7F,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanmars/tospec",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Spec-driven development CLI for structured requirements and issue workflows",
   "license": "MIT",
   "homepage": "https://www.npmjs.com/package/@seanmars/tospec",
@@ -37,7 +37,7 @@
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^24.13.4",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.5"
   },
   "dependencies": {
     "@inquirer/core": "^12.0.3",