@gtrabanco/pi-agentic-workflow 0.18.5 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.18.5",
+  "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/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.1
+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

@@ -31,6 +31,39 @@ backticked command **and** an expected outcome, e.g. `exits 0`), and the nested
 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
@@ -39,10 +72,17 @@ it is never out of scope for the executor.
 - [ ] 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