@hecer/yoke 1.5.1 → 1.6.1

package/canon/skills/verification-before-completion/SKILL.md

@@ -1,139 +1,139 @@
----
-name: verification-before-completion
-description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
----
-
-# Verification Before Completion
-
-## Overview
-
-Claiming work is complete without verification is dishonesty, not efficiency.
-
-**Core principle:** Evidence before claims, always.
-
-**Violating the letter of this rule is violating the spirit of this rule.**
-
-## The Iron Law
-
-```
-NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
-```
-
-If you haven't run the verification command in this message, you cannot claim it passes.
-
-## The Gate Function
-
-```
-BEFORE claiming any status or expressing satisfaction:
-
-1. IDENTIFY: What command proves this claim?
-2. RUN: Execute the FULL command (fresh, complete)
-3. READ: Full output, check exit code, count failures
-4. VERIFY: Does output confirm the claim?
-   - If NO: State actual status with evidence
-   - If YES: State claim WITH evidence
-5. ONLY THEN: Make the claim
-
-Skip any step = lying, not verifying
-```
-
-## Common Failures
-
-| Claim | Requires | Not Sufficient |
-|-------|----------|----------------|
-| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
-| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
-| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
-| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
-| Regression test works | Red-green cycle verified | Test passes once |
-| Agent completed | VCS diff shows changes | Agent reports "success" |
-| Requirements met | Line-by-line checklist | Tests passing |
-
-## Red Flags - STOP
-
-- Using "should", "probably", "seems to"
-- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
-- About to commit/push/PR without verification
-- Trusting agent success reports
-- Relying on partial verification
-- Thinking "just this once"
-- Tired and wanting work over
-- **ANY wording implying success without having run verification**
-
-## Rationalization Prevention
-
-| Excuse | Reality |
-|--------|---------|
-| "Should work now" | RUN the verification |
-| "I'm confident" | Confidence ≠ evidence |
-| "Just this once" | No exceptions |
-| "Linter passed" | Linter ≠ compiler |
-| "Agent said success" | Verify independently |
-| "I'm tired" | Exhaustion ≠ excuse |
-| "Partial check is enough" | Partial proves nothing |
-| "Different words so rule doesn't apply" | Spirit over letter |
-
-## Key Patterns
-
-**Tests:**
-```
-✅ [Run test command] [See: 34/34 pass] "All tests pass"
-❌ "Should pass now" / "Looks correct"
-```
-
-**Regression tests (TDD Red-Green):**
-```
-✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
-❌ "I've written a regression test" (without red-green verification)
-```
-
-**Build:**
-```
-✅ [Run build] [See: exit 0] "Build passes"
-❌ "Linter passed" (linter doesn't check compilation)
-```
-
-**Requirements:**
-```
-✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
-❌ "Tests pass, phase complete"
-```
-
-**Agent delegation:**
-```
-✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
-❌ Trust agent report
-```
-
-## Why This Matters
-
-From 24 failure memories:
-- your human partner said "I don't believe you" - trust broken
-- Undefined functions shipped - would crash
-- Missing requirements shipped - incomplete features
-- Time wasted on false completion → redirect → rework
-- Violates: "Honesty is a core value. If you lie, you'll be replaced."
-
-## When To Apply
-
-**ALWAYS before:**
-- ANY variation of success/completion claims
-- ANY expression of satisfaction
-- ANY positive statement about work state
-- Committing, PR creation, task completion
-- Moving to next task
-- Delegating to agents
-
-**Rule applies to:**
-- Exact phrases
-- Paraphrases and synonyms
-- Implications of success
-- ANY communication suggesting completion/correctness
-
-## The Bottom Line
-
-**No shortcuts for verification.**
-
-Run the command. Read the output. THEN claim the result.
-
-This is non-negotiable.
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## Why This Matters
+
+From 24 failure memories:
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.

package/canon/skills/visual-verification/SKILL.md

