@olegkoval/agent-skills 1.40.1 → 1.41.1

package/.github/prompts/open-source-publisher.prompt.md

@@ -31,12 +31,11 @@ Use this skill to audit whether an OSS repository is ready to publish, then help
 5. For existing usable pieces, do not propose replacement by default. Ask a change-oriented question only when useful, for example:
    - "You already have a terminal-style GitHub Pages site. Do you want to keep it or restyle it?"
    - "You already have an icon and social card. Do you want a refresh, or should I leave them as-is?"
-   - "You already have a static social card. Do you want me to animate it with pixel2motion, or leave it static?"
    - "You already have release automation. Do you want me to audit only, or also tighten it?"
 6. Ask only for choices needed to fix missing or weak pieces:
    - If GitHub Pages is missing or weak, ask for style: `oldschool linux`, `terminal`, `modern`, `brutalist`, `glassmorphism`, `y2k`, `hacker`, or custom.
    - If donation wiring is missing, ask whether to enable it: `none`, `GitHub Sponsors`, `Ko-fi`, `Buy Me a Coffee`, `Open Collective`, `Thanks.dev`, or custom URL.
-   - If the repo has a generated static social image or hero card, ask whether to animate it using `nolangz/pixel2motion`.
+   - If the repo has a generated logo or simple hero artwork supported by `nolangz/pixel2motion`, ask whether to animate it or leave it static.
    - If the repo has no clear product essence, ask for a one-sentence positioning statement.
 7. Implement only approved, missing, or weak work in this order:
    - OSS governance and support files
@@ -200,8 +199,8 @@ Use `magick` or another renderer when `rsvg-convert` is unavailable.
 
 Some repos benefit from a short animated preview. Keep this opt-in.
 
-- If you already generated a static image, ask: `Do you want me to animate the static image using pixel2motion?`
-- If the user says yes, use `nolangz/pixel2motion` as the optional dependency for logo animation, animated HTML demos, and GIF/video previews.
+- After the user opts in during workflow step 6, animate only the approved generated logo or simple artwork.
+- Use `nolangz/pixel2motion` as the optional dependency for that animation, animated HTML demos, and GIF/video previews.
 - Do not auto-animate by default.
 
 ## README Standard

package/.kiro/steering/open-source-publisher.md

@@ -30,12 +30,11 @@ Use this skill to audit whether an OSS repository is ready to publish, then help
 5. For existing usable pieces, do not propose replacement by default. Ask a change-oriented question only when useful, for example:
    - "You already have a terminal-style GitHub Pages site. Do you want to keep it or restyle it?"
    - "You already have an icon and social card. Do you want a refresh, or should I leave them as-is?"
-   - "You already have a static social card. Do you want me to animate it with pixel2motion, or leave it static?"
    - "You already have release automation. Do you want me to audit only, or also tighten it?"
 6. Ask only for choices needed to fix missing or weak pieces:
    - If GitHub Pages is missing or weak, ask for style: `oldschool linux`, `terminal`, `modern`, `brutalist`, `glassmorphism`, `y2k`, `hacker`, or custom.
    - If donation wiring is missing, ask whether to enable it: `none`, `GitHub Sponsors`, `Ko-fi`, `Buy Me a Coffee`, `Open Collective`, `Thanks.dev`, or custom URL.
-   - If the repo has a generated static social image or hero card, ask whether to animate it using `nolangz/pixel2motion`.
+   - If the repo has a generated logo or simple hero artwork supported by `nolangz/pixel2motion`, ask whether to animate it or leave it static.
    - If the repo has no clear product essence, ask for a one-sentence positioning statement.
 7. Implement only approved, missing, or weak work in this order:
    - OSS governance and support files
@@ -199,8 +198,8 @@ Use `magick` or another renderer when `rsvg-convert` is unavailable.
 
 Some repos benefit from a short animated preview. Keep this opt-in.
 
-- If you already generated a static image, ask: `Do you want me to animate the static image using pixel2motion?`
-- If the user says yes, use `nolangz/pixel2motion` as the optional dependency for logo animation, animated HTML demos, and GIF/video previews.
+- After the user opts in during workflow step 6, animate only the approved generated logo or simple artwork.
+- Use `nolangz/pixel2motion` as the optional dependency for that animation, animated HTML demos, and GIF/video previews.
 - Do not auto-animate by default.
 
 ## README Standard

package/.windsurf/rules/open-source-publisher.md

@@ -29,12 +29,11 @@ Use this skill to audit whether an OSS repository is ready to publish, then help
 5. For existing usable pieces, do not propose replacement by default. Ask a change-oriented question only when useful, for example:
    - "You already have a terminal-style GitHub Pages site. Do you want to keep it or restyle it?"
    - "You already have an icon and social card. Do you want a refresh, or should I leave them as-is?"
