synorch 0.2.0 → 0.3.0

package/dist/templates/skill-creator-skill.js

@@ -0,0 +1,235 @@
+import { createEmptyLedger } from "../domain/observation-ledger.js";
+import { stringifyYaml } from "../infrastructure/serialization.js";
+export const skillCreatorSkill = `---
+name: skill-creator
+description: Use at task completion to record non-obvious project discoveries as sourced observations, and to propose, author, review and activate a generated project skill once one observation has been confirmed by three distinct tasks or corrected by the user.
+not_for: Mid-task use, first sessions, and cold repository scans. A trivial task may record observations but never proposes a skill.
+version: 1.0.0
+references:
+  - references/observation-ledger.md
+  - references/generated-skill-contract.md
+  - references/retirement.md
+---
+
+# Skill Creator
+
+The system earns a skill; it never assumes one. Observations are cheap and unattended. Promotion is rare, approved by the user, written by a worker and verified by an independent reviewer.
+
+## When this applies
+
+- At the end of a completed task, while writing the final report, for every worker completion packet.
+- When the user corrects an approach ("not that way, this way"): record the observation and propose immediately.
+- When \`doctor\` reports stale evidence, or a worker identifies a stale or superseded project skill and a natural pause has arrived.
+
+## When it does not
+
+- Mid-task. Recording is a completion step; proposing interrupts nothing that is still running.
+- On a first session, or from a repository scan. Day one has facts, not procedures; the project record already holds the facts.
+- For anything a bundled technology skill already covers, or for a discovery with no source path.
+- Never propose more than one skill in one final report. If several are ready, take the highest \`count\` and leave the rest.
+
+## Required inputs
+
+- The completed task's id, and the worker completion packets with their \`commands_run\`, \`decisions_made\` and source paths.
+- \`.ai/tasks/observations.yaml\` (the ledger) and the current contents of \`.ai/skills/project/\`.
+- For a proposal: the user's explicit approval, and the active project-skill count.
+
+## Procedure
+
+1. **Qualify.** An observation must be non-obvious, repeatable and carry at least one source path. No source, no observation. Discard anything a bundled skill already states.
+2. **Record.** Append or update the entry in \`.ai/tasks/observations.yaml\` — the orchestrator's only writable area, so this needs no constitutional change. Increment \`tasks_seen\` exactly once per completed task. Format and expiry: \`references/observation-ledger.md\`.
+3. **Confirm.** Add the task id to \`confirmed_by\` only if it is not already there. The same task hitting the same wall twice counts once. Set \`count\` to the number of distinct ids and \`last_seen_task_index\` to \`tasks_seen\`.
+4. **Decide.** At \`count\` 3, set \`status: ready-to-propose\`. A user correction sets \`origin: user-correction\` and is ready at once.
+5. **Budget.** Before proposing, count \`status: active\` skills under \`.ai/skills/project/\`. At 12, propose a retirement first and let the user choose; do not propose an addition alongside it.
+6. **Propose.** In the final report, state the claim, its sources and its confirming task ids, and ask. On approval continue; on refusal set \`status: declined\`, which is permanent — never ask again for that id.
+7. **Author.** Delegate to an implementer: write \`.ai/skills/project/<id>/SKILL.md\` against the contract in \`references/generated-skill-contract.md\`.
+8. **Review.** Delegate to an independent reviewer, never the author. The reviewer opens every \`source\`, confirms the claim it backs and recomputes its digest.
+9. **Activate.** Only after the review passes, and only through two writes: the implementer sets \`status: active\` in the skill's own frontmatter, and the orchestrator sets the observation to \`status: promoted\` with \`promoted_to: <id>\`. There is no registry entry to make — \`.ai/projects/<id>.skills.yaml\` is regenerated by every \`sync\` and sits outside \`.ai/tasks/**\`.
+10. **Maintain.** Apply stale-evidence and manually identified supersession signals from \`references/retirement.md\` at the next pause. The first slice has no skill-usage telemetry, so usage-based retirement is manual.
+
+## Tools
+
+File reads for sources; the ledger write; \`syn doctor\` for the contract, budget, size and digest checks; delegation to an implementer and a reviewer. No model call inside the CLI, and no external skill import.
+
+## Verification
+
+- \`syn doctor\` reports no \`generated.*\` error for the new skill.
+- Every \`evidence\` entry names a file that exists inside the root and whose digest matches.
+- The active project-skill count is at most 12 and the file is at most 15KB.
+- The reviewer's report names each claim and the source it was checked against.
+
+## Stop and escalate
+
+- Stop if a claim cannot be traced to a source, if the reviewer rejects any claim, or if the author and the reviewer are the same worker.
+- Stop if the proposal would exceed the budget without an approved retirement.
+- Stop and ask if the content would belong in a protocol or the constitution. A generated skill holds \`priority: skill\` only; it never overrides a core protocol and never claims constitutional authority.
+- Never delete a skill. Retirement is proposed, then the implementer moves the file to \`RETIRED.md\` and sets \`status: retired\`, and the orchestrator records it in the ledger.
+
+## Output contract
+
+Ledger entries are the ordinary output. A promotion additionally yields: one proposal paragraph in the final report; on approval, \`.ai/skills/project/<id>/SKILL.md\` with complete evidence frontmatter and \`status: active\`; a reviewer verdict per claim; and the observation moved to \`status: promoted\` with \`promoted_to\` naming the skill.
+`;
+const observationLedgerReference = `# Observation Ledger
+
+\`.ai/tasks/observations.yaml\` is Git-tracked and lives inside the orchestrator's writable area. Per-task working directories under \`.ai/tasks/\` are not tracked.
+
+## Format
+
+\`\`\`yaml
+schema_version: 1
+tasks_seen: 174
+observations:
+  - id: api-test-execution
+    claim: >
+      API tests must run with cwd services/api and
+      TESTCONTAINERS_RYUK_DISABLED=true, or they fail on startup.
+    kind: command-behavior
+    sources:
+      - path: services/api/package.json
+        digest: sha256:9f2c1d3b4a5e6f708192a3b4c5d6e7f8
+      - path: .github/workflows/ci.yml
+        digest: sha256:41ab5c6d7e8f9012a3b4c5d6e7f80192
+    confirmed_by: [task-141, task-156, task-173]
+    count: 3
+    origin: worker-discovery
+    first_seen_at: 2026-09-14
+    last_seen_at: 2026-09-22
+    last_seen_task_index: 173
+    status: ready-to-propose
+\`\`\`
+
+## Fields
+
+- \`kind\` is one of \`command-behavior\`, \`convention\`, \`ordering-constraint\`, \`pitfall\`, \`boundary\`. It exists to make deduplication tractable: a new observation that shares a \`kind\` and a source path with an existing one updates it instead of adding a second entry.
+- \`origin\` is \`worker-discovery\` or \`user-correction\`.
+- \`status\` is one of \`collecting\`, \`ready-to-propose\`, \`proposed\`, \`promoted\`, \`declined\`, \`expired\`.
+- \`promoted_to\` is optional and set only on promotion: the id of the generated skill this observation became. It is half of the activation record; the other half is \`status: active\` in that skill's own frontmatter. There is no third place, and no registry entry.
+- \`digest\` is \`sha256:<hex>\` over the source file's bytes with line endings normalized to \`\\n\`. A prefix of at least 32 hex characters is accepted; anything shorter is not treated as a match.
+- \`count\` must equal the number of distinct ids in \`confirmed_by\`.
+
+## The two counters
+
+\`tasks_seen\` is a monotonic count of completed tasks. Increment it exactly once per completed task, in the same write that records or reconfirms observations. \`last_seen_task_index\` stores the value of \`tasks_seen\` at an observation's last confirmation.
+
+That pair is what makes the task-based expiry rule decidable without a clock or a task history: an observation is \`20 tasks\` old when \`tasks_seen - last_seen_task_index >= 20\`.
+
+## Expiry
+
+An unpromoted observation expires 90 days after \`last_seen_at\` or 20 tasks after \`last_seen_task_index\`, whichever comes first. \`syn sync\` prunes expired entries and reports how many it removed. \`promoted\` and \`declined\` entries are never pruned: \`declined\` is permanent so the user is not asked twice.
+
+A one-off oddity is not a procedure. Expiry is the structural immunity against a ledger that turns into an incident log.
+`;
+const generatedSkillContractReference = `# Generated Skill Contract
+
+A generated skill lives at \`.ai/skills/project/<id>/SKILL.md\`. \`syn sync\` never writes, overwrites or deletes anything in that namespace, even with \`--force\`.
+
+## Frontmatter
+
+\`\`\`yaml
+---
+name: api-test-execution
+description: How to run and debug the API test suite in this repository.
+version: 1.0.0
+priority: skill
+origin: generated
+status: active
+generated_at: 2026-09-22
+verified_at: 2026-09-22
+confirmations: 3
+promotion: threshold
+confirmed_by: [task-141, task-156, task-173]
+evidence:
+  - claim: Tests require cwd services/api
+    source: services/api/package.json
+    digest: sha256:9f2c1d3b4a5e6f708192a3b4c5d6e7f8
+  - claim: TESTCONTAINERS_RYUK_DISABLED=true is required locally
+    source: .github/workflows/ci.yml
+    digest: sha256:41ab5c6d7e8f9012a3b4c5d6e7f80192
+supersedes: []
+---
+\`\`\`
+
+\`promotion\` is \`threshold\` for the ordinary three-confirmation path, or \`user-correction\` for the fast path. It is the only way a skill may carry fewer than three confirmations, and it must be stated explicitly.
+
+## Blocking rules
+
+1. \`origin: generated\` requires a non-empty \`evidence\` list; every entry needs a \`claim\`, a \`source\` and a \`digest\`.
+2. Every \`source\` exists and stays inside the root under both lexical and realpath checks.
+3. \`priority\` is \`skill\`. \`constitutional\`, \`core\` and any protocol-level value are rejected.
+4. \`SKILL.md\` is at most 15KB.
+5. At most 12 project skills are \`active\`.
+6. Every id in \`confirmed_by\` appears in the observation ledger.
+
+## Body
+
+The same sections every skill carries: When this applies, When it does not, Required inputs, Procedure, Tools, Verification, Stop and escalate, Output contract.
+
+Write a repeatable procedure, not a story. Every factual claim in the body must be backed by an \`evidence\` entry; \`doctor\` warns on an unsourced path, on a missing activation condition and on past-tense incident narration.
+
+## Authoring and review
+
+The implementer writes the file. A different worker reviews it, opening each \`source\` and confirming the claim it backs.
+
+Activation is expressed in exactly two places, and nowhere else. The implementer sets \`status: active\` in this frontmatter, which is what \`doctor\` counts against the twelve-skill budget. The orchestrator then sets the observation to \`status: promoted\` and records \`promoted_to: <id>\`. There is no registry entry: \`.ai/projects/<id>.skills.yaml\` is regenerated by every \`sync\`, has no project-skill slot, and lies outside the orchestrator's \`.ai/tasks/**\` write scope. The orchestrator writes the ledger only — never the skill file itself.
+`;
+const retirementReference = `# Retirement
+
+Nothing is ever deleted automatically. Every signal below produces a proposal at the next natural pause; the user decides.
+
+## Implemented signals
+
+- **Stale.** \`doctor\` warns when a source digest changes. Re-verify at the next pause; when a worker confirms that the claim no longer holds, the implementer sets \`status: stale\`.
+- **Unused.** The first slice does not track when a skill was loaded, so \`doctor\` cannot infer unused skills. The user or a worker may propose retirement manually.
+- **Superseded.** A worker or reviewer identifies overlap with an existing skill. Propose a merge into the existing skill rather than a second skill, and record the lineage in \`supersedes\`.
+
+## Executing an approved retirement
+
+1. The implementer moves \`.ai/skills/project/<id>/SKILL.md\` to \`.ai/skills/project/<id>/RETIRED.md\` and sets \`status: retired\` in its frontmatter. That is what frees the budget slot: \`doctor\` counts \`status: active\` frontmatter, and nothing else.
+2. The orchestrator records the retirement in the ledger. There is no registry entry to drop — \`.ai/projects/<id>.skills.yaml\` is regenerated by every \`sync\` and never carries project skills.
+3. Leave the Git history alone. Nothing is deleted from it.
+
+A retired skill frees a slot in the 12-skill budget. That budget is the only brake on accumulation, so retirement is a routine act, not a failure.
+`;
+const taskDirectoryIgnore = `# Per-task orchestrator working directories are local state, not shared history.
+# The observation ledger is the exception: it is the distillation record and is tracked.
+*
+!.gitignore
+!.gitkeep
+!observations.yaml
+`;
+/**
+ * The reference documents of the `skill-creator` base skill. `BASE_SKILL_DOCUMENTS` in
+ * `base-skills.ts` is the single place that turns these into files, exactly as it does for
+ * every other base skill, so the skill and its references can never be emitted twice.
+ */
+export const skillCreatorReferences = [
+    { fileName: "observation-ledger.md", content: observationLedgerReference },
+    { fileName: "generated-skill-contract.md", content: generatedSkillContractReference },
+    { fileName: "retirement.md", content: retirementReference },
+];
+/**
+ * The control-plane files the distillation loop needs beside the skill itself: the Git-tracked
+ * observation ledger and the ignore rule that keeps per-task working directories out of history.
+ * They are canonical structure rather than skill content, so `createStructureFiles` emits them.
+ *
+ * The two carry different write policies on purpose. The ignore rule is pure canonical policy
+ * with no user state in it, so `--force` may refresh it. The ledger is the opposite: from the
+ * first completed task it holds approved, promoted and permanently declined observations that
+ * only the orchestrator and the user may change. It is therefore seeded once and never
+ * rewritten — design D12 and §9 forbid destroying user-approved state, and `syn init --force`
+ * is the documented migration command, so it must not be the command that erases it.
+ */
+export const skillCreatorLedgerFiles = [
+    file(".ai/tasks/observations.yaml", stringifyYaml(createEmptyLedger()), "canonical", "create-only"),
+    file(".ai/tasks/.gitignore", taskDirectoryIgnore, "canonical"),
+];
+/** Mirrors the private helper in structure-templates.ts; kept local so nothing private is imported. */
+function file(relativePath, content, kind, writePolicy = "overwrite") {
+    return {
+        relativePath,
+        content: content.length === 0 || content.endsWith("\n") ? content : `${content}\n`,
+        kind,
+        writePolicy,
+    };
+}
+//# sourceMappingURL=skill-creator-skill.js.map