@@ -1,54 +1,54 @@
----
-name: visual-verification
-description: Use for any UI/web project — make the verify gate cover more than unit tests by composing a pipeline (types → unit → design-scan → flow-smoke) and running the built-in yoke flow-smoke gate (landmark + zero console errors + screenshot proof to .yoke/proof/<story>/, video kept on failure). Catches the unwired-page / runtime-crash / AI-slop bugs unit tests miss.
----
-
-# Visual verification
-
-Unit tests don't see a blank page, an unwired route, a runtime console error, or AI-slop design.
-Make the loop's gate catch them by widening `verify`, since the loop trusts verify as truth.
-
-## 1. Compose the verify pipeline
-
-Set `verify.command` (in `.yoke/config.yaml`) to chain, fail-fast:
-
-```
-<typecheck> && <unit tests> && yoke design-scan . && yoke flow-smoke .
-```
-e.g. `tsc --noEmit && vitest run && yoke design-scan . && yoke flow-smoke .`. Any red step blocks the story.
-
-## 2. Flow-smoke with the built-in gate
-
-Configure the key user flows once in `.yoke/config.yaml`:
-
-```yaml
-smoke:
-  baseUrl: http://localhost:3000
-  flows:
-    - name: home
-      path: /
-      landmark: "main h1"
-    - name: login
-      path: /login
-      landmark: "form"
-```
-
-With that in place, the `yoke flow-smoke .` step from the section-1 pipeline is live.
-`yoke flow-smoke` loads each route against the running dev server, waits for the landmark,
-fails on any console error, and **always** saves a screenshot to `.yoke/proof/<story>/`
-(the loop labels the folder with the current story id via `YOKE_STORY`; standalone runs use
-`latest`, or pass `--label=`). Requires Playwright in the project:
-`npm i -D playwright && npx playwright install chromium`. Start the dev server before verify
-(e.g. via `start-server-and-test`).
-
-## 3. Video only when necessary
-
-`yoke flow-smoke` records video per flow and keeps it **only on failure**
-(`.yoke/proof/<story>/<flow>.webm`). When a flow goes red: watch that clip first, then use the
-wired Playwright MCP to reproduce interactively. Never record every run manually — the gate
-already handles the failure case.
-
-## Rule
-
-Green pipeline = types + units + no design-slop over budget + every flow renders without
-console errors, with a screenshot to prove it. Only then is the story actually done.
+---
+name: visual-verification
+description: Use for any UI/web project — make the verify gate cover more than unit tests by composing a pipeline (types → unit → design-scan → flow-smoke) and running the built-in yoke flow-smoke gate (landmark + zero console errors + screenshot proof to .yoke/proof/<story>/, video kept on failure). Catches the unwired-page / runtime-crash / AI-slop bugs unit tests miss.
+---
+
+# Visual verification
+
+Unit tests don't see a blank page, an unwired route, a runtime console error, or AI-slop design.
+Make the loop's gate catch them by widening `verify`, since the loop trusts verify as truth.
+
+## 1. Compose the verify pipeline
+
+Set `verify.command` (in `.yoke/config.yaml`) to chain, fail-fast:
+
+```
+<typecheck> && <unit tests> && yoke design-scan . && yoke flow-smoke .
+```
+e.g. `tsc --noEmit && vitest run && yoke design-scan . && yoke flow-smoke .`. Any red step blocks the story.
+
+## 2. Flow-smoke with the built-in gate
+
+Configure the key user flows once in `.yoke/config.yaml`:
+
+```yaml
+smoke:
+  baseUrl: http://localhost:3000
+  flows:
+    - name: home
+      path: /
+      landmark: "main h1"
+    - name: login
+      path: /login
+      landmark: "form"
+```
+
+With that in place, the `yoke flow-smoke .` step from the section-1 pipeline is live.
+`yoke flow-smoke` loads each route against the running dev server, waits for the landmark,
+fails on any console error, and **always** saves a screenshot to `.yoke/proof/<story>/`
+(the loop labels the folder with the current story id via `YOKE_STORY`; standalone runs use
+`latest`, or pass `--label=`). Requires Playwright in the project:
+`npm i -D playwright && npx playwright install chromium`. Start the dev server before verify
+(e.g. via `start-server-and-test`).
+
+## 3. Video only when necessary
+
+`yoke flow-smoke` records video per flow and keeps it **only on failure**
+(`.yoke/proof/<story>/<flow>.webm`). When a flow goes red: watch that clip first, then use the
+wired Playwright MCP to reproduce interactively. Never record every run manually — the gate
+already handles the failure case.
+
+## Rule
+
+Green pipeline = types + units + no design-slop over budget + every flow renders without
+console errors, with a screenshot to prove it. Only then is the story actually done.

package/canon/skills/workflow/SKILL.md