-   - "You already have a static social card. Do you want me to animate it with pixel2motion, or leave it static?"
    - "You already have release automation. Do you want me to audit only, or also tighten it?"
 6. Ask only for choices needed to fix missing or weak pieces:
    - If GitHub Pages is missing or weak, ask for style: `oldschool linux`, `terminal`, `modern`, `brutalist`, `glassmorphism`, `y2k`, `hacker`, or custom.
    - If donation wiring is missing, ask whether to enable it: `none`, `GitHub Sponsors`, `Ko-fi`, `Buy Me a Coffee`, `Open Collective`, `Thanks.dev`, or custom URL.
-   - If the repo has a generated static social image or hero card, ask whether to animate it using `nolangz/pixel2motion`.
+   - If the repo has a generated logo or simple hero artwork supported by `nolangz/pixel2motion`, ask whether to animate it or leave it static.
    - If the repo has no clear product essence, ask for a one-sentence positioning statement.
 7. Implement only approved, missing, or weak work in this order:
    - OSS governance and support files
@@ -198,8 +197,8 @@ Use `magick` or another renderer when `rsvg-convert` is unavailable.
 
 Some repos benefit from a short animated preview. Keep this opt-in.
 
-- If you already generated a static image, ask: `Do you want me to animate the static image using pixel2motion?`
-- If the user says yes, use `nolangz/pixel2motion` as the optional dependency for logo animation, animated HTML demos, and GIF/video previews.
+- After the user opts in during workflow step 6, animate only the approved generated logo or simple artwork.
+- Use `nolangz/pixel2motion` as the optional dependency for that animation, animated HTML demos, and GIF/video previews.
 - Do not auto-animate by default.
 
 ## README Standard

package/README.md

@@ -342,7 +342,7 @@ When adding or changing a skill:
 
 ### Shared context store
 
-![How the agent context store works: the five resolution steps, the three skills that use the store, and the four states every run ends in](docs/assets/context-store-card.png)
+![How the agent context store works: the five resolution steps, the three skills that use the store, the four states every run ends in, and how the store is read](docs/assets/context-store-card.png)
 
 `retro-analysis` and `shared-knowledge-artifact` share one private GitHub repository,
 resolved through the `context-repo` skill the first time either one runs. It finds a

package/adapters/claude/olko-github-pr/skills/lekker-review/SKILL.md

@@ -5,7 +5,7 @@ description: >
   isolated worktree, gathers context from your issue tracker, chat, docs, CI
   checks, and (optionally) production monitoring, runs 5 parallel specialized
   review agents (quality/implementation/simplification/conventions/test-quality),
