@gtrabanco/pi-agentic-workflow 0.18.3 → 0.18.5

package/dist/extension/factory.d.ts

@@ -2,6 +2,7 @@ import type { LoadedConfig } from "../config/load.js";
 import type { Catalogue } from "../routing/catalogue.js";
 import type { Router } from "../routing/dispatch.js";
 import { dirtyWorktreeWarning, receiptGuard } from "./receipt-guard.js";
+import { mergeGuard } from "./merge-guard.js";
 import type { ExtensionSurface, InvocationContext, ModelRef, RoutingControls } from "../routing/types.js";
 import type { HintStore } from "../routing/state.js";
 /**
@@ -48,12 +49,14 @@ export interface ExtensionHandle<M extends ModelRef = ModelRef> {
     catalogue: Catalogue;
     /**
      * The Pi-free predicates the adapter (`index.ts`) binds to Pi's lifecycle
-     * events: the inline-receipt block guard and the dirty-worktree notice. They
-     * travel with the handle so the entry stays a thin translation layer and the
-     * decisions are unit-tested with no session (issue #182).
+     * events: the inline-receipt block guard, the merge guard (owner-only
+     * merges, issue #278), and the dirty-worktree notice. They travel with the
+     * handle so the entry stays a thin translation layer and the decisions are
+     * unit-tested with no session (issues #182, #278).
      */
     guards: {
         receiptGuard: typeof receiptGuard;
+        mergeGuard: typeof mergeGuard;
         dirtyWorktreeWarning: typeof dirtyWorktreeWarning;
     };
 }

package/dist/extension/factory.js

@@ -2,6 +2,7 @@ import { loadConfig } from "../config/load.js";
 import { readCatalogue } from "../routing/catalogue.js";
 import { createRouter } from "../routing/dispatch.js";
 import { dirtyWorktreeWarning, receiptGuard } from "./receipt-guard.js";
+import { mergeGuard } from "./merge-guard.js";
 import { ADVANCE_COMMAND, SETTINGS_COMMAND, SETTINGS_COMMAND_ALIAS } from "../routing/types.js";
 import { registerAdvanceCommand } from "./conductor-command.js";
 import { createProfileStateStore, stateFilePath } from "../routing/state.js";
@@ -69,5 +70,5 @@ export function createExtension(deps) {
         description: "Show and configure per-command model routing",
         handler: settingsHandler,
     });
-    return { router, catalogue, guards: { receiptGuard, dirtyWorktreeWarning } };
+    return { router, catalogue, guards: { receiptGuard, mergeGuard, dirtyWorktreeWarning } };
 }

package/dist/extension/index.js

@@ -211,8 +211,16 @@ export default function extension(pi) {
     // names the script that proves the receipt landed (issue #182). The guard
     // 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.
     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 });
+        if (merge.block)
+            return merge;
         const receipt = guards.receiptGuard({ toolName: event.toolName, command });
         if (receipt.block)
             return receipt;

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

@@ -0,0 +1,38 @@
+/**
+ * The merge guard — owner-only merges, enforced 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.
+ *
+ * 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.
+ *
+ * Pure on purpose: `index.ts` is the only file that imports Pi values, so this
+ * predicate compiles and is tested with no session.
+ */
+/** 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;
+}
+/**
+ * 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.
+ */
+export declare function mergeGuard({ toolName, command }: ToolCallLike): MergeGuardDecision;

package/dist/extension/merge-guard.js

@@ -0,0 +1,53 @@
+/**
+ * The merge guard — owner-only merges, enforced 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.
+ *
+ * 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.
+ *
+ * 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).
+ */
+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.";
+/**
+ * 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.
+ */
+export function mergeGuard({ toolName, command }) {
+    if (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 };
+    }
+    return { block: false };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.18.3",
+  "version": "0.18.5",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",

package/skills/phase-contract/SKILL.md

@@ -1,20 +1,22 @@
 ---
 name: phase-contract
 user-invocable: false
-version: 1.0.6
+version: 1.1.0
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
-  Internal contract: the single owner of the eight phase-lint rules, the fixed
-  PASS/BLOCKED result, and the normalized phase fingerprint. Consumed by
-  `execute-phase` and the lane's `plan` step. Not a menu entry.
+  Internal contract: the single owner of the eight phase-lint rules, the two
+  accepted phase grammars, the fixed PASS/BLOCKED result, and the normalized
+  phase fingerprint. Consumed by `execute-phase` and the lane's `plan` step.
+  Not a menu entry.
 ---
 
 # Phase Contract (internal)
 
 The one authoritative owner of phase shape for this workflow. Planners lint
 every phase they emit against the eight rules below; `execute-phase` re-checks
-the same rules before any edit. Nothing else may define what a valid phase is.
+the same rules before any edit. Nothing else may define what a valid phase is —
+including which grammar a phase is written in.
 
 ## When to use
 
@@ -62,18 +64,75 @@ The exemption is scoped to those two boxes: boxes 1, 2, 4, 5, 6 and 8 stay armed
 executed phase, and for an unemitted phase every box stays armed, so pre-ticking
 a phase to dodge a check is a defect, never a pass.
 