package/dist/templates/skill-creator-skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-creator-skill.js","sourceRoot":"","sources":["../../src/templates/skill-creator-skill.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAGnE,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoEhC,CAAC;AAEF,MAAM,0BAA0B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiDlC,CAAC;AAEF,MAAM,+BAA+B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoDvC,CAAC;AAEF,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;CAiB3B,CAAC;AAEF,MAAM,mBAAmB,GAAG;;;;;;CAM3B,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsC;IACvE,EAAE,QAAQ,EAAE,uBAAuB,EAAE,OAAO,EAAE,0BAA0B,EAAE;IAC1E,EAAE,QAAQ,EAAE,6BAA6B,EAAE,OAAO,EAAE,+BAA+B,EAAE;IACrF,EAAE,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,mBAAmB,EAAE;CAC5D,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA8B;IAChE,IAAI,CACF,6BAA6B,EAC7B,aAAa,CAAC,iBAAiB,EAAE,CAAC,EAClC,WAAW,EACX,aAAa,CACd;IACD,IAAI,CAAC,sBAAsB,EAAE,mBAAmB,EAAE,WAAW,CAAC;CAC/D,CAAC;AAEF,uGAAuG;AACvG,SAAS,IAAI,CACX,YAAoB,EACpB,OAAe,EACf,IAA4B,EAC5B,cAA+B,WAAW;IAE1C,OAAO;QACL,YAAY;QACZ,OAAO,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI;QAClF,IAAI;QACJ,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/templates/skill-references.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Progressive-disclosure reference files for the canonical base skills.
+ *
+ * A reference costs nothing until a step in its skill actually needs it, so it
+ * carries the worked examples, catalogues and rubrics that would otherwise
+ * bloat a just-in-time `SKILL.md`. Each file is declared in its skill's
+ * `references` frontmatter and generated under the skill's own directory.
+ */
+export declare const riskClassificationReference = "# Risk Classification \u2014 Worked Examples\n\nUse this file when a brief does not obviously land in one tier, or when someone\ndisputes a classification. The tier definitions live in\n`.ai/protocols/core/orchestration.md`; this file only shows how they are applied.\n\n## The deciding questions\n\nAsk them in order. The first \"yes\" sets the floor; nothing below it applies.\n\n1. Can this change corrupt, expose or lose data that already exists?\n2. Does it alter a contract someone outside this repository depends on?\n3. Does it touch authentication, authorization, secrets, payments or money?\n4. Does it change concurrency, ordering, retries or idempotency?\n5. Does it change behavior a user or another service can observe?\n6. Does it span more than one module, or more than one owner?\n\nQuestions 1\u20134 mean high-risk. Question 5 alone means standard. Question 6 alone\nmeans standard. None of them means trivial.\n\n## Worked examples\n\n| Brief | Tier | Why |\n| --- | --- | --- |\n| Fix a typo in a button label | trivial | No behavior, no contract, reversible in one line. |\n| Rename a private helper used in one file | trivial | No external name changes; the compiler proves the rename. |\n| Bump a patch version of a dev-only formatter | trivial | No runtime artifact changes. |\n| Add a nullable, unused column with a default | standard | Schema change, but no reader depends on it yet. |\n| Add a field to an existing API response | standard | Observable behavior; additive, so no consumer breaks. |\n| Extract a component used by three screens | standard | Multi-file, but behavior is meant to be identical. |\n| Change a cache expiry from 60s to 600s | standard | Observable staleness change, bounded blast radius. |\n| Add an index to a large production table | high-risk | Locking and write-path impact during migration. |\n| Change a password hash or token lifetime | high-risk | Authentication surface. |\n| Make a sequential job run in parallel | high-risk | New ordering and idempotency assumptions. |\n| Drop or rename a column still read by code | high-risk | Destructive and irreversible without a backup. |\n| Change the rounding of an invoice total | high-risk | Money, and every historical comparison shifts. |\n\n## Traps that misclassify\n\n- **\"It is only a config change.\"** Config that selects a code path is a code\n  change with no test coverage. Tier it by what the path does.\n- **\"It is only one line.\"** Size is not risk. A one-line change to a permission\n  check is high-risk; a hundred-line change to a test fixture is trivial.\n- **\"The tests pass.\"** Passing tests classify nothing. They tell you what is\n  already covered, not what the change can break.\n- **\"We will verify it in production.\"** That is a decision to accept risk, not\n  a reason to lower the tier. Record it as an accepted risk in the plan.\n- **\"It is a revert.\"** A revert of a migrated schema is not symmetrical with\n  the migration. Tier it on what the revert itself does.\n\n## Escalating a tier mid-task\n\nEscalate, record the reason, and re-open approval when any of these appear:\n\n- A verified fact contradicts an assumption the plan rested on.\n- The change turns out to need a file the plan did not name.\n- A check fails for a reason no one predicted.\n- The worker asks for authority the packet did not grant.\n\nNever lower a tier because the work is taking longer than expected. Lower it\nonly when evidence removes the risk that set it, and say which evidence did.\n";
+export declare const evidenceLadderReference = "# Evidence Ladder \u2014 Worked Examples\n\nThe rungs and the browser policy are defined in\n`.ai/protocols/core/verification.md`. This file shows which evidence actually\nproves which claim, and which evidence only looks like proof.\n\n## Claim to evidence\n\n| Claim | Sufficient evidence | Not sufficient |\n| --- | --- | --- |\n| \"The label now reads X.\" | The diff hunk showing the literal, plus a search proving no other copy exists. | \"I changed it.\" |\n| \"The function handles null.\" | A unit test asserting the null path, failing before the change. | Reading the new branch. |\n| \"No caller breaks.\" | A type check, or an exhaustive search of call sites with each one listed. | \"It is backwards compatible.\" |\n| \"The bug is fixed.\" | The original reproduction command, before and after, with output. | The test suite passing. |\n| \"Performance improved.\" | The same measurement command before and after, with both numbers. | A reasoned argument about complexity. |\n| \"The migration is safe.\" | A dry run against a copy of real-shaped data, plus the rollback path. | A review of the SQL. |\n| \"Nothing else changed.\" | The full diff, read hunk by hunk. | The summary of the diff. |\n| \"The endpoint returns 403 for anonymous users.\" | A request-level test asserting the status. | The presence of a guard annotation. |\n\n## Choosing the cheapest sufficient rung\n\nAsk: *what observation would change my mind?* Run that, and stop.\n\n- A claim about a literal is settled by a search. Running the test suite adds\n  minutes and zero information.\n- A claim about a type boundary is settled by the type checker. A runtime test\n  adds nothing the compiler did not already prove.\n- A claim about behavior at an integration seam is not settled by a unit test\n  with the seam mocked. The mock encodes the assumption under test.\n- A claim about a rendered pixel, a focus order or a real browser event is the\n  only case where a headed browser is the cheapest sufficient evidence \u2014 and it\n  still requires the approval the protocol demands.\n\n## Recording evidence\n\nRecord, for every check: the exact command, the working directory, the outcome,\nand the reason for any check deliberately not run. Three failure modes to avoid:\n\n1. **Paraphrasing a command.** `pnpm test` and `pnpm test src/foo` are\n   different evidence. Record what ran, not what it resembled.\n2. **Reporting a check that did not run.** If it was skipped, name it as\n   skipped. An honest gap is cheaper than a false claim discovered later.\n3. **Reporting a pass that was not read.** A green exit code from a command\n   that matched zero tests proves nothing. Confirm the check had subjects.\n\n## Worked example \u2014 a trivial change\n\nObjective: correct a misspelled key in one constant.\n\n1. Diff: one line, one file. **Rung 1.**\n2. Search for the old spelling across the repository: no other occurrence.\n3. Stop. No lint, no build, no test suite, no reviewer, no browser.\n4. Record: \"grep -r oldKey \u2192 0 hits; suite not run (unaffected).\"\n\n## Worked example \u2014 a standard change\n\nObjective: an API response gains an optional field.\n\n1. Diff read hunk by hunk. **Rung 1.**\n2. Type check and the serializer's own unit tests. **Rung 2.**\n3. One request-level test asserting the field is present and optional.\n4. Integration suite only if a consumer in this repository parses strictly.\n5. Independent review because the change crosses a published boundary.\n6. Record every command, plus \"end-to-end suite not run: no UI path changed.\"\n";
+export declare const hypothesisPatternsReference = "# Hypothesis Patterns and Failure Catalogue\n\nOpen this file when the reproduction is in hand and the hypothesis list is\nshort, obvious and wrong. It exists to widen the candidate set before effort is\nspent confirming a favourite.\n\n## Writing a falsifiable hypothesis\n\nA usable hypothesis names a mechanism and predicts an observation.\n\n- Weak: \"something is wrong with the cache.\"\n- Usable: \"the cache key omits the tenant id, so tenant B reads tenant A's\n  entry. If true, two requests differing only by tenant return the same body.\"\n\nEvery hypothesis must come with the cheapest observation that would **disprove**\nit. Rank by `likelihood / cost of disproof`, and test the cheapest first.\n\n## The failure catalogue\n\n### It works locally but not in the other environment\n\n- Configuration or secret differs, and the code falls back silently.\n- Version skew: a dependency resolved differently by an unpinned range.\n- Case-sensitive file system on one side, case-insensitive on the other.\n- Timezone or locale of the host changes parsing or formatting.\n- A build step runs in one environment and not the other.\n\n### It worked yesterday\n\n- A dependency floated to a new version; check the lockfile diff first.\n- A clock, an expiry or a certificate crossed a boundary.\n- Data grew past a limit: a page size, a timeout, an index that stopped being used.\n- A feature flag or remote configuration changed outside the repository.\n\n### It fails only sometimes\n\n- Order dependence between tests sharing mutable state.\n- A race between an async write and the read that follows it.\n- Time-of-day, date-boundary or leap-related arithmetic.\n- Retry logic masking a failure until the retry budget is exhausted.\n- Hash or set iteration order treated as stable.\n\n### The error message points at innocent code\n\n- The reported frame is where the bad value was *used*, not where it was made.\n  Walk the value backwards to its origin.\n- A wrapper re-threw and lost the cause; find the original throw site.\n- A null or default was substituted upstream by a permissive parser.\n- The stack belongs to a different async context than the failure.\n\n### The fix does not stick\n\n- Two code paths do the same thing and only one was changed.\n- A cached, generated or committed artifact still holds the old value.\n- The test asserts the mock, not the code.\n- The change is correct but never runs: the branch condition is false.\n\n## Reduction techniques\n\n- **Bisect the input.** Halve the failing input until the minimal trigger remains.\n- **Bisect history.** Find the last good commit; the diff bounds the cause.\n- **Bisect the stack.** Assert the value at the midpoint between the origin and\n  the symptom; each assertion halves the remaining search space.\n- **Invert.** Instead of asking why it fails, construct the closest case that\n  succeeds and diff the two.\n\n## Before calling it a root cause\n\n1. You can state the mechanism in one sentence, cause to symptom.\n2. You can explain why it did not fail earlier, or elsewhere.\n3. A regression test fails before the fix and passes after it.\n4. The fix touches the cause, not the place the symptom was observed.\n\nIf any of the four is missing, you have a correlation. Say so, and escalate\nrather than shipping a fix whose mechanism you cannot state.\n";
+export declare const severityRubricReference = "# Review Severity Rubric and Checklist\n\nOpen this file when classifying a finding, or when a review needs a systematic\npass rather than an impression. The verdict vocabulary is fixed so that\n\"blocking\" means the same thing to every reviewer.\n\n## Severity rubric\n\n| Severity | Definition | Reviewer action |\n| --- | --- | --- |\n| `blocking` | The change is incorrect, unsafe, or fails an approved acceptance criterion. Shipping it causes harm or rework. | Reject. Name the location, the mechanism and the consequence. |\n| `required` | Correct for the approved case, but leaves a defect that will surface under a stated, realistic condition. | Approve only with a named follow-up owner and task. |\n| `advisory` | A real improvement that is out of scope for the approved change. | Report; never block on it. |\n| `note` | Context a future reader will want. No action implied. | Report at most a handful. |\n\nA finding with no consequence is not a finding. If you cannot complete the\nsentence \"if this ships unchanged, then \u2026\", it is at most a note.\n\n## Blocking, by category\n\n- **Correctness.** The code does not do what the criterion says, on the inputs\n  the criterion names.\n- **Regression.** An existing behavior covered by a test or a caller changes\n  without being part of the approved scope.\n- **Security.** Missing authorization, injected input reaching an interpreter,\n  a secret in the diff, a permission widened without justification.\n- **Data.** Irreversible migration without a rollback, a write that can partially\n  apply, a unique constraint the code does not honour.\n- **Concurrency.** A read-modify-write without a guard, an await inside a lock, a\n  shared mutable default.\n- **Evidence.** The packet reports a check that did not run, or the named\n  evidence does not prove the claim it is attached to.\n\n## The checklist\n\nRun in order. Stop at the first section that produces a blocking finding, report\nit, and finish the remaining sections at low cost rather than in depth.\n\n1. **Scope.** Does every changed file appear in the approved ownership? Is any\n   hunk unrelated to the objective?\n2. **Criteria.** For each acceptance criterion, name the hunk that satisfies it.\n   A criterion with no hunk is blocking.\n3. **Edges.** For each new branch: what happens on empty, null, zero, one,\n   duplicate, very large, and concurrent?\n4. **Errors.** Is every failure path either handled or deliberately propagated?\n   Is any error swallowed into a default?\n5. **Boundaries.** Did a public type, route, schema, event or column change? Is\n   the change additive?\n6. **Tests.** Does a new test fail without the change? Does it assert behavior\n   rather than the shape of the implementation?\n7. **Evidence.** Re-run the cheapest reported command. Does it pass, and does it\n   cover the change?\n8. **Leftovers.** Debug output, commented code, skipped tests, temporary files,\n   unrelated formatting.\n\n## What not to raise\n\n- Preferences the project does not enforce in lint, formatter or existing code.\n- Rewrites of code the diff only moved.\n- Hypothetical scale the project has never stated a requirement for.\n- Duplicate findings: report the pattern once and list the locations.\n\n## Wording a finding\n\n`path:line` \u2014 severity \u2014 what is wrong \u2014 what happens if it ships \u2014 the\nsmallest change that resolves it. Four sentences at most. If a finding needs\nmore, the change needs a conversation, not a comment.\n";
+//# sourceMappingURL=skill-references.d.ts.map