-  verifies every finding against the diff, then outputs a single unified markdown
+  verifies every verdict-affecting finding against the diff, then outputs a single unified markdown
   review: file + risk + bad code + why it's wrong + fix, ready to paste directly
   into GitHub. Saves every review to ~/code-reviews/*.md. Covers business logic,
   scalability, complexity, data integrity, security, integration contracts, error
@@ -79,14 +79,11 @@ the 5 specialist agents still run and still find real bugs. They just don't
 have a codified "always Critical" rule list to check against.
 
 If any hard rule you define carries a `rule` tag (e.g. `"TS-1"`), reviewer
-agents attach that tag to matching findings and the workflow **skips
-adversarial verification** for them. This is deliberate: the verifier's five
-challenges ask runtime-failure questions ("does this fail on a normal
-execution?", "can you write the failing test?") that a standards violation
-can never answer, so verifying them systematically drops the very findings
-your policy declares non-negotiable. A tagged finding keeps its Critical
-severity; the workflow returns how many were exempted as `hardRuleCount`, and
-each carries a `verifierReasoning` saying so.
+agents attach that tag to matching findings. The verifier checks the diff
+anchor and rule applicability, but skips its five runtime-failure challenges.
+Those challenges cannot evaluate a standards violation. A tagged finding keeps
+Critical severity only when both rule-specific checks pass. The workflow
+returns the number checked as `hardRuleCount`.
 
 `${CLAUDE_PLUGIN_ROOT}` below refers to this skill's own installed directory:
 resolve every `references/...` and script path relative to it.
@@ -150,7 +147,7 @@ treat as a full review and leave PREV_SHA unset. Also grep the same file for
 | Context: chat/docs/framework-docs/monitoring/prior-review-memory (optional, MCP-dependent) | skip | included | included + broader recall |
 | Worktree + static checks    | skip (WORKTREE_PATH=null) unless `--fix` | included | included          |
 | Review agents               | 2 triage (haiku)      | 5 specialists (sonnet) | 5 specialists (sonnet)  |
-| Per-finding verification    | none                  | Criticals only (hard rules exempt) | Criticals + Importants (hard rules exempt) |
+| Per-finding verification    | Criticals + Importants | Criticals + Importants | Criticals + Importants |
 | Completeness critic         | skip                  | skip                | included                   |
 | Proof-of-bug (failing test per Critical) | skip     | included (max 5)    | included (max 5)           |
 | Living review artifact      | included              | included            | included                   |
@@ -298,8 +295,9 @@ The workflow runs three phases:
   description/badCode/fix of the set - a Critical is never demoted by an
   Observation someone else filed at the same line - and records every
   contributing dimension in `agreedBy`.
-- **Verify:** scan verifies nothing; medium verifies Criticals; deep verifies
-  Criticals + Importants. Hard-rule findings (`rule` set) are always exempt.
+- **Verify:** every Critical and Important is checked at every depth because it
+  can affect the verdict. Hard-rule findings (`rule` set) use the verifier's
+  diff-anchor and rule-applicability checks instead of runtime challenges.
   Each verifier runs the five-challenge adversarial refutation from
   `references/agents/verifier.md` against one finding, returns
   `{verdict, newSeverity?, reasoning}`. Verifiers run `maxConcurrent` at a time
@@ -311,13 +309,13 @@ The workflow runs three phases:
   one prover agent (`references/agents/prover.md`, sonnet, max 5, run
   `maxConcurrent` at a time) that writes a test asserting the CORRECT behaviour,
   runs it in the worktree, and captures it failing because of the bug. The proof rides on the finding as
-  `proof: {attempted, proven, reason, testCode?, testCommand?, redOutput?}`.
+  `proof: {attempted, proven, outcome, reason, testCode?, testCommand?, redOutput?}`.
   A proof that comes back GREEN (code behaved correctly) is counter-evidence -
-  Step 3 must downgrade or explicitly justify the finding, never ignore it.
+  the workflow automatically downgrades the finding from Critical to Important.
   Hard-rule findings are never proved (policy violations have no failing test).
 
 Findings have schema:
-`{file, line, severity, title, description, badCode, fix, rule?, precedent?, agreedBy?, verifierReasoning?, proof?}`
+`{file, line, severity, title, description, badCode, fix, rule?, precedent?, agreedBy?, verificationStatus?, verifierReasoning?, proof?}`
 `badCode` and `fix` are schema-required: an empty string is allowed only on
 `observation` / `idiomatic` findings.
 
@@ -326,7 +324,7 @@ provers on `sonnet`, housekeeping on `haiku`. Only the synthesis in Step 3 runs
 on the session model.
 
 Return value from the workflow:
-`{findings, droppedCount, downgradedCount, hardRuleCount, proveAttemptCount, provenCount, agentCount, outputTokens, turnTokensTotal}`
+`{findings, droppedCount, downgradedCount, hardRuleCount, proveAttemptCount, provenCount, acCoverage, coverageVerdict, mutationSlip, mockSmells, agentCount, outputTokens, turnTokensTotal}`
 `outputTokens` is this workflow's own output spend; `turnTokensTotal` is the
 whole turn's shared pool (main loop included).
 
@@ -411,7 +409,7 @@ requirements:
 - When `PREV_SHA` is set: include `## 🔁 Since last review` comparing
   `PREV_REVIEW_FILE` findings against the new head - list each as fixed or
   still open, before any new findings.
-- Test Quality section: populate from the test-quality agent's fields
+- Test Quality section: populate from the workflow return fields
   (`coverageVerdict`, `mutationSlip`, `mockSmells`).
 - Idiomatic section: populated from severity=idiomatic findings only.
 - **💰 Review Cost block:** `outputTokens` from the workflow return is the

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/implementation.md

@@ -8,6 +8,7 @@ Axes to cover:
 - Business Logic / AC coverage: for each AC in the list below, mark
   ✅ met / ⚠️ partial / ❌ missing. Scope creep is also worth flagging.
   AC_LIST: read key "acList" from CONTEXT_FILE.
+  Return the complete status summary in the structured `acCoverage` field.
 - Scalability: N+1 queries, missing pagination, unbounded in-memory
   collections, missing rate-limit handling, cron jobs without overlap guard,
   missing DB indexes for new query patterns.
@@ -23,7 +24,7 @@ Axes to cover:
   Set `rule: "GQL-1"` on any Critical finding raised under this axis.
 
 Setting rule tags the finding as a house hard rule: it keeps its Critical
-severity and skips adversarial verification. Only set it for a genuine GQL-1
+severity only after rule-specific validation and skips runtime challenges. Only set it for a genuine GQL-1
 violation: never to shield an ordinary finding from verification.
 
 CI_STATUS: read key "ciStatus" from the JSON file CONTEXT_FILE.

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/prover.md

@@ -1,6 +1,6 @@
 # prover -- lekker-review agent prompt
 # Receives: one FINDING as JSON, WORKTREE_PATH path, DIFF_FILE path, CONTEXT_FILE path
-# Returns: PROOF_SCHEMA { attempted: boolean, proven: boolean, reason: string, testCode?: string, testCommand?: string, redOutput?: string }
+# Returns: PROOF_SCHEMA { attempted: boolean, proven: boolean, outcome: 'proven'|'passed'|'inconclusive'|'not_attempted', reason: string, testCode?: string, testCommand?: string, redOutput?: string }
 
 ## Mission
 
@@ -29,8 +29,9 @@ explicitly.
 ## Step 1 -- Testability gate
 
 Read the FINDING, the real code at `file:line` in `WORKTREE_PATH`, and the diff
-context in `DIFF_FILE`. Return `attempted: false` with an honest one-sentence
-`reason` when any of these hold:
+context in `DIFF_FILE`. Return `attempted: false, proven: false,
+outcome: "not_attempted"` with an honest one-sentence `reason` when any of these
+hold:
 
 - The failure path requires live IO (Shopify/BC/Salesforce API, a real DB, the
   network) and the repo has no test infra to fake it cheaply.
@@ -77,25 +78,26 @@ Exactly one run command, scoped to your file only:
 Set the Bash tool's `timeout` parameter to 120000 for this call.
 
 If the runner hangs or the environment fails (missing config, transform
-errors), that is `attempted: true, proven: false` with the reason. Report
-honestly -- never retry more than once for a pure environment issue (e.g. a
-wrong config flag), and never loop.
+errors), that is `attempted: true, proven: false, outcome: "inconclusive"`
+with the reason. Report honestly -- never retry more than once for a pure
+environment issue (e.g. a wrong config flag), and never loop.
 
 ---
 
 ## Step 4 -- Judge the outcome
 
 - **Test FAILS, and the mismatch matches what the finding predicts** ->
-  `proven: true`. `redOutput` = the failure excerpt, trimmed to the
+  `proven: true, outcome: "proven"`. `redOutput` = the failure excerpt, trimmed to the
   informative ~15 lines (expected vs received + the failing assertion line).
   `testCode` = the full test file content. `testCommand` = the exact command
   you ran.
-- **Test PASSES** -> the finding did not reproduce. `proven: false`, and
+- **Test PASSES** -> the finding did not reproduce. `proven: false,
+  outcome: "passed"`, and
   `reason` states plainly that the code behaved correctly for the tested
   input. This is important review signal, not a failure of yours. Do NOT alter
   the test to force a failure.
 - **Test fails for an unrelated reason** (import error, env issue) ->
-  `proven: false`, honest `reason`.
+  `proven: false, outcome: "inconclusive"`, honest `reason`.
 
 ---
 
@@ -124,6 +126,7 @@ Return EXACTLY one JSON object matching PROOF_SCHEMA:
 {
   "attempted": true | false,
   "proven": true | false,
+  "outcome": "proven" | "passed" | "inconclusive" | "not_attempted",
   "reason": "<one or two sentences: why not attempted, why it proved, or why it didn't reproduce>",
   "testCode": "<full test file content -- only when attempted>",
   "testCommand": "<exact command run -- only when attempted>",
@@ -131,5 +134,5 @@ Return EXACTLY one JSON object matching PROOF_SCHEMA:
 }
 ```
 
-`attempted: false` implies `proven: false` and omits `testCode`/`testCommand`/
+`attempted: false` implies `proven: false, outcome: "not_attempted"` and omits `testCode`/`testCommand`/
 `redOutput`. Do not narrate outside the object.

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/quality.md

@@ -56,7 +56,7 @@ Axes to cover:
   or a `node_modules` path.
 
 Setting rule tags the finding as a house hard rule: it keeps its Critical
-severity and skips adversarial verification. Only set it for a genuine
+severity only after rule-specific validation and skips runtime challenges. Only set it for a genuine
 TS-1/TS-2 violation: never to shield an ordinary finding from verification.
 
 CI_STATUS: read key "ciStatus" from the JSON file CONTEXT_FILE.

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/test-quality.md

@@ -141,6 +141,13 @@ criticism without a fix is incomplete.
 Report the mutation-slip analysis as a single paragraph under a
 "**Mutation-slip risk:**" heading, not as line items.
 
+Return the review summary through these structured fields in addition to
+`findings`:
+- `coverageVerdict`: one concise overall coverage verdict.
+- `mutationSlip`: the mutation-slip risk paragraph.
+- `mockSmells`: every mock-smell issue as `{file, line, description, fix}`.
+  Return an empty array when there are no mock smells.
+
 EXISTING_REVIEWS: read key "existingReviews" from CONTEXT_FILE (awareness only, skip findings already raised)
 
 PROJECT_RULES to verify: read key "projectRules" from CONTEXT_FILE.

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/triage-quality.md

@@ -20,7 +20,7 @@ Axes to cover (Critical/Important only):
   set `rule: "GQL-1"` when Critical
 
 Setting rule tags the finding as a house hard rule: it keeps its Critical
-severity and skips adversarial verification. Only set it for a genuine
+severity only after rule-specific validation and skips runtime challenges. Only set it for a genuine
 TS-1/TS-2/GQL-1 violation: never to shield an ordinary finding from
 verification.
 

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/verifier.md

@@ -1,5 +1,5 @@
 # verifier -- lekker-review agent prompt
-# Receives: one FINDING as JSON, DIFF_FILE path, CONTEXT_FILE path, WORKTREE_PATH path
+# Receives: one FINDING as JSON, DIFF_FILE path, CONTEXT_FILE path, WORKTREE_PATH path, HOUSE_RULES_FILE path
 # Returns: VERDICT_SCHEMA { verdict: 'confirmed'|'downgraded'|'dropped', newSeverity?, reasoning }
 
 ## Mindset
@@ -18,17 +18,19 @@ verified yourself are not confirmed findings.
 
 You have received one candidate finding as JSON (field `FINDING` in your task
 message). Run all applicable verification checks below against the finding using
-`DIFF_FILE`, `CONTEXT_FILE`, and `WORKTREE_PATH` (read from the task message).
+`DIFF_FILE`, `CONTEXT_FILE`, `WORKTREE_PATH`, and `HOUSE_RULES_FILE` (read from
+the task message).
 
 When in doubt, drop. A Critical must pass ALL FIVE challenges to remain Critical
--- unless Step 0 exempts it as a house hard rule, which is the one exception.
+unless Step 0 validates it through the house hard-rule path.
 
 ---
 
-## Step 0 -- Hard-rule exemption (check this FIRST)
+## Step 0 -- Hard-rule validation (check this FIRST)
 
-If the FINDING JSON has a `rule` field set to `TS-1`, `TS-2`, `GQL-1`, or
-`PR-1`, do NOT run the five adversarial challenges below. They ask
+If the FINDING JSON has any non-empty `rule` field, including built-in tags
+such as `TS-1`, `TS-2`, `GQL-1`, or `PR-1`, do NOT run the five adversarial
+challenges below. They ask
 runtime-failure questions that a standards violation can never answer, and
 answering them honestly would drop a finding that house-rules policy declares
 Critical on standards grounds rather than on runtime behaviour.
@@ -41,8 +43,9 @@ Instead run exactly two checks:
    ```bash
    grep "^+" "$DIFF_FILE" | grep "<snippet>"
    ```
-2. **Rule applicability**: the code really does violate the rule as written
-   in `references/house-rules.md` -- e.g. an `as const` is not a type cast in
+2. **Rule applicability**: read the exact `HOUSE_RULES_FILE` path from the task
+   message, then confirm the code really violates the rule as written there --
+   e.g. an `as const` is not a type cast in
    the TS-1 sense; a `nodes` query that legitimately fetches a single known
    node with a documented comment may satisfy GQL-1; a `.js` file inside a
    Liquid theme repo is exempt from TS-2.
@@ -253,7 +256,7 @@ the inference is the crux of the claim
 ## Outcome rules
 
 The one exception to "a Critical must pass ALL FIVE challenges" is the
-hard-rule path in Step 0: a `rule`-tagged finding is judged solely on the
+hard-rule path in Step 0: a `rule`-tagged finding is validated solely on the
 anchor + rule-applicability checks and never runs the five challenges.
 
 A Critical finding must pass ALL FIVE challenges. Any failure downgrades:

package/adapters/claude/olko-github-pr/skills/lekker-review/references/artifact-page.md

@@ -18,7 +18,7 @@ All of the following are already in hand after Step 3 of SKILL.md:
 - `findings.json` path (scratchpad) -- each finding carries: `file`, `line`,
   `severity`, `title`, `description`, `badCode`, `fix`, `rule?`, `precedent?`,
   `agreedBy?`, `verifierReasoning?`, `proof?` (proof = `{attempted, proven,
-  reason, testCode?, testCommand?, redOutput?}`).
+  outcome, reason, testCode?, testCommand?, redOutput?}`).
 - The saved review file path: `~/code-reviews/YYYY-MM-DD-pr-N-repo.md`.
 - PR metadata: `REPO_SLUG`, `PR_NUMBER`, `PR_URL`, title, author, `headRefName`
   → `baseRefName`, head sha, depth, verdict, `isDraft`, `mergeStateStatus`, CI
@@ -96,6 +96,11 @@ Hard requirements for the HTML page:
   `<pre>`, a one-line explanation that the test asserts correct behavior, and
   `testCode` collapsed behind its own `<details>`. This is the page's
   centerpiece -- make it prominent (e.g. a red left border) but not garish.
+  When `proof.outcome === 'passed'`, render a distinct
+  "COUNTER-EVIDENCE -- focused proof test passed" panel with `reason`,
+  `testCommand`, and `testCode` collapsed behind its own `<details>`. Explain
+  that the workflow downgraded the finding to Important; do not present the
+  passing input as proof that every related input is safe.
 - **Test Quality + Review Cost sections**, mirrored from the review file,
   kept concise (verdict + gaps + cost table; no need to reproduce every
   sentence).

package/adapters/claude/olko-github-pr/skills/lekker-review/references/output-format.md

@@ -217,7 +217,7 @@ if empty.)*
 Depth:            <⚡ scan | 🔍 medium | 🔬 deep>
 Diff size:        ~<N> lines (~<N> tokens)
 Agents run:       <N total>: <breakdown, e.g. "5 reviewers (sonnet) + 6 verifiers (sonnet) + 2 provers (sonnet) + 1 critic (sonnet)">
-Verify skipped:   <N> hard-rule finding(s) exempt from adversarial verification (omit the line when 0)
+Rule checks:      <N> hard-rule finding(s) validated with rule-specific checks (omit the line when 0)
 Context sources:  <the subset of issue-tracker / chat / docs / framework-docs / monitoring / CI / prior-review-memory actually used>
 
 Output tokens:    <N>   ← ACTUAL workflow spend, from the workflow's outputTokens return value
@@ -253,10 +253,7 @@ Reviewer agents, verifiers, provers, and the critic all run on sonnet; triage an
   self-contained but silently breaks callers.
 - Blank line between findings. No double blank lines.
 - No trailing whitespace, no HTML tags, no ANSI escapes.
-- **Proof counter-evidence rule**: when `proof.attempted` is true but `proven`
-  is false because the code behaved correctly for the tested input, the
-  synthesis MUST treat that as counter-evidence: either downgrade the finding
-  or state in the finding body why the proof attempt doesn't exonerate it
-  (e.g. the tested input wasn't the one that actually breaks). A finding whose
-  proof came back green cannot silently stay Critical. When `attempted` is
-  false, say nothing: untestable is not evidence either way.
+- **Proof counter-evidence rule**: when `proof.outcome` is `passed`, the
+  workflow has already downgraded the finding from Critical to Important.
+  Explain the passing proof in the finding body. When `attempted` is false,
+  say nothing: untestable is not evidence either way.

package/adapters/claude/olko-reflection/skills/self-critique/scripts/critique-nudge.mjs

@@ -11,6 +11,9 @@ import { readFileSync } from 'node:fs';
 const THRESHOLD = 1500;
 const OFFER_MARKER = /critical-thinking review/i; // the offer line must contain this; doubles as a loop guard
 
+/**
+ * Exits the hook cleanly when conditions for offering a critique are not met.
+ */
 function bail() { process.exit(0); } // any uncertainty => do nothing, never block the user
 
 let raw = '';