+## The two grammars (fix #272)
+
+One contract, two shapes. `scripts/phase-lint.mjs` mechanizes exactly this
+split and never carries a second copy of the semantics:
+
+| grammar | where | shape |
+|---|---|---|
+| **plan** | a plan file, or any `##/###/#### P<n> — <Title>` heading | heading + `Layer: <enum>` + `- [ ]` tasks + `Done-when:` |
+| **unit doc** | the unit doc's `## Tasks` section | one `P<n> — <task> (validator: <command> <outcome>)` bullet per phase, wrapped lines joining the bullet, plus an optional nested `- Relevant files: <path, path…>` line |
+
+Precedence is fail-closed and one-way: **if a document carries any plan-style
+phase heading, the plan grammar governs it**; only when it carries none does
+the unit-doc grammar apply; a document with no phase in either answers
+`BLOCKED: no-phases`. A `P<n>` bullet outside `## Tasks` (a progress-log line,
+for instance) is prose, never a phase.
+
+### Mapping the eight boxes to a bullet phase
+
+A bullet has no separate title line and declares no layer, so two boxes have no
+input and are **skipped** (not "passed"); the rest run unchanged over the
+bullet's joined text:
+
+| box | unit-doc status |
+|---|---|
+| 1 title names one deliverable | **n/a** — there is no title line; the bullet is the task, and box 4 carries atomicity |
+| 2 one declared layer | **n/a** — a unit doc declares no layer (layers belong to plans) |
+| 3 ≥ 1 task, ≤ 8 tasks | applies — a bullet is exactly one task; a repeated `P<n>` number FAILs as `duplicate unit-doc phase P<n>` |
+| 4 one deliverable | applies — same arrow-chain, >3-case and created-file checks |
+| 5 zero decision words | applies, unchanged |
+| 6 no conditional scope mutation | applies, unchanged |
+| 7 no external/manual gates | applies with the **final-bullet exemption**: the last bullet is the unit doc's verification/close-out line, so `manual` / `ask the user` / `gh pr` are allowed there only |
+| 8 machine-checkable done-when | applies — the bullet's `(validator: …)` span **is** the done-when: it must carry a backticked command *and* an expected outcome; a bullet without the span FAILs as `bullet carries no \`(validator: …)\`` |
+
+### The `Relevant files:` sub-section is metadata
+
+A nested `- Relevant files: <path, path…>` line under a bullet declares that
+phase's read set (the lane's plan step writes it from its own discovery). It is
+**never** a task: it does not count toward box 3, never feeds a box-2 target and
+is scanned by no rule. Every entry must be a path or a glob; an empty list, an
+empty entry or a token that is neither fails the phase closed under its own
+`relevant-files:` finding id — a malformed read set is reported, never dropped.
+**Never-authority (same rule as every selector):** a file that is *not* listed
+is never out of scope — an executor may always add one, logging it in the unit
+doc's Progress log.
+
 ## Result — fixed PASS/BLOCKED output
 
 ```text
 Phase-lint: PASS (8/8)
 ```
 
+A unit-doc bullet phase reports the boxes it actually runs:
+
+```text
+P<n> Phase-lint: PASS (6/6) · fingerprint P<n>:unit-doc:<n-tasks>:<title-deliverable>
+```
+
 or, on the first failing box:
 
 ```text
 Phase-lint: BLOCKED — box <n>: <one-line reason>
 ```
 
+A malformed `Relevant files:` sub-section reports under its own id:
+
+```text
+P<n> relevant-files: <one-line reason>
+```
+
 A BLOCKED phase is re-cut or split; it is never emitted, committed, or executed
 as-is (no `--force` bypass exists for a non-atomic phase — that decision belongs
 to the user).
@@ -85,6 +144,10 @@ Each phase's fingerprint is a deterministic string over the phase's shape:
 exact phase version a plan committed to — templates and plans record
 `Phase-lint: PASS (8/8) · fingerprint <fingerprint>` so later re-lints and
 `execute-phase` can confirm nothing in the phase shape drifted since planning.
+A unit-doc bullet phase has no layer, so its slot is the literal `unit-doc`
+(`P<n>:unit-doc:<n-tasks>:<title-deliverable>`, title = the bullet text up to
+its first `:`, with the `(validator: …)` span removed); both grammars hash the
+same way, so a re-lint of either is comparable with its own earlier run.
 
 ## Guardrails
 

package/skills/unit-lane/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: unit-lane
 user-invocable: true
-version: 1.1.0
+version: 1.1.1
 argument-hint: <NN-slug | "<idea>"> [--retriage] | --fix <issue-number> | --from-issue <issue-number>
 description: >
   One-shot lane conductor for a delivery unit: triage, implement, evidence, and

package/skills/unit-lane/references/PLAN.md

@@ -15,17 +15,27 @@ first. No future-phase work.
 Fill the unit doc's **Tasks** section:
 
 ```
-P1 — <task description> (validator: <what proves it works>)
-P2 — <task description> (validator: <what proves it works>)
+P1 — <task description> (validator: <backticked command> <expected outcome>)
+  - Relevant files: <path, path…>
+P2 — <task description> (validator: <backticked command> <expected outcome>)
 …
 Pn — last task is verification when the unit has behavior
 ```
 
+Both phase grammars are accepted (owner: `phase-contract`): these bullets, or
+full plan-style `## P<n> —` blocks when the unit doc already carries them —
+`phase-lint` parses either and answers `no-phases` only when it finds neither.
+A bullet's `(validator: …)` span is its machine-checkable done-when (a
+backticked command **and** an expected outcome, e.g. `exits 0`), and the nested
+`Relevant files:` line is **metadata, never a task** — it is that phase's read
+set, written from the planner's own discovery, and a file that is missing from
+it is never out of scope for the executor.
+
 ## Checklist (pass only if)
 
 - [ ] Every AC maps to at least one task
 - [ ] Tasks are ordered smallest first
-- [ ] Each task names its validator (command, output, or observation)
+- [ ] Each task names its validator (a backticked command plus its expected outcome)
 - [ ] Final task is verification (proves the whole unit works)
 - [ ] No task reaches into a future-phase concern (docs, release, migrations)
 - [ ] Phases labeled P1, P2, … (never S1, Step 1)