@gtrabanco/pi-agentic-workflow 4.10.0 → 5.0.0-canary.20261102.1

package/README.md

@@ -326,9 +326,9 @@ dialog.
 
 - Verified against the peer floor Pi 0.99.1 (2026-09-29) (`pi install`, package skills, friendly
   command registration, routed set/clear, settings console round-trip, `sendUserMessage`
-  with prompt template expansion). Also verified against Pi 1.2.0 (2026-10-14) via a local
+  with prompt template expansion). Also verified against Pi 1.5.0 (2026-11-02) via a local
   two-leg `tsc --noEmit` run (legs `0.99.1` + `latest`, the `latest` leg resolving to pi
-  1.2.0; COMPAT-OK); continuously against the
+  1.5.0; COMPAT-OK); continuously against the
   `latest` dist-tag by the `pi-compat-guard` PR gate (the leg is a moving tripwire,
   not a pinned version — a breaking release shows red here first).
 - The package declares Pi as a peer dependency; it bundles no copy of Pi.

package/dist/config/defaults.js

@@ -20,14 +20,6 @@ export const DEFAULT_CONFIG = {
     // Feature 66 — the memory substrate is ask-first: nothing is provisioned
     // until the operator opts in.
     memory: { engram: false },
-    // Tool-call guards ship all-off: they are this repository's working rules,
-    // not a package opinion — a project opts in per guard in its config file.
-    guards: {
-        merge: false,
-        history: false,
-        ci: { create: false, run: false },
-        expensiveTests: { maxTokens: 0, patterns: [] },
-    },
     profiles: {},
     profileOrder: [],
     profileFallback: { ...DEFAULT_PROFILE_FALLBACK },

package/dist/config/merge.js

@@ -132,9 +132,6 @@ export function mergeConfigs(globalFile = {}, projectFile = {}) {
         memory: {
             engram: pick(false, projectFile.memory?.engram, globalFile.memory?.engram) === true,
         },
-        // Tool-call guards resolve like every other knob: project wins, then
-        // global, then the shipped OFF. A guard no scope mentions stays disabled.
-        guards: mergeGuards(globalFile.guards, projectFile.guards),
         profiles: mergeProfiles(globalFile.profiles, projectFile.profiles),
         profileOrder: pick([], projectFile.profileOrder, globalFile.profileOrder),
         profileFallback: mergeProfileFallback(globalFile.profileFallback, projectFile.profileFallback),
@@ -147,23 +144,6 @@ export function mergeConfigs(globalFile = {}, projectFile = {}) {
         merged.advance = advance;
     return merged;
 }
-/** Guards merge whole-knob: a boolean takes project-then-global, and the
- *  expensive-tests block resolves field-by-field (patterns are replaced, not
- *  concatenated, so a project override is predictable — no hidden union). */
-function mergeGuards(globalGuards, projectGuards) {
-    return {
-        merge: pick(DEFAULT_CONFIG.guards.merge, projectGuards?.merge, globalGuards?.merge),
-        history: pick(DEFAULT_CONFIG.guards.history, projectGuards?.history, globalGuards?.history),
-        ci: {
-            create: pick(DEFAULT_CONFIG.guards.ci.create, projectGuards?.ci?.create, globalGuards?.ci?.create),
-            run: pick(DEFAULT_CONFIG.guards.ci.run, projectGuards?.ci?.run, globalGuards?.ci?.run),
-        },
-        expensiveTests: {
-            maxTokens: pick(DEFAULT_CONFIG.guards.expensiveTests.maxTokens, projectGuards?.expensiveTests?.maxTokens, globalGuards?.expensiveTests?.maxTokens),
-            patterns: pick(DEFAULT_CONFIG.guards.expensiveTests.patterns, projectGuards?.expensiveTests?.patterns, globalGuards?.expensiveTests?.patterns),
-        },
-    };
-}
 /** Project-over-global merge of the advance (conductor) knobs (feature 62).
  *  Absent from the result when neither scope declares any — the resolved
  *  shape of pre-62 configs is byte-stable. */

package/dist/config/schema.js

@@ -21,7 +21,6 @@ const ROOT_KEYS = new Set([
     "profileOrder",
     "profileFallback",
     "memory",
-    "guards",
 ]);
 const ROUTE_KEYS = new Set(["model", "thinking"]);
 const COMMAND_NAME = /^[a-z0-9][a-z0-9._-]*$/u;
@@ -333,7 +332,7 @@ function validateConfig(value) {
         if (!ROOT_KEYS.has(key)) {
             issues.push({
                 path: `$.${displayKey(key)}`,
-                message: `unknown config key "${key}" (allowed: default, commands, onUnavailableRoute, onSettle, pathProtection, advance, recommendedModels, profiles, profileOrder, profileFallback, memory, guards)`,
+                message: `unknown config key "${key}" (allowed: default, commands, onUnavailableRoute, onSettle, pathProtection, advance, recommendedModels, profiles, profileOrder, profileFallback, memory)`,
             });
         }
     }
@@ -408,11 +407,6 @@ function validateConfig(value) {
         if (memory)
             config.memory = memory;
     }
-    if (value.guards !== undefined) {
-        const guards = checkGuards(value.guards, "$.guards", issues);
-        if (guards)
-            config.guards = guards;
-    }
     if (value.profiles !== undefined) {
         if (!isRecord(value.profiles)) {
             issues.push({ path: "$.profiles", message: "must be an object mapping profile names to profile definitions" });
@@ -472,102 +466,6 @@ function checkMemory(value, path, issues) {
     }
     return unknown ? undefined : out;
 }
-/** Strict validator for the `guards` block. Everything absent stays off. */
-function checkGuards(value, path, issues) {
-    if (!isRecord(value)) {
-        issues.push({ path, message: `must be a JSON object, got ${describe(value)}` });
-        return undefined;
-    }
-    const out = {};
-    for (const key of ["merge", "history"]) {
-        if (value[key] !== undefined) {
-            if (typeof value[key] !== "boolean") {
-                issues.push({ path: `${path}.${key}`, message: `must be a boolean, got ${describe(value[key])}` });
-            }
-            else {
-                out[key] = value[key];
-            }
-        }
-    }
-    if (value.ci !== undefined) {
-        const ciPath = `${path}.ci`;
-        if (!isRecord(value.ci)) {
-            issues.push({ path: ciPath, message: `must be a JSON object, got ${describe(value.ci)}` });
-        }
-        else {
-            const ci = {};
-            for (const key of ["create", "run"]) {
-                if (value.ci[key] !== undefined) {
-                    if (typeof value.ci[key] !== "boolean") {
-                        issues.push({ path: `${ciPath}.${key}`, message: `must be a boolean, got ${describe(value.ci[key])}` });
-                    }
-                    else {
-                        ci[key] = value.ci[key];
-                    }
-                }
-            }
-            for (const key of Object.keys(value.ci)) {
-                if (key !== "create" && key !== "run") {
-                    issues.push({ path: `${ciPath}.${displayKey(key)}`, message: `unknown ci key "${key}" (allowed: create, run)` });
-                }
-            }
-            out.ci = ci;
-        }
-    }
-    if (value.expensiveTests !== undefined) {
-        out.expensiveTests = checkExpensiveTests(value.expensiveTests, `${path}.expensiveTests`, issues);
-    }
-    for (const key of Object.keys(value)) {
-        if (key !== "merge" && key !== "history" && key !== "ci" && key !== "expensiveTests") {
-            issues.push({ path: `${path}.${displayKey(key)}`, message: `unknown guards key "${key}" (allowed: merge, history, ci, expensiveTests)` });
-        }
-    }
-    return out;
-}
-function checkExpensiveTests(value, path, issues) {
-    if (!isRecord(value)) {
-        issues.push({ path, message: `must be a JSON object, got ${describe(value)}` });
-        return undefined;
-    }
-    const out = {};
-    if (value.maxTokens !== undefined) {
-        if (typeof value.maxTokens !== "number" || !Number.isInteger(value.maxTokens) || value.maxTokens < 0) {
-            issues.push({ path: `${path}.maxTokens`, message: `must be a non-negative integer, got ${describe(value.maxTokens)}` });
-        }
-        else {
-            out.maxTokens = value.maxTokens;
-        }
-    }
-    if (value.patterns !== undefined) {
-        if (!Array.isArray(value.patterns)) {
-            issues.push({ path: `${path}.patterns`, message: `must be an array, got ${describe(value.patterns)}` });
-        }
-        else {
-            const patterns = [];
-            value.patterns.forEach((entry, index) => {
-                const entryPath = `${path}.patterns[${index}]`;
-                if (!isRecord(entry) || typeof entry.match !== "string" || entry.match === "") {
-                    issues.push({ path: entryPath, message: `must be an object with a non-empty string "match", got ${describe(entry)}` });
-                    return;
-                }
-                if (typeof entry.tokens !== "number" || !Number.isInteger(entry.tokens) || entry.tokens < 0) {
-                    issues.push({ path: `${entryPath}.tokens`, message: `must be a non-negative integer, got ${describe(entry.tokens)}` });
-                    return;
-                }
-                try {
-                    new RegExp(entry.match, "u");
-                }
-                catch {
-                    issues.push({ path: `${entryPath}.match`, message: `not a valid regular expression: ${entry.match}` });
-                    return;
-                }
-                patterns.push({ match: entry.match, tokens: entry.tokens });
-            });
-            out.patterns = patterns;
-        }
-    }
-    return out;
-}
 export function parseConfigFile(text) {
     if (text.trim() === "")
         return { ok: true, config: {} };

package/dist/config/types.d.ts

@@ -78,9 +78,6 @@ export interface ConfigFile {
     /** Feature 66 (AC3/D3): the memory-substrate consent surface — Engram's MCP
      *  registration is ask-first, so nothing is provisioned unless this says so. */
     memory?: MemoryConfigFile;
-    /** Tool-call guards (owner-gated merges, history, CI, expensive tests).
-     *  Everything absent stays off. */
-    guards?: GuardsConfigFile;
     /** Named user profiles keyed by profile name (feature 63, AC5). */
     profiles?: Record<string, ProfileFile>;
     /** Ordered list of profile names to probe; empty means ["default"] only
@@ -108,61 +105,6 @@ export interface MemoryConfigFile {
 export interface MemoryConfig {
     engram: boolean;
 }
-/**
- * One tool-call guard, as an operator WRITES it (this repository's working
- * rules, made mechanical; every other project gets none of it unless it
- * configures it). Each guard ships disabled — an absent key is OFF.
- *
- *   merge           every direct merge route is owner-only: `git merge`,
- *                   `gh pr merge`, and `git pull`'s merge form.
- *   history         pushes are decided by asking git (`git push --dry-run`):
- *                   a forced update, a ref delete or a push to `main` is
- *                   declined — one mechanism covering every flag spelling and
- *                   git alias.
- *   ci              CI is owner-gated: creating workflow files and triggering
- *                   workflow runs are blocked.
- *   expensiveTests  commands matching a configured pattern are estimated in
- *                   tokens; above `maxTokens` they are blocked. `tokens: 0`
- *                   blocks every match regardless of estimate.
- *
- * The only way through a guard is the explicit per-command token — the
- * command's first word — after an owner authorization in the same turn:
- * `AW_ALLOW=merge`, `AW_ALLOW=force`, `AW_ALLOW=ci`, `AW_ALLOW=cost`.
- */
-export interface GuardsConfigFile {
-    merge?: boolean;
-    history?: boolean;
-    ci?: GuardsCiFile;
-    expensiveTests?: GuardsExpensiveTestsFile;
-}
-export interface GuardsCiFile {
-    create?: boolean;
-    run?: boolean;
-}
-export interface GuardsExpensiveTestsFile {
-    /** Estimated-token ceiling; a match above it is blocked. `0` (default)
-     *  blocks every match regardless of estimate. */
-    maxTokens?: number;
-    /** Command patterns (regex source, `u` flag) and their estimated cost. */
-    patterns?: GuardsCostPattern[];
-}
-export interface GuardsCostPattern {
-    match: string;
-    tokens: number;
-}
-/** What the extension READS: every guard knob resolved. */
-export interface GuardsConfig {
-    merge: boolean;
-    history: boolean;
-    ci: {
-        create: boolean;
-        run: boolean;
-    };
-    expensiveTests: {
-        maxTokens: number;
-        patterns: GuardsCostPattern[];
-    };
-}
 export interface ConfigIssue {
     path: string;
     message: string;
@@ -191,8 +133,6 @@ export interface EffectiveConfig {
     profileFallback: ProfileFallbackConfig;
     /** Feature 66: the memory-substrate consent surface. */
     memory: MemoryConfig;
-    /** The effective tool-call guards (all off unless a config file enables them). */
-    guards: GuardsConfig;
     /** Feature 63: declaredness of the implicit `default` profile. */
     declared: {
         default: RouteDeclaration;

package/dist/extension/factory.d.ts

@@ -2,10 +2,6 @@ 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 { historyGuard } from "./history-guard.js";
-import { ciGuard } from "./ci-guard.js";
-import { costGuard } from "./cost-guard.js";
 import type { ExtensionSurface, InvocationContext, ModelRef, RoutingControls } from "../routing/types.js";
 import type { HintStore } from "../routing/state.js";
 /**
@@ -58,18 +54,12 @@ 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, the owner-gated tool guards (merge,
-     * history, CI, cost — all config-gated, all off unless a project enables
-     * them), 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).
+     * 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).
      */
     guards: {
         receiptGuard: typeof receiptGuard;
-        mergeGuard: typeof mergeGuard;
-        historyGuard: typeof historyGuard;
-        ciGuard: typeof ciGuard;
-        costGuard: typeof costGuard;
         dirtyWorktreeWarning: typeof dirtyWorktreeWarning;
     };
 }

package/dist/extension/factory.js

@@ -2,10 +2,6 @@ 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 { historyGuard } from "./history-guard.js";
-import { ciGuard } from "./ci-guard.js";
-import { costGuard } from "./cost-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";
@@ -82,5 +78,5 @@ export function createExtension(deps) {
         description: "Show and configure per-command model routing",
         handler: settingsHandler,
     });
-    return { router, catalogue, guards: { receiptGuard, mergeGuard, historyGuard, ciGuard, costGuard, dirtyWorktreeWarning } };
+    return { router, catalogue, guards: { receiptGuard, dirtyWorktreeWarning } };
 }

package/dist/extension/index.js

@@ -296,32 +296,8 @@ 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.
-    //
-    // 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 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "4.10.0",
+  "version": "5.0.0-canary.20261102.1",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",
@@ -58,11 +58,11 @@
     "@earendil-works/pi-tui": "*"
   },
   "dependencies": {
-    "@gtrabanco/agentic-workflow": "4.10.0",
-    "@gtrabanco/agentic-workflow-schema": "4.10.0"
+    "@gtrabanco/agentic-workflow": "5.0.0-canary.20261102.1",
+    "@gtrabanco/agentic-workflow-schema": "5.0.0-canary.20261102.1"
   },
   "devDependencies": {
-    "@types/node": "24.13.3",
+    "@types/node": "26.6.6",
     "typescript": "7"
   }
 }

package/skills/execute-phase/SKILL.md

@@ -227,8 +227,8 @@ the full accumulated diff. On gate red at any step: repair that step (up to
 `--max-attempts`), then continue the loop. The close-out is part of the last
 step's completion: open the PR on `main` with `Closes #N`, write `- PR: <url>`
 into References, and settle the index row with `agentic-workflow roadmap
-<index> rowUpsert '<json>'` (`docs/features/ROADMAP.md`; a fix unit edits its
-`docs/fix/README.md` status cell — no `NN` column, no `rowUpsert`).
+<index> rowUpsert '<json>'` (`docs/ROADMAP.md`; a fix unit edits its row in that
+document's `## Fixes` table — no `NN` column, no `rowUpsert`).
 `bun scripts/roadmap-settle.mjs` exits 0 (#316).
 Terminal:
 

package/skills/execute-phase/references/PREFLIGHT.md

@@ -69,8 +69,8 @@ appending to the unit doc's Evidence section.
 
 ### Own-status precondition (runs after the dependency closure is met, still before any edit)
 
-Read the unit doc's status from the roadmap (the five-state machine —
-`docs/features/ROADMAP.md` → Status legend):
+Read the unit doc's status from the location index (the five-state machine —
+`docs/ROADMAP.md` → Status legend):
 
 1. **`idea`** (or no triage block in the unit doc) → STOP, before any edit:
 

package/skills/init-workspace/SKILL.md

@@ -65,7 +65,8 @@ Inspect the target dir (`[target-dir]`, default cwd) before touching anything:
 - An existing **agent guide** (`AGENTS.md`, or a legacy `CLAUDE.md`), `docs/`,
   `.github/`? If so, **do not clobber** — check first whether it's an
   **agentic-workflow scaffold** (marker: an agent guide present *and* either
-  `docs/features/ROADMAP.md` or a `docs/workflow/` dir). If both markers are
+  `docs/ROADMAP.md` — or the pre-319 `docs/features/ROADMAP.md` — or a
+  `docs/workflow/` dir). If both markers are
   present, offer **upgrade** as the default action, alongside merge /
   adapt-in-place / abort — see **Upgrade mode** below. If an agent guide or
   `docs/` exists but the markers are absent (a foreign scaffold), stay in
@@ -166,11 +167,17 @@ loads exactly upgrade and skips bootstrap plus portability.
 
 ## Unit document conventions (the adaptive lane)
 
-The adaptive lane (feature 61) replaces the fixed pipeline with a single-unit-
-document model. Every NEW unit produces one `SPEC.md` under
-`docs/features/<NN>-<slug>/` with 14 sections: Objective, Why, User outcome, Acceptance criteria, Impact,
-Non-goals, Future cost, Applicable tests, Known pre-existing issues, Tasks,
-Evidence, Progress log, Next, References.
+The adaptive lane replaces the fixed pipeline with a single-unit-document model.
+Every NEW unit produces one `SPEC.md` under `docs/features/<NN>-<slug>/`, cut in
+the **`spec-by-reference`** shape the template ships: `Specs` (numbered `S#`, each
+quoting the requester's words verbatim), Impact, Non-goals, Future cost,
+Applicable tests, Known pre-existing issues, `Tasks` (each bullet linked to the
+`S#` it delivers), `Findings` (OPEN rows only), `Log` (append-only; `L1` is the
+request verbatim), Next, References. A unit opened before this shape keeps the
+legacy 14-section shape — Objective, Why, User outcome, Acceptance criteria,
+Impact, Non-goals, Future cost, Applicable tests, Known pre-existing issues,
+Tasks, Evidence, Progress log, Next, References — and is never rewritten to
+migrate.
 
 Conventions written into the project's AGENTS.md:
 
@@ -188,8 +195,8 @@ Conventions written into the project's AGENTS.md:
 
 These are written by bootstrap (fresh) and upgrade mode (additive-only for pre-
 lane installs). A pre-lane project gets only: the lane conventions section in
-AGENTS.md, the unit doc template under `docs/features/_TEMPLATE/`, and the
-docs-map row for the unit doc.
+AGENTS.md, the unit doc templates under `docs/features/_TEMPLATE/` and
+`docs/fix/_TEMPLATE/`, and the docs-map rows for them.
 
 ## Normalized Repository State
 

package/skills/init-workspace/references/BOOTSTRAP_WRITE.md

@@ -4,10 +4,11 @@
    the documentation map rows, architecture); write the **adaptive lane
    conventions** (unit document, triage, catalog steps, guards, evidence rows,
    dated progress log, closed commit format `type(scope): description`); keep
-   the `features/_TEMPLATE` + `ROADMAP`, the `fix/_TEMPLATE` + `README`, and
-   the `.github/` templates; keep `.agentic-workflow/hooks/` and activate only
-   the adapters explicitly accepted in the interview; prune unused doc folders
-   and map rows. Leave honest placeholders where the user hasn't decided — never
+   the documentation templates it ships — `features/_TEMPLATE` beside
+   `features/ROADMAP.md`, and `fix/_TEMPLATE` beside `fix/README.md` — and the
+   `.github/` templates; keep `.agentic-workflow/hooks/` and activate only the
+   adapters explicitly accepted in the interview; prune unused doc folders and
+   map rows. Leave honest placeholders where the user hasn't decided — never
    invent values.
 5. **Seed Normalized Repository State.** Copy
    `template/docs/workflow/REPOSITORY_STATE.md` to
@@ -21,9 +22,14 @@
    optional: an absent document means no project invariants are declared, not
    that the scaffold failed. If retained, add its documentation-map row and
    name the project's explicit architectural-decision authority.
-7. **Propagate the unit doc template.** Ensure
-   `docs/features/_TEMPLATE/SPEC.md` exists with all 14 sections sections.
-   This is the template used when creating new unit documents.
+7. **Propagate the unit doc templates.** Ensure both template folders exist and
+   are cut in the `spec-by-reference` shape the scaffold ships —
+   `docs/features/_TEMPLATE/SPEC.md` and `docs/fix/_TEMPLATE/SPEC.md` (`Specs`
+   with `S#` requirements, Impact, Non-goals, Future cost, Applicable tests,
+   Known pre-existing issues, `Tasks`, `Findings`, `Log`, Next, References).
+   These are the templates used when creating new unit documents; a unit opened
+   before this shape keeps the legacy 14-section shape and is never rewritten to
+   migrate.
 8. **Provision Serena — one consented question, then write.** Load
    [SERENA](SERENA.md) and ask its single consent question; one yes covers the
    tool install, the detected platform's MCP registration and the global trust

package/skills/init-workspace/references/UPGRADE.md

@@ -4,7 +4,7 @@ Entered when Step 0 finds an existing **agentic-workflow scaffold** (not a
 bare or foreign repo). Bootstrap mode (the Process section above) never
 engages here — upgrade mode reuses the same discovery + interview machinery,
 scoped to **only the blocks the current template has that this project
-lacks**. Nine ordered steps:
+lacks**. Ten ordered steps:
 
 1. **Locate the current template.** Fetch the current `template/` the same
    way bootstrap does — `npx degit gtrabanco/agentic-workflow/template <temp-dir>`
@@ -33,14 +33,34 @@ lacks**. Nine ordered steps:
    dated migration note so the proposal explains *why* the block exists and
    *what* it migrates. If `MIGRATION.md` is absent, proceed on the template
    diff alone and say so in the report — never block on a missing note.
-4. **Propose the adaptive lane conventions (feature 61 P11).** For pre-lane
+4. **Propose the consolidated location index (issue #319).** A project whose
+   roadmap still lives at `docs/features/ROADMAP.md`, or whose fix index is still
+   a standalone `docs/fix/README.md`, is offered the move **additively**:
+   `docs/ROADMAP.md` gained as a new file (the project's feature table plus a
+   `## Fixes` section built from its own fix index), the old path removed **only
+   after the new file is in place**, and the fix README reduced to the one-line
+   pointer stub the template ships. Never rewrite an edited roadmap: if the
+   project's table differs from the template's, carry the project's rows
+   verbatim and list the differences as residuals. **The read window is closed**
+   (`docs/workflow/MIGRATION.md`, 2026-10-30, decision D4): the old path is only
+   *detected* so this step can offer the move — a repository that still runs the
+   lane against it is refused with a `roadmap-moved` pointer, so propose the move
+   as the first thing to fix, never as an optional cleanup. A half-migrated tree
+   (canonical roadmap without a `## Fixes` table) still reads its standalone fix
+   index, so the fix table can be folded in a second pass.
+
+5. **Propose the adaptive lane conventions (feature 61 P11).** For pre-lane
    installs (before the fixed pipeline was retired), propose these missing
    blocks additively — **never clobber existing content**:
-   - The **unit document conventions** section in AGENTS.md (the 14-section
-     SPEC.md, triage-driven step selection, diff-size guard, evidence rows,
-     dated progress log, closed commit format `type(scope): description`).
-   - The **unit doc template** under `docs/features/_TEMPLATE/SPEC.md` if
-     absent — the same 14-section template used by new units.
+   - The **unit document conventions** section in AGENTS.md (the
+     `spec-by-reference` unit doc the template ships — `Specs` with `S#`
+     requirements, `Tasks`, `Findings`, `Log` — triage-driven step selection,
+     diff-size guard, evidence rows, dated progress log, closed commit format
+     `type(scope): description`).
+   - The **unit doc templates** under `docs/features/_TEMPLATE/SPEC.md` and
+     `docs/fix/_TEMPLATE/SPEC.md` if absent — the re-cut `spec-by-reference`
+     templates the scaffold ships. A pre-existing unit keeps the legacy
+     14-section shape and is never rewritten to migrate.
    - The **lane workflow doc** under `docs/workflow/` if absent: `FEATURE_WORKFLOW.md`
      (unit doc → triage → catalog steps → evidence → review → release),
      `ISSUE_WORKFLOW.md` (issues route through triage to the lane).
@@ -50,7 +70,7 @@ lacks**. Nine ordered steps:
    the project already answered** — a block that's already filled is skipped,
    not re-interviewed. The lane conventions are additive only: existing content
    is never rewritten, only new blocks are inserted where missing.
-5. **Write additively.** Insert accepted blocks, including a missing
+6. **Write additively.** Insert accepted blocks, including a missing
    `docs/workflow/REPOSITORY_STATE.md`; fill raw, still-placeholder
    blocks with the confirmed values. **Never rewrite a block the project has
    already tailored, and never delete anything** — a tailored block the
@@ -61,7 +81,7 @@ lacks**. Nine ordered steps:
    `path-protection.md` page are proposed from the template; an existing
    owner-written `path-policy.json` is never clobbered and is listed as a
    residual instead. Leave honest placeholders where the user skipped.
-6. **Retire the legacy `CLAUDE.md` — only with an explicit yes, never as a side
+7. **Retire the legacy `CLAUDE.md` — only with an explicit yes, never as a side
    effect.** Older releases of this workflow wrote the guide as `CLAUDE.md`;
    current ones write `AGENTS.md`, and current Claude Code reads `AGENTS.md`.
    When the project has a `CLAUDE.md`, three ordered moves — never skip (a):
@@ -83,7 +103,7 @@ lacks**. Nine ordered steps:
 
    This step is the only writer of `CLAUDE.md` in upgrade mode, and it is never
    reached without the answer from (b).
-7. **Seed missing urgency labels, additively (feature 15).** Independent of
+8. **Seed missing urgency labels, additively (feature 15).** Independent of
    the agent-guide/`docs/` block diff above (this is forge-repo state, not a
    doc block): check whether the target repo already has the `urgent` and
    `fix-next` labels (`gh label list`); create whichever is missing with the
@@ -92,7 +112,7 @@ lacks**. Nine ordered steps:
    rule as the doc blocks; a pre-existing `urgent`/`fix-next` label the
    project recolored or redescribed is left exactly as-is).
 
-8. **Provision Serena, additively only (Refs #219).** Load
+9. **Provision Serena, additively only (Refs #219).** Load
    [SERENA](SERENA.md) and ask its single consent question — the tool install,
    the detected platform's MCP registration and the global trust append all ride
    on that one yes, and a refusal writes nothing. Then append the `.gitignore`
@@ -101,7 +121,7 @@ lacks**. Nine ordered steps:
    the health check, and render the fixed provisioning report. This step is
    additive-only; it never rewrites or deletes, consistent with upgrade mode's
    rule.
-9. **Report + hand off.** Summarize blocks added, filled, and skipped
+10. **Report + hand off.** Summarize blocks added, filled, and skipped
    (residuals), the legacy `CLAUDE.md` outcome (folded items and removed, or kept
    with the reason), the urgency labels seeded (or already present), then print the
    recommendation to run `product-audit` next to see which newly-available
@@ -121,12 +141,12 @@ lacks**. Nine ordered steps:
 - **A block the project already tailored.** If the current template also
   changed a block the project customized, **do not merge, diff-patch, or
   overwrite it** — leave it exactly as the project has it and list it as a
-  residual in the report (step 5's never-clobber invariant). The user decides
+  residual in the report (step 6's never-clobber invariant). The user decides
   separately, via an explicit bootstrap adapt-in-place run, whether to
   re-tailor it.
 - **Bootstrap stays unchanged on a bare or foreign repo.** If Step 0's
   scaffold markers (an agent guide — `AGENTS.md` or a legacy `CLAUDE.md` — plus
-  `docs/features/ROADMAP.md` or
+  `docs/ROADMAP.md`, a pre-319 `docs/features/ROADMAP.md`, or
   `docs/workflow/`) are absent — no repo, an empty repo, or a guide
   that isn't this workflow's — upgrade mode never engages; the existing
   bootstrap Process (merge/adapt/abort) runs exactly as before this mode was

package/skills/phase-contract/SKILL.md

@@ -72,7 +72,7 @@ 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 |
+| **unit doc** | the unit doc's `## Tasks` section | one `P<n> — <task> (validator: <command> <outcome>)` bullet per phase, optionally carrying the executed-phase tick mark (`- [x] P<n> — …`; the tick is state, never a second 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

package/skills/pre-execution-review/references/LEDGERS.md

@@ -170,7 +170,7 @@ planning-findings | docs/features/<NN>-<slug>/planning-findings.md · docs/fix/<
 progress | docs/features/<NN>-<slug>/SPEC.md · docs/fix/<issue>-<topic>/SPEC.md | unit-lane:progress-entries + execute-phase:phase-entries + execute-phase:gate-rejection-traces | none | none | bun test scripts/pre-execution-sensor.test.mjs
 known-issues | docs/features/<NN>-<slug>/known-issues.md · docs/fix/<issue>-<topic>/known-issues.md | unit-lane:known-entries + execute-phase:blocker-entries-and-status | none | none | bun test scripts/ledger-ownership.test.mjs
 decisions | docs/features/<NN>-<slug>/decisions.md · docs/fix/<issue>-<topic>/decisions.md | unit-lane:decisions + execute-phase:phase-decisions + human-owner:ratified-verdicts | none | none | bun test scripts/ledger-ownership.test.mjs
-roadmap | docs/features/ROADMAP.md · docs/fix/README.md | unit-lane:row-registration + execute-phase:status-and-pr-link + audit-docs:low-risk-row-repair | none | none | bun test scripts/bounded-delivery-loops.test.mjs
+roadmap | docs/ROADMAP.md | unit-lane:row-registration + execute-phase:status-and-pr-link + audit-docs:low-risk-row-repair | none | none | bun test scripts/bounded-delivery-loops.test.mjs
 acceptance-manifest | docs/features/<NN>-<slug>/ACCEPTANCE.md · docs/fix/<issue>-<topic>/ACCEPTANCE.md | unit-lane:acceptance-freeze + human-owner:approved-amendment | none | none | git hash-object docs/features/<NN>-<slug>/ACCEPTANCE.md (legacy pre-feature 61) · sed -n '/^## Acceptance criteria/,/^## /p' <unit>/SPEC.md then git hash-object --stdin (unit doc era, post-feature 61)
 # no-script-writer: SPEC.md · PLAN.md · TASKS.md · CHECKLIST.md · testing.md · architecture-notes.md · planning-evidence.md · planning-obligations.md · delegated-evidence.md
 ```

package/skills/pre-execution-review/references/POLICY.md

@@ -136,8 +136,8 @@ a count and never waives a finding.
   `execute-phase`, and a `PLAN-REVIEW-PASS` never certifies the Product half.
 - A gate answer from a roadmap row's status. Gates read receipts only;
   roadmap rows are labels and never answer a gate. `done` means built + PR open
-  with the human merge pending (`docs/features/ROADMAP.md` § Status legend;
-  `docs/fix/README.md` § Status legend), so it never satisfies or suppresses a
+  with the human merge pending (`docs/ROADMAP.md` § Status legend and § Fix
+  status legend), so it never satisfies or suppresses a
   pre-execution/verification gate, never retires the obligation to re-derive a
   receipt, and never lets a reviewer or consumer report a unit closed while its
   PR is unmerged. The complement of §5's "no verdict *from* a status" — and the