package/adapters/claude/olko-release/skills/open-source-publisher/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: open-source-publisher
-description: Prepare an open-source repository for polished public publishing. Use when a user asks to publish, open-source, launch, polish, package, brand, or make a GitHub project presentable with a minimal project icon, social preview image, GitHub Pages landing page, standardized README, essential shields, CI/CD quality gates, release automation checks, and optional donation setup. Prefer the external `logo-generator` skill for icon generation when available, and `nolangz/pixel2motion` for optional motion previews of generated static images.
+description: Prepare an open-source repository for polished public publishing. Use when a user asks to publish, open-source, launch, polish, package, brand, or make a GitHub project presentable with a minimal project icon, social preview image, GitHub Pages landing page, standardized README, essential shields, CI/CD quality gates, release automation checks, and optional donation setup. Prefer the external `logo-generator` skill for icon generation when available, and `nolangz/pixel2motion` for optional motion previews of supported logos or simple artwork.
 license: MIT
 allowed-tools: Bash, Read, Write, Edit, WebSearch, WebFetch
 compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires a writable git repository; browser or image rendering tools are useful for visual validation.
@@ -44,12 +44,11 @@ Use this skill to audit whether an OSS repository is ready to publish, then help
 5. For existing usable pieces, do not propose replacement by default. Ask a change-oriented question only when useful, for example:
    - "You already have a terminal-style GitHub Pages site. Do you want to keep it or restyle it?"
    - "You already have an icon and social card. Do you want a refresh, or should I leave them as-is?"
