@gtrabanco/pi-agentic-workflow 0.18.4 → 0.18.5

package/package.json

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