@gtrabanco/pi-agentic-workflow 0.18.4 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.18.4",
+  "version": "0.19.0",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",
@@ -57,7 +57,7 @@
     "@earendil-works/pi-tui": "*"
   },
   "dependencies": {
-    "@gtrabanco/agentic-workflow": "0.1.1",
+    "@gtrabanco/agentic-workflow": "0.2.0",
     "@gtrabanco/agentic-workflow-schema": "4.5.0"
   },
   "devDependencies": {

package/skills/init-workspace/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: init-workspace
 user-invocable: true
-version: 3.2.0
+version: 3.3.0
 argument-hint: <target-dir>
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -109,6 +109,16 @@ loads exactly upgrade and skips bootstrap plus portability.
   is not listed (markdown/yaml/json are never auto-detected), and a listed
   server that fails to start must be removed (one failure disables every
   server in the project). Document verification is a script's job.
+- **Retrieval index scaffold and git hooks are consent-gated (AC22).** The
+  index surface — the committed `.agentic-workflow/index.json` config plus the
+  three freshness hooks (`post-merge`, `post-checkout`, `post-rewrite`, all
+  `index-sync.sh` installed into `.git/hooks/`) — is installed **only after an
+  explicit yes** to the question "install the doc retrieval index scaffold and
+  its git hooks?". Without consent: install nothing, record it as a residual
+  (the entry point still runs and builds its index on first query — the hooks
+  are only a freshness fast path), and never write `.git/hooks/` or the config
+  on a later visit without a fresh yes. The hooks are best-effort by contract
+  (`doc --sync --quiet`, always exit 0 — a fast path never breaks git).
 - **Never redefine the urgency label vocabulary here.** `skills/triage-issue
   /SKILL.md` is the sole owner of the `urgent`/`fix-next` names, colors, and
   apply rules — this skill only seeds those two labels into the repo; it never

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/product-audit/SKILL.md

@@ -2,7 +2,7 @@
 name: product-audit
 user-invocable: true
 disable-model-invocation: true
-version: 3.3.0
+version: 3.4.0
 metadata:
   opencode/autoinvoke: false
 argument-hint: <path-or-area> (optional — defaults to the whole product)
@@ -10,9 +10,12 @@ author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Audit the whole product across code, quality, process, docs, roadmap, and
-  tooling. Persist one severity-ranked, F-numbered report with proposals; never
-  fix or file work. Triggers: "product-audit", "audit the product", "full health
-  check", "are we product-ready", "CTO review".
+  tooling; it owns the repo-wide bug hunt, security research, and broken-version
+  investigation (scoped and budgeted per dimension, as distinct from
+  `review-change`'s change-scoped review). Persist one severity-ranked,
+  F-numbered report with proposals; never fix or file work. Triggers:
+  "product-audit", "audit the product", "full health check", "are we product-ready",
+  "CTO review".
 ---
 
 # Product Audit
@@ -38,6 +41,11 @@ first on purpose).
 - Periodically (every few features) or at a product-ready milestone.
 - When you want the broad, honest picture — quality, security, debt, docs, and
   roadmap — not the review of a single change (`review-change`) or PR (`audit-pr`).
+- **It owns the repo-wide sweep.** Open-ended, repository-wide bug hunting,
+  security research and broken-version investigation land **here** — scoped,
+  sampled and budgeted per dimension (state what you sampled). The same hunt
+  against one change is `review-change`'s job: neither skill absorbs the other's
+  scope.
 
 Unlike diff, PR, or docs-only reviews, this skill covers the whole product.
 

package/skills/review-change/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-change
 user-invocable: true
-version: 3.8.0
+version: 3.10.0
 argument-hint: <path-or-glob> [--adversarial N] [--synthesize]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -68,6 +68,32 @@ mapping candidate evidence.
 Default target is the **current change** (branch diff vs the default branch);
 accept a path/glob to widen or narrow. State the scope at the top of the report.
 
+## Review charter — dismantle the claim
+
+The workflow's job is to demonstrate that what works, works — **and works
+well**: programmatically, engineering-wise, decision-wise, and against user
+expectation. This review exists to **try to dismantle that claim**; if it
+survives the attempt, that survival *is* the review outcome. So:
+
+- **In-scope defects are this review's job — never “out of scope”.** A bug, a
+  security issue, or a guard skip inside the current feature's scope is a
+  `review-change` finding: a feature is not complete while it has one. The
+  reward is not delivery, it is meeting the acceptance criteria, adequate
+  engineering without over-engineering, meeting **other features' requirements**
+  (a page that needs auth verifies the session *and* the permission; a change to
+  another table that a requirement depends on stays in scope even if it “looks”
+  out of scope), and above all the user's expectation.
+- **Ask, don't infer — the whole expectation surface.** Where the plan, the diff
+  or the requirement leaves the user's expectation unclear, surface it as a
+  question in non-technical terms (a technical user asks for an app; a
+  non-technical user asks for “an app to measure my heart rate”) — never as an
+  assumed intent. This extends ask-don't-infer from acceptance criteria to every
+  expectation the change is judged against.
+- **Repo-wide hunting is not this review.** Open-ended bug hunting, security
+  research and broken-version investigation *across the repository* belong to
+  `product-audit`, where the sweep is scoped and budgeted; this review stays on
+  the change at hand.
+
 ## Step 0 — Discover the project & the change (always first)
 
 Per Workflow conventions + documentation map, decide axes from:
@@ -76,6 +102,12 @@ Per Workflow conventions + documentation map, decide axes from:
    and optional recorded platform skills (extras only).
 2. **Footprint:** what the diff touches (UI, API, infra, domain). An axis applies
    only when both project and footprint support it.
+3. **Prior findings (optional retrieval aid, never authoritative):** when the
+   index entry point exists, `agentic-workflow doc --query "<change topic>"
+   --json-only` may surface earlier findings, decisions and session-log entries
+   on the same surface before the passes run. A missing index, an absent entry
+   point, or an empty answer changes nothing — grep stays the exhaustive
+   fallback, and the index is never a decision authority.
 
 ## Applicability matrix (default; the project's docs refine it)
 

package/skills/triage-issue/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: triage-issue
 user-invocable: true
-version: 2.9.0
+version: 2.10.0
 argument-hint: <issue-number> [more issue numbers…] | <audit-id> F<k> [F<j>…] | --prioritize-now <unit> F<k> [F<j>…]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -57,7 +57,13 @@ first on purpose).
 
 Per the agent guide's **Workflow conventions** + **documentation map**, then read
 what THIS skill needs: the fix index (e.g. `docs/fix/README.md`) and fix SPEC