-   - "You already have a static social card. Do you want me to animate it with pixel2motion, or leave it static?"
    - "You already have release automation. Do you want me to audit only, or also tighten it?"
 6. Ask only for choices needed to fix missing or weak pieces:
    - If GitHub Pages is missing or weak, ask for style: `oldschool linux`, `terminal`, `modern`, `brutalist`, `glassmorphism`, `y2k`, `hacker`, or custom.
    - If donation wiring is missing, ask whether to enable it: `none`, `GitHub Sponsors`, `Ko-fi`, `Buy Me a Coffee`, `Open Collective`, `Thanks.dev`, or custom URL.
-   - If the repo has a generated static social image or hero card, ask whether to animate it using `nolangz/pixel2motion`.
+   - If the repo has a generated logo or simple hero artwork supported by `nolangz/pixel2motion`, ask whether to animate it or leave it static.
    - If the repo has no clear product essence, ask for a one-sentence positioning statement.
 7. Implement only approved, missing, or weak work in this order:
    - OSS governance and support files
@@ -213,8 +212,8 @@ Use `magick` or another renderer when `rsvg-convert` is unavailable.
 
 Some repos benefit from a short animated preview. Keep this opt-in.
 
-- If you already generated a static image, ask: `Do you want me to animate the static image using pixel2motion?`
-- If the user says yes, use `nolangz/pixel2motion` as the optional dependency for logo animation, animated HTML demos, and GIF/video previews.
+- After the user opts in during workflow step 6, animate only the approved generated logo or simple artwork.
+- Use `nolangz/pixel2motion` as the optional dependency for that animation, animated HTML demos, and GIF/video previews.
 - Do not auto-animate by default.
 
 ## README Standard