@@ -1,22 +1,22 @@
----
-name: workflow
-description: Use at the start of any non-trivial task — the default order of operations for shipping quality work, from idea to deploy.
----
-
-# Workflow — the default order of operations
-
-For any non-trivial change, move through these phases in order (skip only what genuinely does not apply):
-
-When `.yoke/config.yaml` exists and the user wants Yoke to own planning plus autonomous
-execution, use `yoke-workflow` as the entrypoint. It adds the approved-plan → PRD → loop
-handoff and the configured critical-decision behavior to the phases below.
-
-1. **Brainstorm** the idea into a clear design — see `brainstorming`.
-2. **Plan** a concrete, testable implementation — see `writing-plans`.
-3. **Understand the code** — map the blast radius with the code-graph before changing anything.
-4. **Implement test-first** — RED → GREEN → REFACTOR, smallest steps — see `tdd` and `minimal-code`.
-5. **Verify** — run the real tests and exercise the change; never trust "it should work" — see `verification-before-completion`.
-6. **Review** — get an independent review of the diff before landing — see `review` / `requesting-code-review`.
-7. **Ship** — bump version, update changelog and docs, open the PR — see `ship` / `document-release`.
-
-Stop-the-Line applies throughout: no implementation before acceptance criteria exist. Always prefer the least code that solves the task (`minimal-code`).
+---
+name: workflow
+description: Use at the start of any non-trivial task — the default order of operations for shipping quality work, from idea to deploy.
+---
+
+# Workflow — the default order of operations
+
+For any non-trivial change, move through these phases in order (skip only what genuinely does not apply):
+
+When `.yoke/config.yaml` exists and the user wants Yoke to own planning plus autonomous
+execution, use `yoke-workflow` as the entrypoint. It adds the approved-plan → PRD → loop
+handoff and the configured critical-decision behavior to the phases below.
+
+1. **Brainstorm** the idea into a clear design — see `brainstorming`.
+2. **Plan** a concrete, testable implementation — see `writing-plans`.
+3. **Understand the code** — map the blast radius with the code-graph before changing anything.
+4. **Implement test-first** — RED → GREEN → REFACTOR, smallest steps — see `tdd` and `minimal-code`.
+5. **Verify** — run the real tests and exercise the change; never trust "it should work" — see `verification-before-completion`.
+6. **Review** — get an independent review of the diff before landing — see `review` / `requesting-code-review`.
+7. **Ship** — bump version, update changelog and docs, open the PR — see `ship` / `document-release`.
+
+Stop-the-Line applies throughout: no implementation before acceptance criteria exist. Always prefer the least code that solves the task (`minimal-code`).

package/canon/skills/writing-for-agents/SKILL-MECHANICS.md

@@ -0,0 +1,27 @@
+# Skill mechanics
+
+## Entrypoint
+
+`SKILL.md` needs `name` and a discriminating `description`. The description is the always-loaded
+context pointer: state the capability, real trigger branches, and a boundary only when it prevents
+likely misrouting.
+
+Keep common actions and constraints in `SKILL.md`. Put substantial conditional procedures,
+formats, or examples in linked resources, and state when the agent should load each one.
+
+## Invocation
+
+Yoke records invocation in `canon/manifest.yaml`:
+
+- `auto` allows provider-supported automatic selection and explicit user invocation.
+- `manual` excludes automatic advertising and requires explicit invocation.
+
+Choose `auto` when an agent or another workflow must discover the capability. Choose `manual` when
+only a user should select it and the cognitive cost is intentional. Provider metadata is generated
+by Retrofit; do not add provider-specific policy to a normal Canon package.
+
+## Validation
+
+The package must remain self-contained. Every relative Markdown link resolves inside the package,
+symlinks and path escapes are rejected, and resources install for every supported provider. Test
+observable routing or output behavior rather than only matching headings.

package/canon/skills/writing-for-agents/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: writing-for-agents
+description: Create or edit agent-facing instructions such as AGENTS.md, CLAUDE.md, skills, roles, and workflow documents. Use when triggers, completion criteria, context pointers, instruction hierarchy, or duplication affect whether an agent can execute the document reliably.
+---
+
+# Writing for agents
+
+Write instructions that produce a repeatable process with observable completion, while preserving
+authorization, safety rules, acceptance criteria, and precise domain language.
+
+## Context pointers
+
+A pointer names out-of-context material and states when to load it. A skill description and an
+`AGENTS.md` link serve the same routing function.
+
+- Front-load the capability or trigger.
+- Name each genuinely different branch once; remove synonymous trigger lists.
+- Keep must-have instructions behind a pointer only when its trigger is strong enough to load them.
+- Spend always-loaded context on rules needed broadly; disclose branch-specific reference material.
+
+## Information hierarchy
+
+1. Put ordered actions and their completion criteria in the main file.
+2. Co-locate definitions, rules, and caveats that an action needs.
+3. Move substantial branch-specific reference behind a named link and say when to read it.
+4. Keep each durable meaning in one source of truth. Treat scripts, config, and directory structure
+   as discoverable sources instead of copying facts that will go stale.
+
+Every step needs a checkable completion criterion. Prefer an exhaustive observable bound such as
+"every changed public interface has a passing contract test" over "review the interfaces."
+
+## Editing pass
+
+- Remove duplicated, contradictory, stale, or no-op instructions.
+- Replace vague verbs with concrete actions, paths, commands, evidence, and stopping conditions.
+- Separate durable project rules from details that belong only to the current task.
+- Phrase the desired behavior positively. Keep prohibitions for real guardrails and pair them with
+  the action the agent should take.
+- Keep examples only when they distinguish correct behavior from a likely mistake.
+- Preserve user scope: completing a workflow never grants unrelated external or destructive action.
+
+When the document is a skill, read [SKILL-MECHANICS.md](SKILL-MECHANICS.md).