package/dist/templates/skill-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-references.d.ts","sourceRoot":"","sources":["../../src/templates/skill-references.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,2BAA2B,q8GA6DvC,CAAC;AAEF,eAAO,MAAM,uBAAuB,+/GAgEnC,CAAC;AAEF,eAAO,MAAM,2BAA2B,wxGA2EvC,CAAC;AAEF,eAAO,MAAM,uBAAuB,u7GAmEnC,CAAC"}

package/dist/templates/skill-references.js

@@ -0,0 +1,280 @@
+/**
+ * Progressive-disclosure reference files for the canonical base skills.
+ *
+ * A reference costs nothing until a step in its skill actually needs it, so it
+ * carries the worked examples, catalogues and rubrics that would otherwise
+ * bloat a just-in-time `SKILL.md`. Each file is declared in its skill's
+ * `references` frontmatter and generated under the skill's own directory.
+ */
+export const riskClassificationReference = `# Risk Classification — Worked Examples
+
+Use this file when a brief does not obviously land in one tier, or when someone
+disputes a classification. The tier definitions live in
+\`.ai/protocols/core/orchestration.md\`; this file only shows how they are applied.
+
+## The deciding questions
+
+Ask them in order. The first "yes" sets the floor; nothing below it applies.
+
+1. Can this change corrupt, expose or lose data that already exists?
+2. Does it alter a contract someone outside this repository depends on?
+3. Does it touch authentication, authorization, secrets, payments or money?
+4. Does it change concurrency, ordering, retries or idempotency?
+5. Does it change behavior a user or another service can observe?
+6. Does it span more than one module, or more than one owner?
+
+Questions 1–4 mean high-risk. Question 5 alone means standard. Question 6 alone
+means standard. None of them means trivial.
+
+## Worked examples
+
+| Brief | Tier | Why |
+| --- | --- | --- |
+| Fix a typo in a button label | trivial | No behavior, no contract, reversible in one line. |
+| Rename a private helper used in one file | trivial | No external name changes; the compiler proves the rename. |
+| Bump a patch version of a dev-only formatter | trivial | No runtime artifact changes. |
+| Add a nullable, unused column with a default | standard | Schema change, but no reader depends on it yet. |
+| Add a field to an existing API response | standard | Observable behavior; additive, so no consumer breaks. |
+| Extract a component used by three screens | standard | Multi-file, but behavior is meant to be identical. |
+| Change a cache expiry from 60s to 600s | standard | Observable staleness change, bounded blast radius. |
+| Add an index to a large production table | high-risk | Locking and write-path impact during migration. |
+| Change a password hash or token lifetime | high-risk | Authentication surface. |
+| Make a sequential job run in parallel | high-risk | New ordering and idempotency assumptions. |
+| Drop or rename a column still read by code | high-risk | Destructive and irreversible without a backup. |
+| Change the rounding of an invoice total | high-risk | Money, and every historical comparison shifts. |
+
+## Traps that misclassify
+
+- **"It is only a config change."** Config that selects a code path is a code
+  change with no test coverage. Tier it by what the path does.
+- **"It is only one line."** Size is not risk. A one-line change to a permission
+  check is high-risk; a hundred-line change to a test fixture is trivial.
+- **"The tests pass."** Passing tests classify nothing. They tell you what is
+  already covered, not what the change can break.
+- **"We will verify it in production."** That is a decision to accept risk, not
+  a reason to lower the tier. Record it as an accepted risk in the plan.
+- **"It is a revert."** A revert of a migrated schema is not symmetrical with
+  the migration. Tier it on what the revert itself does.
+
+## Escalating a tier mid-task
+
+Escalate, record the reason, and re-open approval when any of these appear:
+
+- A verified fact contradicts an assumption the plan rested on.
+- The change turns out to need a file the plan did not name.
+- A check fails for a reason no one predicted.
+- The worker asks for authority the packet did not grant.
+
+Never lower a tier because the work is taking longer than expected. Lower it
+only when evidence removes the risk that set it, and say which evidence did.
+`;
+export const evidenceLadderReference = `# Evidence Ladder — Worked Examples
+
+The rungs and the browser policy are defined in
+\`.ai/protocols/core/verification.md\`. This file shows which evidence actually
+proves which claim, and which evidence only looks like proof.
+
+## Claim to evidence
+
+| Claim | Sufficient evidence | Not sufficient |
+| --- | --- | --- |
+| "The label now reads X." | The diff hunk showing the literal, plus a search proving no other copy exists. | "I changed it." |
+| "The function handles null." | A unit test asserting the null path, failing before the change. | Reading the new branch. |
+| "No caller breaks." | A type check, or an exhaustive search of call sites with each one listed. | "It is backwards compatible." |
+| "The bug is fixed." | The original reproduction command, before and after, with output. | The test suite passing. |
+| "Performance improved." | The same measurement command before and after, with both numbers. | A reasoned argument about complexity. |
+| "The migration is safe." | A dry run against a copy of real-shaped data, plus the rollback path. | A review of the SQL. |
+| "Nothing else changed." | The full diff, read hunk by hunk. | The summary of the diff. |
+| "The endpoint returns 403 for anonymous users." | A request-level test asserting the status. | The presence of a guard annotation. |
+
+## Choosing the cheapest sufficient rung
+
+Ask: *what observation would change my mind?* Run that, and stop.
+
+- A claim about a literal is settled by a search. Running the test suite adds
+  minutes and zero information.
+- A claim about a type boundary is settled by the type checker. A runtime test
+  adds nothing the compiler did not already prove.
+- A claim about behavior at an integration seam is not settled by a unit test
+  with the seam mocked. The mock encodes the assumption under test.
+- A claim about a rendered pixel, a focus order or a real browser event is the
+  only case where a headed browser is the cheapest sufficient evidence — and it
+  still requires the approval the protocol demands.
+
+## Recording evidence
+
+Record, for every check: the exact command, the working directory, the outcome,
+and the reason for any check deliberately not run. Three failure modes to avoid:
+
+1. **Paraphrasing a command.** \`pnpm test\` and \`pnpm test src/foo\` are
+   different evidence. Record what ran, not what it resembled.
+2. **Reporting a check that did not run.** If it was skipped, name it as
+   skipped. An honest gap is cheaper than a false claim discovered later.
+3. **Reporting a pass that was not read.** A green exit code from a command
+   that matched zero tests proves nothing. Confirm the check had subjects.
+
+## Worked example — a trivial change
+
+Objective: correct a misspelled key in one constant.
+
+1. Diff: one line, one file. **Rung 1.**
+2. Search for the old spelling across the repository: no other occurrence.
+3. Stop. No lint, no build, no test suite, no reviewer, no browser.
+4. Record: "grep -r oldKey → 0 hits; suite not run (unaffected)."
+
+## Worked example — a standard change
+
+Objective: an API response gains an optional field.
+
+1. Diff read hunk by hunk. **Rung 1.**
+2. Type check and the serializer's own unit tests. **Rung 2.**
+3. One request-level test asserting the field is present and optional.
+4. Integration suite only if a consumer in this repository parses strictly.
+5. Independent review because the change crosses a published boundary.
+6. Record every command, plus "end-to-end suite not run: no UI path changed."
+`;
+export const hypothesisPatternsReference = `# Hypothesis Patterns and Failure Catalogue
+
+Open this file when the reproduction is in hand and the hypothesis list is
+short, obvious and wrong. It exists to widen the candidate set before effort is
+spent confirming a favourite.
+
+## Writing a falsifiable hypothesis
+
+A usable hypothesis names a mechanism and predicts an observation.
+
+- Weak: "something is wrong with the cache."
+- Usable: "the cache key omits the tenant id, so tenant B reads tenant A's
+  entry. If true, two requests differing only by tenant return the same body."
+
+Every hypothesis must come with the cheapest observation that would **disprove**
+it. Rank by \`likelihood / cost of disproof\`, and test the cheapest first.
+
+## The failure catalogue
+
+### It works locally but not in the other environment
+
+- Configuration or secret differs, and the code falls back silently.
+- Version skew: a dependency resolved differently by an unpinned range.
+- Case-sensitive file system on one side, case-insensitive on the other.
+- Timezone or locale of the host changes parsing or formatting.
+- A build step runs in one environment and not the other.
+
+### It worked yesterday
+
+- A dependency floated to a new version; check the lockfile diff first.
+- A clock, an expiry or a certificate crossed a boundary.
+- Data grew past a limit: a page size, a timeout, an index that stopped being used.
+- A feature flag or remote configuration changed outside the repository.
+
+### It fails only sometimes
+
+- Order dependence between tests sharing mutable state.
+- A race between an async write and the read that follows it.
+- Time-of-day, date-boundary or leap-related arithmetic.
+- Retry logic masking a failure until the retry budget is exhausted.
+- Hash or set iteration order treated as stable.
+
+### The error message points at innocent code
+
+- The reported frame is where the bad value was *used*, not where it was made.
+  Walk the value backwards to its origin.
+- A wrapper re-threw and lost the cause; find the original throw site.
+- A null or default was substituted upstream by a permissive parser.
+- The stack belongs to a different async context than the failure.
+
+### The fix does not stick
+
+- Two code paths do the same thing and only one was changed.
+- A cached, generated or committed artifact still holds the old value.
+- The test asserts the mock, not the code.
+- The change is correct but never runs: the branch condition is false.
+
+## Reduction techniques
+
+- **Bisect the input.** Halve the failing input until the minimal trigger remains.
+- **Bisect history.** Find the last good commit; the diff bounds the cause.
+- **Bisect the stack.** Assert the value at the midpoint between the origin and
+  the symptom; each assertion halves the remaining search space.
+- **Invert.** Instead of asking why it fails, construct the closest case that
+  succeeds and diff the two.
+
+## Before calling it a root cause
+
+1. You can state the mechanism in one sentence, cause to symptom.
+2. You can explain why it did not fail earlier, or elsewhere.
+3. A regression test fails before the fix and passes after it.
+4. The fix touches the cause, not the place the symptom was observed.
+
+If any of the four is missing, you have a correlation. Say so, and escalate
+rather than shipping a fix whose mechanism you cannot state.
+`;
+export const severityRubricReference = `# Review Severity Rubric and Checklist
+
+Open this file when classifying a finding, or when a review needs a systematic
+pass rather than an impression. The verdict vocabulary is fixed so that
+"blocking" means the same thing to every reviewer.
+
+## Severity rubric
+
+| Severity | Definition | Reviewer action |
+| --- | --- | --- |
+| \`blocking\` | The change is incorrect, unsafe, or fails an approved acceptance criterion. Shipping it causes harm or rework. | Reject. Name the location, the mechanism and the consequence. |
+| \`required\` | Correct for the approved case, but leaves a defect that will surface under a stated, realistic condition. | Approve only with a named follow-up owner and task. |
+| \`advisory\` | A real improvement that is out of scope for the approved change. | Report; never block on it. |
+| \`note\` | Context a future reader will want. No action implied. | Report at most a handful. |
+
+A finding with no consequence is not a finding. If you cannot complete the
+sentence "if this ships unchanged, then …", it is at most a note.
+
+## Blocking, by category
+
+- **Correctness.** The code does not do what the criterion says, on the inputs
+  the criterion names.
+- **Regression.** An existing behavior covered by a test or a caller changes
+  without being part of the approved scope.
+- **Security.** Missing authorization, injected input reaching an interpreter,
+  a secret in the diff, a permission widened without justification.
+- **Data.** Irreversible migration without a rollback, a write that can partially
+  apply, a unique constraint the code does not honour.
+- **Concurrency.** A read-modify-write without a guard, an await inside a lock, a
+  shared mutable default.
+- **Evidence.** The packet reports a check that did not run, or the named
+  evidence does not prove the claim it is attached to.
+
+## The checklist
+
+Run in order. Stop at the first section that produces a blocking finding, report
+it, and finish the remaining sections at low cost rather than in depth.
+
+1. **Scope.** Does every changed file appear in the approved ownership? Is any
+   hunk unrelated to the objective?
+2. **Criteria.** For each acceptance criterion, name the hunk that satisfies it.
+   A criterion with no hunk is blocking.
+3. **Edges.** For each new branch: what happens on empty, null, zero, one,
+   duplicate, very large, and concurrent?
+4. **Errors.** Is every failure path either handled or deliberately propagated?
+   Is any error swallowed into a default?
+5. **Boundaries.** Did a public type, route, schema, event or column change? Is
+   the change additive?
+6. **Tests.** Does a new test fail without the change? Does it assert behavior
+   rather than the shape of the implementation?
+7. **Evidence.** Re-run the cheapest reported command. Does it pass, and does it
+   cover the change?
+8. **Leftovers.** Debug output, commented code, skipped tests, temporary files,
+   unrelated formatting.
+
+## What not to raise
+
+- Preferences the project does not enforce in lint, formatter or existing code.
+- Rewrites of code the diff only moved.
+- Hypothetical scale the project has never stated a requirement for.
+- Duplicate findings: report the pattern once and list the locations.
+
+## Wording a finding
+
+\`path:line\` — severity — what is wrong — what happens if it ships — the
+smallest change that resolves it. Four sentences at most. If a finding needs
+more, the change needs a conversation, not a comment.
+`;
+//# sourceMappingURL=skill-references.js.map

package/dist/templates/skill-references.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-references.js","sourceRoot":"","sources":["../../src/templates/skill-references.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6D1C,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgEtC,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2E1C,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmEtC,CAAC"}

package/dist/templates/structure-templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"structure-templates.d.ts","sourceRoot":"","sources":["../../src/templates/structure-templates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAK1D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,cAAc,EAAE,CA0DrF"}
+{"version":3,"file":"structure-templates.d.ts","sourceRoot":"","sources":["../../src/templates/structure-templates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAO1D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,cAAc,EAAE,CA2DrF"}