package/adapters/cursor/olko-reflection/skills/self-critique/scripts/critique-nudge.mjs

@@ -11,6 +11,9 @@ import { readFileSync } from 'node:fs';
 const THRESHOLD = 1500;
 const OFFER_MARKER = /critical-thinking review/i; // the offer line must contain this; doubles as a loop guard
 
+/**
+ * Exits the hook cleanly when conditions for offering a critique are not met.
+ */
 function bail() { process.exit(0); } // any uncertainty => do nothing, never block the user
 
 let raw = '';

package/adapters/cursor/olko-release/skills/open-source-publisher/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: open-source-publisher
-description: Prepare an open-source repository for polished public publishing. Use when a user asks to publish, open-source, launch, polish, package, brand, or make a GitHub project presentable with a minimal project icon, social preview image, GitHub Pages landing page, standardized README, essential shields, CI/CD quality gates, release automation checks, and optional donation setup. Prefer the external `logo-generator` skill for icon generation when available, and `nolangz/pixel2motion` for optional motion previews of generated static images.
+description: Prepare an open-source repository for polished public publishing. Use when a user asks to publish, open-source, launch, polish, package, brand, or make a GitHub project presentable with a minimal project icon, social preview image, GitHub Pages landing page, standardized README, essential shields, CI/CD quality gates, release automation checks, and optional donation setup. Prefer the external `logo-generator` skill for icon generation when available, and `nolangz/pixel2motion` for optional motion previews of supported logos or simple artwork.
 license: MIT
 allowed-tools: Bash, Read, Write, Edit, WebSearch, WebFetch
 compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires a writable git repository; browser or image rendering tools are useful for visual validation.
