@gtrabanco/pi-agentic-workflow 0.37.0 → 4.10.0

package/dist/extension/history-guard.js

@@ -0,0 +1,132 @@
+/**
+ * The history guard — published history is owner-written, decided by git
+ * itself (`git push --dry-run`), not by enumerating spellings.
+ *
+ * AGENTS.md → Working rules states the way this repository integrates work:
+ * short branches off `main`, `main` only advances through a PR, and when `main`
+ * moves the conflicted branch is handed back for the owner to integrate. A
+ * local `git rebase` is a private rewrite; the moment it is pushed it rewrites
+ * commits a reviewer, another session or a CI artifact may already be building
+ * on, so the block sits where the rewrite becomes public — on `git push`.
+ *
+ * The outcome, not the spelling, is what is judged. Every direct `git push`
+ * runs first as `git push --dry-run` (the same arguments, plus `--dry-run` —
+ * git resolves flags and refspecs itself), and the printed outcome decides: a
+ * `(forced update)`, a `[deleted]` ref, or a destination of `main` declines
+ * the push. One mechanism covers every force flag spelling and `+`/`:ref`
+ * refspec, because the answer comes from git, not from this file. When the
+ * dry-run cannot run (offline — where a real push would fail anyway), a simple
+ * text check on the push's own segment is the fallback.
+ *
+ * The guard is config-gated (`guards.history`): off by default for every
+ * project, enabled where an operator asks for it. The only way through is an
+ * explicit owner instruction in the same turn, carried as the command's first
+ * word: `AW_ALLOW=force` — which never enables a push to `main`, because main
+ * advances only through a PR.
+ *
+ * What is deliberately out of scope: payloads hidden inside scripts or
+ * interpreter one-liners that never spell `git push` in the command text, and
+ * a git alias invoked as `git fp` — the dry-run sees what git is told to push,
+ * not what an alias named `fp` expands to. The dry-run sees what git sees; it
+ * cannot see what a script builds at runtime, and no text predicate honestly
+ * can. The residual risk is documented, not chased with a regex zoo.
+ */
+import { spawnSync } from "node:child_process";
+import { explicitAllow, splitSegments } from "./guard-util.js";
+/** A direct `git push` (optionally after `-C <path>` / `-c <name=value>`). */
+const GIT_PUSH_RE = /(?:^|[\s;|&])git\s+(?:-[Cc]\s+\S+\s+)*push(?![\w-])(?=\s|$)/u;
+/** The REST twin of a force push: `gh api` moving a ref with `force`. */
+const GH_API_FORCE_REF_RE = /\bgh\s+api\b[\s\S]*refs\/heads\/[\s\S]*\bforce\b/u;
+/** Offline fallback — the flags that make a push rewrite or delete. */
+const FALLBACK_REWRITE_RE = /(?:^|\s)(?:--force(?:-with-lease(?:=\S*)?|-if-includes)?|--mirror|--all|--branches|--delete)(?=\s|$)/u;
+const FALLBACK_SHORT_RE = /(?:^|\s)-[a-z]*[fd][a-z]*(?=\s|$)/u;
+const FALLBACK_REFSPEC_RE = /(?:^|\s)[+:]\S+|^:\S+/u;
+const FALLBACK_MAIN_RE = /(?:^|[\s:])(?:refs\/heads\/)?main(?=\s|$)/u;
+/** The default runner: git in the session's working directory. */
+export function spawnPushRunner(cwd) {
+    return (args) => {
+        const result = spawnSync("git", ["push", "--dry-run", ...args], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 30_000,
+        });
+        return { status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+    };
+}
+/** Shell-tokenize the arguments of one push segment (quotes stripped). */
+export function pushArgs(segment) {
+    const rest = segment.replace(/^[\s]*git\s+(?:-[Cc]\s+\S+\s+)*push(?![\w-])\s?/u, "");
+    return rest
+        .split(/\s+/u)
+        .filter((token) => token !== "")
+        .map((token) => token.replace(/^["'`]|["'`]$/gu, ""));
+}
+/** Read the outcome git printed for one dry-run. */
+export function readPushOutcome(result) {
+    if (result.status !== 0)
+        return "unknown";
+    for (const line of result.stdout.split("\n")) {
+        if (/\(forced update\)/u.test(line))
+            return "forced";
+        if (/\[deleted\]/u.test(line))
+            return "deleted";
+        const arrow = /->\s*(\S+)\s*$/u.exec(line.trim());
+        if (arrow) {
+            const ref = arrow[1].replace(/^refs\/heads\//u, "");
+            if (ref === "main")
+                return "main";
+        }
+    }
+    return "clean";
+}
+/** The offline fallback, scoped to one push segment. */
+function fallbackOutcome(segment) {
+    const args = pushArgs(segment);
+    const text = args.join(" ");
+    if (FALLBACK_REWRITE_RE.test(` ${text} `) || FALLBACK_SHORT_RE.test(` ${text} `) || FALLBACK_REFSPEC_RE.test(` ${text} `)) {
+        return "forced";
+    }
+    if (FALLBACK_MAIN_RE.test(` ${text} `))
+        return "main";
+    return "unknown";
+}
+/**
+ * The `tool_call` gate. `enabled` comes from the config (`guards.history`);
+ * the guard is a no-op while disabled. `runner`/`cwd` are injectable so the
+ * suite never touches the network.
+ */
+export function historyGuard({ toolName, command }, enabled = true, { runner, cwd = process.cwd(), offlineFallback = fallbackOutcome } = {}) {
+    if (!enabled || toolName !== "bash")
+        return { block: false };
+    const text = command ?? "";
+    const allow = explicitAllow(text);
+    // `gh api` forcing a ref update is a push by other means; the dry-run never
+    // sees it, so the text is the only witness.
+    if (!allow.has("force") && GH_API_FORCE_REF_RE.test(text)) {
+        return { block: true, reason: `${HISTORY_REASON} (blocked: \`gh api\` forcing a ref update)` };
+    }
+    for (const segment of splitSegments(text)) {
+        if (!GIT_PUSH_RE.test(segment))
+            continue;
+        const args = pushArgs(segment);
+        const run = runner ?? spawnPushRunner(cwd);
+        let outcome = readPushOutcome(run(args));
+        if (outcome === "unknown")
+            outcome = offlineFallback(segment);
+        if (outcome === "forced" || outcome === "deleted") {
+            if (!allow.has("force")) {
+                return { block: true, reason: `${HISTORY_REASON} (git reports: ${outcome === "forced" ? "a forced update" : "a ref delete"})` };
+            }
+        }
+        if (outcome === "main") {
+            // `force` never enables main: main advances only through a PR.
+            return { block: true, reason: `${HISTORY_REASON} (blocked: a push whose destination is \`main\`)` };
+        }
+    }
+    return { block: false };
+}
+export const HISTORY_REASON = "Published history is owner-written (AGENTS.md → Working rules): an agent session does not rewrite, delete or force commits that are already pushed, and never pushes `main` — main advances only through a PR. " +
+    "The push was declined by asking git what it would do (`git push --dry-run`). " +
+    "Only an explicit owner instruction in this turn (\"Sí, usa force\") enables it, carried as the command's first word: `AW_ALLOW=force` — which never enables a push to `main`. " +
+    "A conflict with `main` is resolved by handing the branch back: the owner runs the integration.";

package/dist/extension/index.js

@@ -297,15 +297,31 @@ export default function extension(pi) {
     // itself filters to `bash`, so every tool call is checked — nesting it under
     // one tool name would make the block unreachable for the calls it exists for.
     //
-    // Merges are owner-only (issue #278): `gh pr merge`, the `gh api` merge
-    // endpoints, and `git merge` are blocked before anything else runs — a
-    // review waiver is not merge authorization. Read-only git (`merge-tree`,
-    // `merge-base`) and rebases pass; the reason hands the PR URL to the owner.
+    // Owner-gated tool guards, all config-driven (`guards` in the config files;
+    // every guard ships OFF — a project opts in per guard):
+    //   merge    `git merge`, `gh pr merge`, `git pull`'s merge form (issue #278).
+    //   history  pushes decided by git itself (`git push --dry-run`): a forced
+    //            update, a ref delete or a push to `main` is declined.
+    //   ci       writing workflow definitions and triggering workflow runs.
+    //   cost     commands estimated above the configured token budget.
+    // The only way through any of them is the explicit per-command token
+    // (`AW_ALLOW=merge|force|ci|cost`) after an owner instruction in the turn.
     pi.on("tool_call", (event, ctx) => {
         const command = "command" in event.input && typeof event.input.command === "string" ? event.input.command : undefined;
-        const merge = guards.mergeGuard({ toolName: event.toolName, command });
+        const inputPath = "path" in event.input && typeof event.input.path === "string" ? event.input.path : undefined;
+        const { guards: policy } = loadConfig({ agentDir, cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() }).config;
+        const merge = guards.mergeGuard({ toolName: event.toolName, command }, policy.merge);
         if (merge.block)
             return merge;
+        const history = guards.historyGuard({ toolName: event.toolName, command }, policy.history, { cwd: ctx.cwd });
+        if (history.block)
+            return history;
+        const ci = guards.ciGuard({ toolName: event.toolName, command, path: inputPath }, policy.ci);
+        if (ci.block)
+            return ci;
+        const cost = guards.costGuard({ toolName: event.toolName, command }, policy.expensiveTests);
+        if (cost.block)
+            return cost;
         const receipt = guards.receiptGuard({ toolName: event.toolName, command });
         if (receipt.block)
             return receipt;

package/dist/extension/merge-guard.d.ts

@@ -1,38 +1,36 @@
 /**
- * The merge guard — owner-only merges, enforced at the `tool_call` gate
- * (issue #278).
+ * The merge guard — owner-only merges at the `tool_call` gate (issue #278).
  *
  * On 2026-09-29 an agent session ran `gh pr merge` after an owner message that
  * waived only the *review* ("No hace falta una review para esto"), not the
- * merge. Merging is owner-only: prose already says so (`audit-pr` "never
- * merges") and prose demonstrably failed once, so the block lives here, in the
- * same Pi-free layer as the inline-receipt guard (issue #182) — a predicate the
- * shipped adapter binds to `tool_call`, unit-tested with no session.
+ * merge. Merging is owner-only, and the direct routes are self-evident — a
+ * command that *is* a merge needs no simulation and no spelling census:
  *
- * Same philosophy as `receipt-guard`: deterministic over clever. A bash command
- * that merely *mentions* `gh pr merge` (a search for the guard's own text) is
- * blocked like an invocation; the reason tells the agent to search `pr merge`
- * instead. This is a guard, not a wall — it covers what routes through Pi's
- * tool pipeline, exactly like the path-protection guard beside it.
+ *   `git merge <ref>`   the command is a merge (read-only forms —
+ *                       `merge-tree`, `merge-base`, `merge-file` — stay out).
+ *   `gh pr merge`       the command merges the PR.
+ *   `gh api` merge      the REST endpoint (`pulls/N/merge`) and the GraphQL
+ *                       mutations (`mergePullRequest`, `mergeBranch`,
+ *                       `enablePullRequestAutoMerge`) — the same merge by
+ *                       other syntax, still self-evident.
+ *   `git pull`          fetch + merge by default; only `--rebase`/`--ff-only`
+ *                       (no merge commit) pass.
  *
- * Pure on purpose: `index.ts` is the only file that imports Pi values, so this
- * predicate compiles and is tested with no session.
+ * The guard is config-gated (`guards.merge`): off by default for every
+ * project, enabled where an operator asks for it. The only way through is an
+ * explicit owner instruction in the same turn, carried as the command's first
+ * word: `AW_ALLOW=merge`.
+ *
+ * What is deliberately out of scope: merges hidden inside scripts or
+ * interpreter one-liners. A text predicate that chased every wrapper would
+ * grow a regex zoo and still miss the file it never read; the direct routes
+ * above are the honest boundary.
  */
-/** The narrow slice of a Pi `tool_call` the guard reads. */
-export interface ToolCallLike {
-    toolName: string;
-    command?: string | undefined;
-}
-/** The Pi `tool_call` result shape: `block` plus an actionable `reason`. */
-export interface MergeGuardDecision {
-    block: boolean;
-    reason?: string;
-}
+import { type GuardDecision, type ToolCallLike } from "./guard-util.js";
+export declare const MERGE_REASON: string;
 /**
  * The `tool_call` gate. Blocks merge shapes on the `bash` tool only — every
- * other tool passes, and every non-merge command passes. Read-only git
- * (`merge-tree`, `merge-base`), rebases, and PR reads (`gh pr view`, checks,
- * comments) are deliberately out of scope; `gh pr comment` receipts remain the
- * receipt guard's domain.
+ * other tool passes, and every non-merge command passes. `enabled` comes from
+ * the config (`guards.merge`); the guard is a no-op while disabled.
  */
-export declare function mergeGuard({ toolName, command }: ToolCallLike): MergeGuardDecision;
+export declare function mergeGuard({ toolName, command }: ToolCallLike, enabled?: boolean): GuardDecision;

package/dist/extension/merge-guard.js

@@ -1,53 +1,79 @@
 /**
- * The merge guard — owner-only merges, enforced at the `tool_call` gate
- * (issue #278).
+ * The merge guard — owner-only merges at the `tool_call` gate (issue #278).
  *
  * On 2026-09-29 an agent session ran `gh pr merge` after an owner message that
  * waived only the *review* ("No hace falta una review para esto"), not the
- * merge. Merging is owner-only: prose already says so (`audit-pr` "never
- * merges") and prose demonstrably failed once, so the block lives here, in the
- * same Pi-free layer as the inline-receipt guard (issue #182) — a predicate the
- * shipped adapter binds to `tool_call`, unit-tested with no session.
+ * merge. Merging is owner-only, and the direct routes are self-evident — a
+ * command that *is* a merge needs no simulation and no spelling census:
  *
- * Same philosophy as `receipt-guard`: deterministic over clever. A bash command
- * that merely *mentions* `gh pr merge` (a search for the guard's own text) is
- * blocked like an invocation; the reason tells the agent to search `pr merge`
- * instead. This is a guard, not a wall — it covers what routes through Pi's
- * tool pipeline, exactly like the path-protection guard beside it.
+ *   `git merge <ref>`   the command is a merge (read-only forms —
+ *                       `merge-tree`, `merge-base`, `merge-file` — stay out).
+ *   `gh pr merge`       the command merges the PR.
+ *   `gh api` merge      the REST endpoint (`pulls/N/merge`) and the GraphQL
+ *                       mutations (`mergePullRequest`, `mergeBranch`,
+ *                       `enablePullRequestAutoMerge`) — the same merge by
+ *                       other syntax, still self-evident.
+ *   `git pull`          fetch + merge by default; only `--rebase`/`--ff-only`
+ *                       (no merge commit) pass.
  *
- * Pure on purpose: `index.ts` is the only file that imports Pi values, so this
- * predicate compiles and is tested with no session.
- */
-/** `gh pr merge` as an invoked command, not as a quoted string elsewhere in it. */
-const GH_PR_MERGE_RE = /\bgh\s+pr\s+merge\b/;
-/** The REST merge endpoint and the GraphQL mutation, both under `gh api`. */
-const GH_API_MERGE_RE = /\bgh\s+api\b[\s\S]*(?:pulls\/\d+\/merge\b|mergePullRequest\b)/;
-/**
- * `git merge <args>` (optionally after `-C <path>` / `-c <name>`), at a word
- * boundary that is deliberately NOT `-`: `git merge-tree` and `git merge-base`
- * are read-only and the reconciliation flow depends on them (issue #275).
+ * The guard is config-gated (`guards.merge`): off by default for every
+ * project, enabled where an operator asks for it. The only way through is an
+ * explicit owner instruction in the same turn, carried as the command's first
+ * word: `AW_ALLOW=merge`.
+ *
+ * What is deliberately out of scope: merges hidden inside scripts or
+ * interpreter one-liners. A text predicate that chased every wrapper would
+ * grow a regex zoo and still miss the file it never read; the direct routes
+ * above are the honest boundary.
  */
-const GIT_MERGE_RE = /(^|[\s;|&()])git\s+(?:-[Cc]\s+\S+\s+)*merge(?![\w-])(?=\s|$)/;
-const GH_MERGE_REASON = "Merging is owner-only (merge guard, issue #278): a merge command from an agent session is blocked — a review waiver is not merge authorization. " +
-    "Open or refresh the PR and hand its URL to the owner (`gh pr view <N> --json url -q .url`); if you were searching text, search `pr merge` instead of `gh pr merge`.";
-const GIT_MERGE_REASON = "Merging is owner-only (merge guard, issue #278): `git merge` from an agent session is blocked. " +
-    "Hand the branch to the owner for integration, or use the read-only forms (`git merge-tree`, `git merge-base`) and rebases, which stay allowed.";
+import { explicitAllow, splitSegments } from "./guard-util.js";
+/** `git merge` at a word boundary — `merge-tree`/`merge-base`/`merge-file` stay out. */
+const GIT_MERGE_RE = /(?:^|[\s;|&])git\s+(?:-[Cc]\s+\S+\s+)*merge(?![\w-])(?=\s|$)/u;
+/** `git pull` — merge by default. */
+const GIT_PULL_RE = /(?:^|[\s;|&])git\s+(?:-[Cc]\s+\S+\s+)*pull(?![\w-])(?=\s|$)/u;
+/** pull flags that make it a rebase or a fast-forward-only update: no merge commit. */
+const PULL_NO_MERGE_RE = /(?:^|\s)(?:--rebase(?:=(?!=false)\S*)?|--ff-only|-[a-z]*r[a-z]*)(?=\s|$)/u;
+/** pull flags that force the merge form back on. */
+const PULL_MERGE_RE = /(?:^|\s)(?:--no-rebase|--rebase=false)(?=\s|$)/u;
+const GH_PR_MERGE_RE = /\bgh\s+pr\s+merge\b/u;
+/** The REST endpoint and GraphQL mutations that are a merge by other syntax. */
+const GH_API_MERGE_RE = /\bgh\s+api\b[\s\S]*(?:pulls\/\d+\/merge\b|\b(?:mergePullRequest|mergeBranch|enablePullRequestAutoMerge)\b)/u;
+/** The merge shape one command segment carries, or null. */
+function mergeShape(segment) {
+    if (GH_PR_MERGE_RE.test(segment))
+        return "`gh pr merge`";
+    if (GH_API_MERGE_RE.test(segment))
+        return "a `gh api` merge endpoint or mutation";
+    if (GIT_MERGE_RE.test(segment))
+        return "`git merge`";
+    if (GIT_PULL_RE.test(segment)) {
+        if (PULL_MERGE_RE.test(segment))
+            return "`git pull` in its merge form";
+        if (!PULL_NO_MERGE_RE.test(segment)) {
+            return "`git pull` in its merge form (use `git pull --rebase`, `--ff-only`, or `git fetch` + ask)";
+        }
+    }
+    return null;
+}
+export const MERGE_REASON = "Merging is owner-only (merge guard, issue #278): a merge command from an agent session is blocked — a review waiver is not merge authorization. " +
+    "Only an explicit owner instruction in this turn (\"Sí, mergea la PR\" / \"Mergea rama B en rama A\") enables it, carried as the command's first word: `AW_ALLOW=merge`. " +
+    "Otherwise: resolve the files, report, and hand the branch to the owner (`gh pr view <N> --json url -q .url`). " +
+    "If you were searching text, search `pr merge` instead of `gh pr merge`.";
 /**
  * The `tool_call` gate. Blocks merge shapes on the `bash` tool only — every
- * other tool passes, and every non-merge command passes. Read-only git
- * (`merge-tree`, `merge-base`), rebases, and PR reads (`gh pr view`, checks,
- * comments) are deliberately out of scope; `gh pr comment` receipts remain the
- * receipt guard's domain.
+ * other tool passes, and every non-merge command passes. `enabled` comes from
+ * the config (`guards.merge`); the guard is a no-op while disabled.
  */
-export function mergeGuard({ toolName, command }) {
-    if (toolName !== "bash")
+export function mergeGuard({ toolName, command }, enabled = true) {
+    if (!enabled || toolName !== "bash")
         return { block: false };
     const text = command ?? "";
-    if (GH_PR_MERGE_RE.test(text) || GH_API_MERGE_RE.test(text)) {
-        return { block: true, reason: GH_MERGE_REASON };
-    }
-    if (GIT_MERGE_RE.test(text)) {
-        return { block: true, reason: GIT_MERGE_REASON };
+    if (explicitAllow(text).has("merge"))
+        return { block: false };
+    for (const segment of splitSegments(text)) {
+        const shape = mergeShape(segment);
+        if (shape)
+            return { block: true, reason: `${MERGE_REASON} (blocked: ${shape})` };
     }
     return { block: false };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.37.0",
+  "version": "4.10.0",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",
@@ -43,25 +43,26 @@
   },
   "scripts": {
     "build": "tsc",
+    "build:deps": "bun run --cwd ../agentic-workflow-schema build",
     "bundle:skills": "bun scripts/bundle-skills.mjs",
     "clean:skills": "bun scripts/bundle-skills.mjs --clean",
     "test": "bun run bundle:skills && tsc && bun test test/*.test.mjs",
     "test:node": "bun run bundle:skills && tsc && node --test test/*.test.mjs",
-    "prepublishOnly": "bun run build && bun run bundle:skills && bun run test",
+    "prepublishOnly": "bun run build:deps && bun run build && bun run bundle:skills && bun run test",
     "postpack": "bun run clean:skills",
     "mutation": "bun run bundle:skills && bun scripts/mutation-check.mjs",
-    "prepare": "bun run build && bun run bundle:skills"
+    "prepare": "bun run build:deps && bun run build && bun run bundle:skills"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.99.1",
     "@earendil-works/pi-tui": "*"
   },
   "dependencies": {
-    "@gtrabanco/agentic-workflow": "0.5.0",
-    "@gtrabanco/agentic-workflow-schema": "4.9.0"
+    "@gtrabanco/agentic-workflow": "4.10.0",
+    "@gtrabanco/agentic-workflow-schema": "4.10.0"
   },
   "devDependencies": {
     "@types/node": "24.13.3",
-    "typescript": "6.0.3"
+    "typescript": "7"
   }
 }

package/skills/audit-docs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: audit-docs
 user-invocable: true
-version: 2.2.0
+version: 4.10.0
 argument-hint: "[--fix]"
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/audit-pr/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: audit-pr
 user-invocable: true
-version: 5.6.3
+version: 4.10.0
 argument-hint: <pr-number> (optional — defaults to the current branch's PR)
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -50,6 +50,12 @@ independently evaluates only the delivery gates below.
   this skill and cannot be inherited from docs or an earlier session
 ✓ No review pass was composed or reconstructed: a missing/stale receipt is a
   blocker, never a prompt to re-run review axes from this skill
+✓ **Every AC links a demonstration artifact (S3, S7).** Read the unit doc's
+  `## Acceptance criteria` (or `## Specs` S# + `## Acceptance criteria` in
+  the re-cut shape). For each AC, verify it links a demonstration:
+  a passing test with output, a UI capture, a reproduced command output.
+  An AC without a demonstration is a **BLOCKER** — the PR's body must render
+  it. A PR whose ACs lack demonstrations never reaches the merge gate.
 ✓ Closure integrity was evaluated and its result stated explicitly: pass /
   blocker / n-a (fix-governed PRs are always n-a; never skipped
   silently)
@@ -77,6 +83,11 @@ first on purpose).
 everything the SPEC promised is present, traceable, and green. A missing or stale
 receipt is a blocker routed back to `/review-change`, never re-litigated here.
 
+**Cost-scaling invariant (S7).** Reviewers dig into code only when evidence is
+absent or contradicts — so review cost scales with the change, not the project.
+The non-technical approver (human layer) validates demonstrations; the merge
+gate (technical layer) validates evidence linkage. Same evidence, two readings.
+
 ## Scope
 
 The whole pull request: the branch vs. the default base, **plus** its SPEC and

package/skills/discover-repository-state/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: discover-repository-state
 user-invocable: true
-version: 1.2.2
+version: 4.10.0
 description: >
   Discover repository evidence and write a frozen Normalized Repository State.
   Produces verified repository evidence and keeps facts, decisions, planned

package/skills/execute-phase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: execute-phase
 user-invocable: true
-version: 6.5.0
+version: 4.10.0
 argument-hint: <NN-slug> [P<k>|step] [--max-attempts N] [--force]
 allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
@@ -43,11 +43,16 @@ if bun is not installed) and the
 ✓ Unit doc read and step selected (explicit P<k> or first unfinished)
 ✓ Step executed and committed (one commit per step, conventional format)
 ✓ Evidence rows updated (command → exit/digest → output → verified-by)
+  — each row carries the command, observed output (reproduced, not typed by
+  hand), and the verifying-by credit. (S5 — claim-evidence loop: mandatory
+  reproduction, loop-until-green inside the same turn)
 ✓ Progress log updated with a dated `YYYY-MM-DD HH:MM` entry that names the
   phase id (what, commit, next)
 ✓ Memory boundary ran — the phase's outcome saved under `unit/<NN-slug>/doc`,
   or the mirror marked pending when the layer is degraded
 ✓ Diff guard passed (on implement steps) — see `diff-guard` in PREFLIGHT.md
+✓ Self-audit box (S9 d): every claim the persist introduces was re-derived
+  with pasted output before the commit lands.
 ✓ → Next: block printed as the absolute last output
 ```
 
@@ -133,14 +138,51 @@ work. For `implement` steps: write tests-first where they pay (core/domain,
 orchestration — record the failing red run's command, exit, and failing test
 names before implementation), then green. UI/adapter glue may test after.
 
-### 5. Post-step
+### 5. Claim-evidence loop (S5 — before post-step)
+
+Before running post-step, verify every claim the step's repair introduces. This
+is the repairer-owned verification that prevents the unit 79 F50-class failure
+(closed gate-green with an unreproduced figure "170" without re-deriving via
+`git diff --numstat`).
+
+1. **Claim ledger.** Enumerate every claim: each new figure, cross-reference,
+   "X is now Y"; in code: each behavior the step declares.
+2. **Mandatory reproduction.** Re-derive the figure with the command, resolve
+   the reference with grep, reproduce the behavior. Paste command + observed
+   output into the claim table — never type the expected result by hand.
+3. **Loop until green.** red → repair → re-run, *inside the same turn*, until
+   every claim verifies.
+4. **Admission rule.** If no command can verify the sentence, it is not a
+   claim, it is an opinion, and it does not get written.
+
+Output:
+
+```
+| claim | command | output | status |
+|---|---|---|---|
+| <claim> | `<command>` | `<observed output>` | ✓ |
+```
+
+The row shape is published grammar (`evidence-row@1` in
+`@gtrabanco/agentic-workflow-schema`), so a row missing its command, its
+observed output or a ✓/✗ verdict is a shape violation rather than a style nit.
+
+**Bounded checkpoint (S13/S14).** The claim-evidence loop is only paid if it is
+cheap: `node scripts/test-route.mjs --check <changed path>` names the minimal
+suite a path needs, so an intermediate verification costs seconds instead of the
+full gate. An unmatched path answers `route: full-suite` — never fewer tests —
+and the full gate stays what the merge gate and CI run.
+
+### 6. Post-step
 
 1. **Diff guard** (implement steps only): run `bun scripts/diff-guard.mjs --base
    <last-step-commit> --unit <unit>` — paste the block verbatim. **BREACH → STOP**
    (re-triage or record exception). Anti-gaming: **NEVER shrink a diff by deleting
    comments, blank lines, docs or tests.**
 2. **Evidence rows**: one row per AC satisfied — `| AC | command | exit/digest |
-   output (≤2 lines) | verified-by |`. Append to the Evidence section.
+   output (≤2 lines, reproduced via command, not typed by hand) | verified-by |`
+   — append to the Evidence section. The evidence row is a *reproduced receipt*,
+   not an assertion (S5: mandatory reproduction extends to doc artifacts).
 3. **Progress log**: append a dated entry —
    `YYYY-MM-DD HH:MM — <what was done> → <commit sha> — next: <what is next>`.
 4. **Memory boundary** — this step is a phase transition. Follow
@@ -153,7 +195,7 @@ names before implementation), then green. UI/adapter glue may test after.
 5. **Commit**: `git add <changed files>` then `git commit -m "<type>(<scope>):
    <step-summary>"` — run it, paste the SHA.
 
-### 6. Red gate (repair loop)
+### 7. Red gate (repair loop)
 
 After each step: run the project's verification gate (type-check + tests + build).
 
@@ -173,7 +215,7 @@ After each step: run the project's verification gate (type-check + tests + build
     · continue atomically → /execute-phase <unit> <P<k>>
   ```
 
-### 7. Whole-unit mode
+### 8. Whole-unit mode
 
 When invoked as `<NN-slug>` with no step: loop all remaining steps, one commit
 each. This is an **explicit operator choice only** — the lane's hand-offs
@@ -200,7 +242,7 @@ PR: <url>
   · merge gate after REVIEW-PASS → /audit-pr
 ```
 
-### 8. Descope guard
+### 9. Descope guard
 
 Before creating **any** issue while executing: classify with the descope test.
 A descope (moving an acceptance criterion or task out of scope) requires
@@ -221,6 +263,11 @@ These files must be loaded when their topic is active:
 
 ## Guardrails
 
+- The all-stages no-assumption rule binds every step here — **ask-don't-infer**,
+  owner `skills/unit-lane/references/DESIGN.md` (`ask-dont-infer@1`): an
+  expectation the tree, the docs, or a prior owner decision does not evidence
+  is asked, never invented.
+
 **Allowed:**
 - Only the triaged steps listed by the unit doc's Evidence header
 - Changes scoped to the acceptance criteria and step tasks
@@ -235,6 +282,14 @@ These files must be loaded when their topic is active:
   keep assertions at least as strong.
 - Never execute a step the triage skipped — the catalog is authoritative.
 - Never edit the unit doc's Acceptance criteria (that is re-triage with user consent).
+- Never write to `docs/LOGS.md` (S9 4b): LOGS.md must be pure code output —
+  no model writes it. The interim rule (until feature 41's
+  `autoLogSession: mechanical`) is append-only: a wrong past line gets a *new
+  correcting line*, never an edit. Machine-authored git-facts entries also
+  kill the "hand-tallied figure" class.
+- Self-audit box (S9 d): before committing, re-derive every claim the step's
+  persist introduces with pasted output. The turn does not end with unreproduced
+  claims.
 - Never expand scope beyond what Non-goals define — findings discovered during
   implementation never widen the unit.
 - Never invent an acceptance criterion — ask the user with concrete options.