-template, and the roadmap. In review-finding mode, read the target unit's SPEC,
+template, and the roadmap. **Retrieval aid (optional, never authoritative):**
+when the index entry point exists, run it once before the forge read —
+`agentic-workflow doc --query "<topic terms>" --json-only` — to surface prior
+findings, decisions and session-log entries on this topic. It is a fast path
+over the same corpus grep covers: a missing index, an absent entry point, or an
+empty answer changes nothing (grep stays the exhaustive fallback — AC21), and
+the index is never a decision authority. In review-finding mode, read the target unit's SPEC,
 acceptance, `review-findings.md`, current diff, and PR instead of looking for an
 issue comment. Otherwise read the issue in full, including comments and labels
 (forge CLI per the project's Workflow conventions — examples use `gh`):

package/skills/unit-lane/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: unit-lane
 user-invocable: true
-version: 1.1.0
+version: 1.2.0
 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,24 +15,74 @@ 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.
+
+## Prior-decisions contradiction sweep
+
+Before the plan is accepted, sweep its claims against what the repository has
+**already decided in writing** — a plan must not contradict a prior decision in
+architecture, engineering, product, or any other domain.
+
+**Candidate sources** — deterministic keyword/FTS matching, no new index and no
+new tooling: `docs/features/<NN>-<slug>/decisions.md`,
+`docs/fix/<issue>-<topic>/decisions.md`, the project's architectural invariants,
+the Normalized Repository State (`discover-repository-state` /
+`resolve-repository-state`), `AGENTS.md`, and a unit SPEC's `## Design status`
+(legacy marker, units ≤ 60).
+
+**Fixed evidence shape** — one row per candidate hit, the decision quoted from
+its source:
+
+| claim | prior decision | source path | relation |
+|---|---|---|---|
+| <the plan claim> | <the recorded decision> | <path:line> | `contradicts` \| `compatible` |
+
+The cell value is exactly one of two values: `contradicts` or `compatible` —
+a row relation, not a stage verdict.
+
+**Advisory only — no new authority.** `contradicts` routes to
+`resolve-repository-state` only when the hit is against a frozen NRS fact
+(its only candidate source that carries a `<contradiction-id>` row after a
+`discover-repository-state` step); hits against
+`decisions.md` / `AGENTS.md` / architectural invariants / `## Design status`
+surface a `NEEDS-DECISION` for the user, per the existing rules. A plan with **no
+candidate match is clean and proceeds** — a miss never blocks it, a missed
+candidate can never void a plan, and the sweep issues no stage verdict and grants no
+gate of its own.
+
 ## 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)
+- [ ] Every plan claim touching architecture, engineering or product intent was
+      swept against the candidate sources above
+- [ ] Each candidate hit is one fixed-shape row, with the prior decision cited
+      at `path:line` and one of the two relations
 
 ## Forbidden
 
 - Do not bundle across phase boundaries — one phase = one commit
 - Do not plan work beyond the unit's acceptance criteria
 - Do not include docs/release tasks here — those are separate catalog steps
-- Do not invent tasks that the ACs do not demand
+- Do not invent tasks that the ACs do not demand
+- Do not turn the sweep into a gate, stage verdict or blocking check — it routes,
+  it never blocks a miss, and it adds no authority
+- Do not record a `prior decision` that no source `path:line` cites