@@ -44,12 +44,11 @@ Use this skill to audit whether an OSS repository is ready to publish, then help
 5. For existing usable pieces, do not propose replacement by default. Ask a change-oriented question only when useful, for example:
    - "You already have a terminal-style GitHub Pages site. Do you want to keep it or restyle it?"
    - "You already have an icon and social card. Do you want a refresh, or should I leave them as-is?"
-   - "You already have a static social card. Do you want me to animate it with pixel2motion, or leave it static?"
    - "You already have release automation. Do you want me to audit only, or also tighten it?"
 6. Ask only for choices needed to fix missing or weak pieces:
    - If GitHub Pages is missing or weak, ask for style: `oldschool linux`, `terminal`, `modern`, `brutalist`, `glassmorphism`, `y2k`, `hacker`, or custom.
    - If donation wiring is missing, ask whether to enable it: `none`, `GitHub Sponsors`, `Ko-fi`, `Buy Me a Coffee`, `Open Collective`, `Thanks.dev`, or custom URL.
-   - If the repo has a generated static social image or hero card, ask whether to animate it using `nolangz/pixel2motion`.
+   - If the repo has a generated logo or simple hero artwork supported by `nolangz/pixel2motion`, ask whether to animate it or leave it static.
    - If the repo has no clear product essence, ask for a one-sentence positioning statement.
 7. Implement only approved, missing, or weak work in this order:
    - OSS governance and support files
@@ -213,8 +212,8 @@ Use `magick` or another renderer when `rsvg-convert` is unavailable.
 
 Some repos benefit from a short animated preview. Keep this opt-in.
 
-- If you already generated a static image, ask: `Do you want me to animate the static image using pixel2motion?`
-- If the user says yes, use `nolangz/pixel2motion` as the optional dependency for logo animation, animated HTML demos, and GIF/video previews.
+- After the user opts in during workflow step 6, animate only the approved generated logo or simple artwork.
+- Use `nolangz/pixel2motion` as the optional dependency for that animation, animated HTML demos, and GIF/video previews.
 - Do not auto-animate by default.
 
 ## README Standard

package/adapters/grok/olko-reflection/skills/self-critique/scripts/critique-nudge.mjs

@@ -11,6 +11,9 @@ import { readFileSync } from 'node:fs';
 const THRESHOLD = 1500;
 const OFFER_MARKER = /critical-thinking review/i; // the offer line must contain this; doubles as a loop guard
 
+/**
+ * Exits the hook cleanly when conditions for offering a critique are not met.
+ */
 function bail() { process.exit(0); } // any uncertainty => do nothing, never block the user
 
 let raw = '';

package/adapters/grok/olko-release/skills/open-source-publisher/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: open-source-publisher
-description: Prepare an open-source repository for polished public publishing. Use when a user asks to publish, open-source, launch, polish, package, brand, or make a GitHub project presentable with a minimal project icon, social preview image, GitHub Pages landing page, standardized README, essential shields, CI/CD quality gates, release automation checks, and optional donation setup. Prefer the external `logo-generator` skill for icon generation when available, and `nolangz/pixel2motion` for optional motion previews of generated static images.
+description: Prepare an open-source repository for polished public publishing. Use when a user asks to publish, open-source, launch, polish, package, brand, or make a GitHub project presentable with a minimal project icon, social preview image, GitHub Pages landing page, standardized README, essential shields, CI/CD quality gates, release automation checks, and optional donation setup. Prefer the external `logo-generator` skill for icon generation when available, and `nolangz/pixel2motion` for optional motion previews of supported logos or simple artwork.
 license: MIT
 allowed-tools: Bash, Read, Write, Edit, WebSearch, WebFetch
 compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires a writable git repository; browser or image rendering tools are useful for visual validation.
