@gtrabanco/pi-agentic-workflow 0.4.1 → 0.5.0

package/dist/routing/catalogue.js

@@ -34,7 +34,31 @@ export function readSkillMeta(text, dir) {
         if (colon === -1)
             continue;
         const key = line.slice(0, colon).trim();
-        const value = line.slice(colon + 1).trim().replace(/^["']|["']$/gu, "");
+        const rawValue = line.slice(colon + 1).trim();
+        const value = rawValue.replace(/^["']|["']$/gu, "");
+        // YAML block scalars: `description: >` (folded) / `description: |` (literal)
+        // carry their content on the following indented lines, not inline. Collect
+        // those continuation lines (they never start a top-level `key: value` line)
+        // and advance the loop past them. ">" is not a description, so the old
+        // line-oriented reader storing `>` is the bug (#165).
+        if (key === "description" && (value === ">" || value === "|")) {
+            const folded = value === ">";
+            const collected = [];
+            let cursor = index + 1;
+            for (; cursor < lines.length; cursor += 1) {
+                const next = lines[cursor];
+                if (next.trim() === "---")
+                    break;
+                // A non-empty, non-indented line starts the next top-level key.
+                if (next !== "" && !/^[ \t]/u.test(next))
+                    break;
+                collected.push(next);
+            }
+            meta.description = buildBlockScalar(collected, folded);
+            // Outer loop += 1 moves past the last consumed continuation line.
+            index = cursor - 1;
+            continue;
+        }
         if (key === "name" && value !== "")
             meta.name = value;
         else if (key === "description" && value !== "")
@@ -44,6 +68,40 @@ export function readSkillMeta(text, dir) {
     }
     return meta;
 }
+/**
+ * Assemble a YAML block scalar from its collected, indented continuation lines.
+ *
+ * Strip the common leading indentation, then: folded (`>`) joins non-blank
+ * lines into a single space-separated string (blank lines become page breaks);
+ * literal (`|`) preserves the line breaks. Both are trimmed of outer blank
+ * whitespace so the value matches the frontmatter's intended text.
+ */
+function buildBlockScalar(lines, folded) {
+    const nonEmpty = lines.filter((line) => line.length > 0);
+    const indent = nonEmpty.reduce((min, line) => {
+        const width = /^[ \t]*/u.exec(line)[0].length;
+        return Math.min(min, width);
+    }, Number.POSITIVE_INFINITY);
+    if (!Number.isFinite(indent))
+        return "";
+    const unindented = lines.map((line) => (line.length === 0 ? "" : line.slice(indent)));
+    if (!folded)
+        return unindented.join("\n").trim();
+    const parts = [];
+    let pendingBreak = false;
+    for (const raw of unindented) {
+        const line = raw.trimEnd();
+        if (line === "") {
+            pendingBreak = true;
+            continue;
+        }
+        if (pendingBreak && parts.length > 0)
+            parts.push("\n");
+        pendingBreak = false;
+        parts.push(line);
+    }
+    return parts.join(" ").replace(/ \n/g, "\n").trim();
+}
 /**
  * Read a bundled skills directory. A duplicate `name:` is reported instead of
  * silently shadowing an alias: two skills claiming one command is a packaging
@@ -54,7 +112,14 @@ export function readCatalogue(skillsDir, readFile = (p) => readFileSync(p, "utf8
     const invocable = [];
     const issues = [];
     const taken = new Map();
-    for (const dir of readdirSync(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory())) {
+    // Iterate directories in a stable order: readdir order is filesystem-dependent
+    // (bun and node return different orders for the same directory), and the
+    // duplicate-name rule is "first owner claims the command". Sorting makes that
+    // owner deterministic across runtimes and platforms.
+    const dirs = readdirSync(skillsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .sort((left, right) => left.name.localeCompare(right.name));
+    for (const dir of dirs) {
         let meta;
         try {
             meta = readSkillMeta(readFile(join(skillsDir, dir.name, SKILL_FILE)), dir.name);

package/package.json

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

package/skills/execute-phase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: execute-phase
 user-invocable: true
-version: 4.2.0
+version: 4.3.0
 argument-hint: <NN> [P<k>] | --fix <n> [P<k>] | [--max-attempts N] [--force]
 allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
@@ -54,6 +54,11 @@ Load and verify the **canonical** [Turn contract](.claude/skills/orchestration-e
   unit). Missing, stale, or wrong-stage stops the turn with the gate block; this is
   the one preflight gate `--force` does not reach — the block, no-forgery and legacy
   rules live in [pre-execution gate](references/PRE_EXECUTION_GATE.md).
+- **Pre-write discovery before any repository write** — after the read-only gates
+  and before branch creation, planning commit, or source/test edit, settle the
+  mapper contract (`implementation-discovery`). It answers the seven evidence
+  questions, emits the fixed compact map, and routes `READY | REPLAN |
+  NEEDS-DESIGN | BLOCKED`; only `READY` authorizes the first write.
 
 ## Context budget (hard rule — context is repaid every turn)
 
@@ -76,6 +81,10 @@ the listed one-hop route resource immediately before its step.
 1. Every invocation: consume [verification contract](<../verification-contract/SKILL.md>),
    read/run [preflight gates](references/PREFLIGHT.md), and stop on a contracted
    blocker before editing. This route owns NRS and Architectural invariants gates.
+   After the read-only pre-execution gate and before any branch/planning/source
+   write, load and settle the pre-write mapper
+   [`implementation-discovery`](<../implementation-discovery/SKILL.md>) — it emits
+   the fixed map and routes READY | REPLAN | NEEDS-DESIGN | BLOCKED.
 2. Without explicit `P<n>`, read [unit loop](references/UNIT_LOOP.md), then
    [execution contract](references/EXECUTION_CONTRACT.md), then exactly one
    workflow: [feature](references/WORKFLOWS_FEATURE.md),

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

@@ -125,8 +125,11 @@ gate block, and **`--force` never reaches this gate** — it overrides ordering
 the user may re-order, not a verdict only a reviewer can produce. Fix units run the
 same check on their own receipt (`/review-plan fix-<N>`). Legacy `planned`/`in-progress`
 units follow the adoption route. The slot immediately after this gate and before the
-first write is reserved for feature 29's bounded implementation discovery — do not
-implement or imitate it here. Full rule, block text, no-forgery and legacy detail:
+first write is owned by the pre-write mapper contract — load
+[`implementation-discovery`](<../implementation-discovery/SKILL.md>) and settle it
+before any branch/planning/source write; it routes READY | REPLAN | NEEDS-DESIGN
+| BLOCKED and is the only contract allowed to confirm the map here. Full rule,
+block text, no-forgery and legacy detail:
 [pre-execution gate](PRE_EXECUTION_GATE.md).
 
 ## Acceptance-manifest gate (after dependency/own-status, before phase-lint)

package/skills/implementation-discovery/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: implementation-discovery
+user-invocable: false
+version: 1.1.0
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal contract: the single owner of the bounded pre-write implementation
+  discovery step. One read-only mapper that closes seven evidence questions,
+  emits one fixed compact map, and routes READY | REPLAN | NEEDS-DESIGN |
+  BLOCKED before any branch, planning, or source write. Consumed only by
+  execute-phase on the pre-write route. Not a menu entry.
+---
+
+# Implementation Discovery (internal)
+
+The one authoritative owner of the bounded, read-only pre-write mapper consumed
+by `execute-phase`. A phase does not touch the repository until this step has
+closed its questions and said `READY`. Nothing else may define what a valid
+pre-write discovery pass is.
+
+## When to use
+
+- `execute-phase` — before any branch/planning/source write, after the read-only
+  dependency/status/acceptance/phase/feature-28 receipt checks.
+- The step runs only on the pre-write route; it is never a general-purpose
+  orientation pass and never a substitute for planning.
+
+## Inputs (exact, only these)
+
+The mapper receives only:
+
+- the governing SPEC/fix obligations for the current phase;
+- the current feature-28 SPEC and Plan receipt digests;
+- the phase-relevant rows from frozen planning evidence, with source revision,
+  affected decision/obligation, freshness, and declared unknowns;
+- the phase fingerprint, ordered tasks, acceptance/obligation ids, and the last
+  progress receipt;
+- source HEAD plus clean-source / allowed-planning-path evidence;
+- applicable NRS / decision / invariant evidence;
+- the repository discovery tools available in this environment.
+
+## Advisory locators
+
+Semantic/symbol navigation and Engram/memory tools are optional adapters that may
+locate evidence faster; they are never authority. Direct repository/Git/search/
+read/test fallback must satisfy the identical evidence contract, and only
+repository bytes answer a map field. The tool that found a citation does not
+excuse a missing `path:line` or a contradictory claim.
+
+## Seven evidence questions
+
+Every pass must answer — each answer citing repository-relative `path:line`,
+symbol, or test plus exact source revision / content identity:
+
+1. Which entry points and public/internal interfaces own current behaviour?
+2. Which callers, adapters, roles, compatibility surfaces, and failure paths
+   can this phase affect?
+3. Which helpers, patterns, decisions, and invariants constrain the change?
+4. Which tests, fixtures, probes, and production-like scenarios establish
+   current behaviour?
+5. Which exact writes are expected, and which reviewed obligation does each
+   serve?
+6. Which carried planning-evidence claims and Plan assumptions are directly
+   confirmed, refined, stale, missing, or contradicted by source?
+7. Which relevant unknowns remain, who owns them, and what evidence resolves
+   them?
+
+The mapper records conclusions, not every search. Repeating a search/read
+requires a new question, changed source, or insufficient cited evidence;
+otherwise it stops (no-progress).
+
+## Inline and fresh routing
+
+**Inline** is permitted only when behaviour is localized/familiar, targeted
+evidence answers every question, no public/persistence/security/recovery/
+compatibility boundary may change, and the executor can finish the map before
+writing.
+
+**A fresh read-only mapper** is required for cross-module/layer or unfamiliar
+work, public/persistence/security/recovery/compatibility impact, competing
+project patterns, an unproven material Plan assumption, prior failed
+attempts/review bias, or any case where editing would begin before the map
+closes. Same-model fresh context is useful but is not model diversity. Manual
+sequential fresh conversations are the portable fallback.
+
+No file-count threshold participates in the route or the verdict.
+
+## Fixed implementation map
+
+```text
+IMPLEMENTATION MAP — unit-id phase-id
+Map revision: opaque single-consumption id
+Source identity: HEAD + clean-source proof + cited-evidence manifest digest
+Authority: SPEC receipt + Plan receipt + phase fingerprint
+Planning evidence: carried row ids + current confirmation/refinement/conflict
+Obligations: ordered acceptance/fix/obligation ids
+Entry points: path:line or symbol + role + exact evidence
+Affected surfaces: callers/adapters/roles/compatibility/failure paths + evidence
+Current behaviour: evidence-backed summary
+Reuse and constraints: helper/pattern/decision/invariant/fixture + evidence
+Expected writes: ordered path + obligation served + reason
+Validation: falsification probe + TDD target + phase gate
+Plan assumptions: confirmed items + evidence
+Contradictions: none or exact Plan/source conflict
+Unknowns: none or exact missing fact + owner + resolution evidence
+Decision: READY | REPLAN | NEEDS-DESIGN | BLOCKED
+```
+
+## Verdicts
+
+`READY` requires every field, question, and owned obligation covered, no
+material contradiction/unknown, an observed falsification probe, and expected
+writes inside phase authority. It also requires every carried planning-evidence
+row to be confirmed or narrowly refined.
+
+`REPLAN` means source disproves Engineering assumptions while Product remains
+stable, or Plan-level topology/architecture/obligation/validator evidence is
+absent.
+
+`NEEDS-DESIGN` means Product, acceptance, authority, or architecture intent is
+missing or conflicting.
+
+`BLOCKED` names evidence that cannot currently be obtained.
+
+No other verdict exists.
+
+## Routes and upstream owners
+
+A verdict routes, it never repairs. Missing/contradicted Plan-level topology,
+architecture, obligations, validators, or assumptions return to
+`plan-feature`/`plan-fix` plus a fresh `review-plan`. Product/acceptance/
+authority/architecture gaps return to `design-feature` then `review-spec`. A
+verdict with unavailable evidence is one exact `BLOCKED` prerequisite. Mapping
+does not decide code correctness — candidate review, verification, and audit
+authority are unchanged, and a second repair/re-review cycle inherits feature
+28's `CONVERGENCE-ANOMALY` diagnosis.
+
+Source-local findings stay local; Plan/Product defects return upstream. A
+missing current-unit behaviour entailed by reviewed scope joins the obligation
+map and routes upstream; it is never a follow-up issue and never calls the
+forge.
+
+## Legacy and manual routes
+
+The portable fallback uses sequential fresh conversations with exact
+artifact/source bindings. It may not claim a machine receipt or a durable
+guarantee it cannot produce; it says plainly what was observed and what was
+not.
+
+## Early falsification
+
+Before READY, run the cheapest relevant read-only probe: a focused existing
+test, current parser/CLI output, public type/schema inspection, symbol callers,
+or an existing fixture. Record the command/query, the observed result, and the
+evidence. A failed probe informs REPLAN/NEEDS-DESIGN; unavailable high-risk
+evidence is BLOCKED, never rewritten as confident evidence. This does not
+replace TDD or later verification.
+
+## No-progress
+
+Conclusion once. Do not re-read or re-search to reconfirm the same conclusion
+without a new question, changed source, or insufficient cited evidence. On
+repetition, stop with `BLOCKED` and name what is still missing. Re-read is
+allowed only for a changed source revision, a new question, insufficient
+evidence, or a contradiction.
+
+## Read-only boundary
+
+The mapper reads; it may not write. It creates no forge issue, no committed
+map, no planning unit, no schema, no source edit, and no test edit. It emits the
+map and reuses `SkillOutcome v1`. A missing current-unit behaviour entailed by
+reviewed scope joins the obligation map and routes upstream; it is not a
+follow-up issue. Discovery never calls the forge.
+
+## Writer handoff
+
+The writer receives frozen phase authority plus the fixed compact map. It does
+not receive raw files, repeated summaries, raw planning discovery, raw
+exploration history, or the authoring conversation unless a cited claim cannot
+be interpreted without a focused excerpt. The map preserves the phase-relevant planning-evidence ids and
+their current confirmation. The writer may only touch expected paths /
+obligations; a newly discovered path or contradiction stops and remaps/routes
+rather than expanding silently.
+
+## Source identity
+
+Source identity is exact pre-map HEAD, proof that tracked/untracked changes
+outside the allowed planning paths are absent, an ordered manifest digest of
+every cited evidence path/content plus the current phase/receipt bindings, and
+an opaque `mappingRevisionId` created for this mapping event.
+
+## Preparation continuity
+
+After READY, deterministic setup may create the branch and commit only the
+already-reviewed planning paths. Before the first source/test edit the executor
+proves either HEAD is unchanged or the new commit is a direct descendant whose
+entire diff is the allowed planning set and whose authority/content digests
+match. Any other path, parent, receipt, phase, or evidence change invalidates
+the map and routes again.
+
+## Consumption and recovery
+
+READY is single-consumption: the first implementation write consumes it. A crash
+before the write may resume only after freshness/no-consumption proof. A crash
+after any partial write remaps current source during recovery. A new map
+revision plus changed Git causal identity prevents reuse after revert; direct
+out-of-protocol state manipulation cannot be claimed detectable without runtime
+history.

package/skills/pre-execution-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pre-execution-review
 user-invocable: false
-version: 1.7.0
+version: 2.0.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >

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

@@ -43,10 +43,17 @@ Rules the builder enforces and no caller may improvise around:
   Passing a fix unit's own SPEC bytes off as a parent is refused by the contract,
   because the field means "the Product review I descend from".
 - **Context rows are the authorities actually consulted**, each `present` with its
-  digest or `absent` with `null`: `roadmap-row`, `project-guide`,
-  `normalized-repository-state`, `architectural-invariants` (the *project's* declared
-  file — the portable workflow contract is not a project's rule set), plus
-  `governing-issue` and `dependency-unit` when the unit has them.
+  digest or `absent` with `null`: `project-guide`, `normalized-repository-state`,
+  `architectural-invariants` (the *project's* declared file — the portable workflow
+  contract is not a project's rule set), plus `governing-issue` and
+  `dependency-unit` when the unit has them. **The roadmap row is deliberately not
+  bound:** `ROADMAP.md` is every unit's shared lifecycle ledger — rows for other
+  units land while a plan is in flight, and the status machine's own sanctioned
+  writes (`planned` → `in-progress` at P1, `done` at PR open) must never invalidate
+  a recorded receipt. Its safety-relevant content is owned by gates that re-read it
+  live (the own-status gate, and the dependency gate's fingerprint over the SPEC
+  `Depends on:` line plus the closure roadmap rows); the unit's artifacts and the
+  authorities above stay bound.
 - **A snapshot digest is not a git blob id.** `git hash-object` stays the convention
   for the frozen `ACCEPTANCE.md` manifest receipt only; comparing it to a snapshot
   digest proves nothing and a sensor that does so is wrong, not cheap.

package/skills/review-spec/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-spec
 user-invocable: true
-version: 1.5.0
+version: 1.6.0
 argument-hint: <NN-slug | path/to/SPEC.md>
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/review-spec/references/CHECKS.md

@@ -27,7 +27,7 @@ A SPEC-stage snapshot is deliberately narrow:
 | `artifactRevisionId` | the author's current revision id from the handoff |
 | `artifacts` | **exactly one row**: `kind: spec`, `path` normalized repo-relative, `selector: spec-product-v1`, `byteLength`, lowercase SHA-256 `digest` |
 | `parentSpecSnapshotDigest` | `null` — a SPEC snapshot roots its own lineage |
-| `contexts` | each authoritative source actually consulted: `roadmap-row`, `governing-issue`, `normalized-repository-state`, `architectural-invariants`, `dependency-unit`, `project-guide` — `present` with its exact digest, or `absent` with `null` |
+| `contexts` | each authoritative source actually consulted: `governing-issue`, `normalized-repository-state`, `architectural-invariants`, `dependency-unit`, `project-guide` — `present` with its exact digest, or `absent` with `null`. The roadmap row is read as routing data and deliberately unbound: the shared `ROADMAP.md` ledger moves for reasons this unit never reviewed (other units' rows, the status machine's own sanctioned writes) |
 
 `spec-product-v1` selects the title, `## Goal`, `## Branch`, `## Size`,
 `## Dependencies`, the whole Product half, and `## Design status` — never the