@@ -44,12 +44,11 @@ Use this skill to audit whether an OSS repository is ready to publish, then help
 5. For existing usable pieces, do not propose replacement by default. Ask a change-oriented question only when useful, for example:
    - "You already have a terminal-style GitHub Pages site. Do you want to keep it or restyle it?"
    - "You already have an icon and social card. Do you want a refresh, or should I leave them as-is?"
-   - "You already have a static social card. Do you want me to animate it with pixel2motion, or leave it static?"
    - "You already have release automation. Do you want me to audit only, or also tighten it?"
 6. Ask only for choices needed to fix missing or weak pieces:
    - If GitHub Pages is missing or weak, ask for style: `oldschool linux`, `terminal`, `modern`, `brutalist`, `glassmorphism`, `y2k`, `hacker`, or custom.
    - If donation wiring is missing, ask whether to enable it: `none`, `GitHub Sponsors`, `Ko-fi`, `Buy Me a Coffee`, `Open Collective`, `Thanks.dev`, or custom URL.
-   - If the repo has a generated static social image or hero card, ask whether to animate it using `nolangz/pixel2motion`.
+   - If the repo has a generated logo or simple hero artwork supported by `nolangz/pixel2motion`, ask whether to animate it or leave it static.
    - If the repo has no clear product essence, ask for a one-sentence positioning statement.
 7. Implement only approved, missing, or weak work in this order:
    - OSS governance and support files
@@ -213,8 +212,8 @@ Use `magick` or another renderer when `rsvg-convert` is unavailable.
 
 Some repos benefit from a short animated preview. Keep this opt-in.
 
-- If you already generated a static image, ask: `Do you want me to animate the static image using pixel2motion?`
-- If the user says yes, use `nolangz/pixel2motion` as the optional dependency for logo animation, animated HTML demos, and GIF/video previews.
+- After the user opts in during workflow step 6, animate only the approved generated logo or simple artwork.
+- Use `nolangz/pixel2motion` as the optional dependency for that animation, animated HTML demos, and GIF/video previews.
 - Do not auto-animate by default.
 
 ## README Standard

package/docs/agent-context-store.md

@@ -229,6 +229,52 @@ into it:
   where they do not conflict with this contract. It cannot override lease acquisition,
   validation, append-only writes, secret handling, or the private-repository requirement.
 
+## Reading the store
+
+Everything above is the write side, and it is enforced: a lease, a validator, and CI
+that runs the validator again on push. The read side had none of that. For a while the
+only instruction to read the ledger was one sentence in `AGENTS.md`, which is a rule an
+agent has to remember rather than a mechanism. It did not hold. Two notes written on
+2026-08-25 described failures that both recurred by 2026-08-31: one about stating the
+denominator behind a percentage, one about cache reads dominating a long-session bill.
+Recording a lesson and delivering it are different jobs.
+
+The store therefore ships a reader, `recipes/tools/ledger-index`, built on the shape
+that already works for per-user memory: a cheap index is always in context, and the
+body is fetched on demand. The index is titles only, roughly 1.9k tokens for 84 notes,
+grouped by scope with traps first. The ledger itself is around 50KB and does not belong
+in every session.
+
+```text
+ledger-index                          the index, grouped by scope
+ledger-index --show n41               one note in full, body and Why
+ledger-index --kind trap --scope shell
+ledger-index --count
+```
+
+It resolves the ledger through the same pointer `context-repo` writes, so a machine
+that has resolved the store once needs no further configuration. An explicitly named
+`--ledger` or `LEDGER_PATH` that does not exist is an error rather than a fallback:
+silently reading a different ledger than the one you asked for is the failure this
+whole document exists to prevent.
+
+Hosts wire it in their own way and neither owns the format. A Claude `SessionStart`
+hook injects the index once per session; a Codex prompt shells out to the same binary.
+The reference hook is `recipes/hooks/ledger-index.sh`, which prints nothing and exits 0
+when the store is absent, so it can never fail a session.
+
+The index states its own horizon. It reads from disk and never fetches, because a
+session start is the wrong place for a network call, so the header carries the commit,
+its age in days, and a plain statement that a newer commit may exist upstream. Past
+three days it prints the `pull --rebase` command for that clone. Age of `HEAD` conflates
+a quiet repository with a checkout that is behind, and only a fetch separates them, so
+the limit is stated rather than implied.
+
+One consequence is worth making explicit. The fixed clone path is not a convention, it
+is the point: a second working copy of the store is the copy nothing keeps current, and
+it will be the one an index or an `AGENTS.md` symlink ends up reading. Resolve through
+the pointer and keep one checkout.
+
 ## What is never committed
 
 Raw session content, tokens, private prompts, and customer data never go into the