@nklisch/pi-agile-workflow 0.16.3 → 0.16.4

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agile-workflow",
   "description": "Markdown-based work-tracking substrate for AI-driven projects. Items as files in .work/, late-binding releases, gates that produce items, goal-backed autopilot queue runner. See docs/VISION.md.",
-  "version": "0.16.3",
+  "version": "0.16.4",
   "author": {
     "name": "nklisch"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agile-workflow",
-  "version": "0.16.3",
+  "version": "0.16.4",
   "description": "Markdown-based work-tracking substrate for AI-driven projects. Items as files in .work/, late-binding releases, gates that produce items, goal-backed autopilot queue runner.",
   "author": {
     "name": "nklisch"

package/docs/ARCHITECTURE.md

@@ -305,8 +305,11 @@ git log --since='1 day ago' -- .work/
 ## Foundation docs (rolling-forward principle)
 docs/ holds standing context: VISION.md, SPEC.md, ARCHITECTURE.md, etc.
 - Foundation docs describe the system's current state or intended future state
+- Future-state claims are valid before implementation exists; foundation docs
+  need not mention every capability
 - Never retain superseded behavior descriptions or versioned migration notes
-- When implementation changes a foundation-doc assertion, update the doc
+- Update only assertions that become false, stale, or contradictory; omission is
+  not drift
 - Git history is the audit trail; the doc carries the active truth
 ````
 
@@ -568,7 +571,7 @@ to the unbound backlog so the gate does not silently expand release scope.
 | `gate-security` | Bound items' code changes against security checklist | Items with `gate_origin: security`, tagged `[security]`, `release_binding` set |
 | `gate-tests` | Useful coverage at stable interfaces, complex units, and bug regressions; low-value tests exposed by the bundle | Items with `gate_origin: tests`, tagged `[testing]` for valuable gaps or removals |
 | `gate-cruft` | Local or system-wide code, tests, checks, compatibility paths, and abstractions that may no longer earn their cost | Items with `gate_origin: cruft`, tagged `[cleanup]`; guarantee-reducing removals require user confirmation |
-| `gate-docs` | Foundation-doc alignment with the bundle's behavior changes | Items with `gate_origin: docs`, tagged `[documentation]` — enforces rolling-foundation |
+| `gate-docs` | Existing foundation assertions that may be false, stale, or contradictory; omissions and unimplemented future claims are excluded | Items with `gate_origin: docs`, tagged `[documentation]` — enforces rolling-foundation |
 | `gate-patterns` | Reusable patterns that emerged in the bundle | Detailed pattern-skill files in `.agents/skills/patterns/` (single source of truth) with optional Claude mirror, the generated hook-loaded `.agents/rules/patterns.md` digest (slug+one-liner index pointing back at the skill, with banner + source hash), plus a tracking item with `gate_origin: patterns` |
 
 For gates that emit findings as items, placement flows through
@@ -617,7 +620,9 @@ parent, and dependency. Common patterns:
 - `work-view --help` for the full flag set
 
 Foundation docs in `docs/` describe the system's current state or intended
-future state, never the past; git history is the audit trail. The substrate
+future state, never the past; git history is the audit trail. Review existing
+assertions only: missing coverage and unimplemented future intent are not drift;
+flag only false, stale, or contradictory claims. The substrate
 itself is durable memory: record decisions, blockers, implementation
 discoveries, and review findings in item bodies instead of depending on chat
 history.
@@ -680,12 +685,16 @@ class is needed and allowed.
 
 Concrete model guidance lives in `skills/principles/references/models.md` and is
 resolved against current availability when selection matters. GPT-5.6 Luna is
-the implementation workhorse; Sol is preferred for design, review, complex code,
-and as the low-thinking bridge above Luna; Terra is a situational middle pick;
-and Claude Fable is a high-cost design, orchestration, and review specialist
-rather than the default implementer. These are capability recommendations, not
-fixed routing. Luna, Terra, Sol, and Codex share OpenAI lineage, so moving among
-them can provide fresh context but is not cross-model evidence.
+the cost-efficient routine implementation and fan-out workhorse; Sol is the
+quality-first general coding choice and remains preferred for design, review,
+and complex code; Terra is a situational middle pick. Sonnet 5 is the capable
+high-throughput Claude worker, Opus 4.8 the stable premium complex-coding and
+review default, and Fable 5 the high-cost escalation for the hardest ambiguous,
+long-running, orchestration, design, and review work. Model-specific prompting
+is conditional and symptom-driven rather than fixed boilerplate. These are
+capability recommendations, not fixed routing. Luna, Terra, Sol, and Codex share
+OpenAI lineage, so moving among them can provide fresh context but is not
+cross-model evidence.
 
 ### Bootstrap (user-invocable only)
 
@@ -742,7 +751,7 @@ neither substitutes inline self-approval for a required fresh-context lane.
 | `gate-security` | Security scan over bound items; produces items with `gate_origin: security` |
 | `gate-tests` | Test-coverage scan; produces gap items with `gate_origin: tests` |
 | `gate-cruft` | Dead-code scan; produces cleanup items with `gate_origin: cruft` |
-| `gate-docs` | Foundation-doc alignment; enforces rolling-foundation; produces doc-update items |
+| `gate-docs` | Assertion-only foundation-doc alignment; ignores omissions and unimplemented future claims; produces doc-update items |
 | `gate-patterns` | Pattern extraction; writes pattern skills (`.agents/skills/patterns/`), the generated `.agents/rules/patterns.md` digest, + tracking item with `gate_origin: patterns` |
 
 All five fire during `release-deploy`'s `quality-gate` stage in the order

package/docs/PRINCIPLES.md

@@ -383,10 +383,12 @@ stages advance. Reading the file IS reading the state of the work.
 ## 9. Rolling-Foundation
 
 Foundation docs (`docs/VISION.md`, `docs/SPEC.md`, `docs/ARCHITECTURE.md`,
-and any others) describe the project's vision (future-looking) and current
-intent — what is true now, OR what will be true once in-flight design lands.
-They roll forward in place as either evolves. No legacy comments. Git carries
-history; the doc carries truth.
+and any others) describe what is true now or the future state the project
+intends to reach. A future-state claim remains valid before implementation
+exists. Foundation docs are selective standing context, not an exhaustive
+inventory: silence about a capability is allowed. They roll forward when an
+assertion becomes false, stale, or contradictory. Git carries history; the doc
+carries truth.
 
 ### Two timing styles
 
@@ -402,9 +404,9 @@ Both are legitimate; the project picks one or mixes per change size:
 
 The discipline is identical in both styles: replace stale assertions in
 place, never accumulate "previously" / "in v1.x" / migration prose.
-`gate-docs` at release-deploy time is the backstop — it catches drift between
-intent (what the doc asserts) and reality (what code does) regardless of
-which timing style was used.
+`gate-docs` is an assertion-consistency backstop: it catches false, stale, or
+contradictory claims, but never treats missing coverage or merely unimplemented
+future intent as drift.
 
 ### What this forbids
 
@@ -418,14 +420,14 @@ which timing style was used.
 
 ### What this enables
 
-- A new contributor reads the doc and learns the system as it IS or as
-  it is meant to imminently become — not as it was
+- A new contributor reads the doc and learns the system as it is or as
+  it is intended to become — not as it was
 - Foundation docs stay short and current rather than growing with every
   change
 - `git log docs/<file>.md` shows every rolling-forward edit — perfect
   audit trail without bloating the doc
-- Discrepancies between intent and reality become bugs that `gate-docs`
-  surfaces, not historical artifacts to be reconciled mentally
+- False, stale, or contradictory assertions become bugs that `gate-docs`
+  surfaces; omissions and not-yet-implemented future claims do not
 
 ### At design time
 
@@ -434,8 +436,8 @@ which timing style was used.
   the update as part of scope)
 - For large-scope `scope` operations, design-first is the default —
   `scope` rolls foundation docs forward as part of the same operation
-- Identify which foundation doc(s) need rolling forward; reading them
-  at design time prevents stale assumptions
+- Identify any existing foundation assertions the design changes or
+  contradicts; do not add coverage merely because the docs omit the capability
 - If a feature's design contradicts a foundation doc, EITHER the design
   is wrong OR the doc is. Resolve before designing the implementation.
 
@@ -449,18 +451,20 @@ which timing style was used.
   adjust whichever was wrong (implementation or assertion).
 - Replace stale assertions in place. Delete the old text. Never append
   "previously" / "in v1.x" / migration prose.
-- The `gate-docs` runs at release-deploy time and produces items for
-  any remaining drift — but the goal is to leave it nothing to find.
+- The `gate-docs` skill produces items only for remaining false, stale, or
+  contradictory assertions—not missing coverage or unimplemented future intent.
 
 ### Design checklist
 
-- [ ] Every assertion in SPEC and ARCHITECTURE reflects current code OR
-      imminent in-flight design (no stale assertions from cancelled work)
+- [ ] Every assertion in SPEC and ARCHITECTURE is true for the current or
+      intended-future state it claims (no stale assertions from superseded intent)
 - [ ] VISION.md reflects the project's current direction, not past direction
 - [ ] No "previously" / "originally" / "in v1.x" prose anywhere in `docs/`
-- [ ] When a feature changes behavior or direction, foundation docs update
-      in the same commit set as the change (code-first) or were preflight-
-      updated and are still accurate (design-first)
+- [ ] When a feature invalidates an existing foundation assertion, that
+      assertion updates in the same commit set (code-first) or was preflight-
+      updated and remains accurate (design-first)
+- [ ] No finding or edit was created solely because foundation docs omit a
+      capability or describe future intent not yet implemented
 - [ ] `git log docs/<file>.md` shows the audit trail; the doc shows the
       present
 

package/docs/VISION.md

@@ -34,9 +34,11 @@ The plugin enforces three execution principles:
   review findings — all accumulate in the item's body as stages advance.
   Reading the file IS reading the state of work.
 - **Foundation docs roll forward.** `docs/VISION.md`, `docs/SPEC.md`,
-  `docs/ARCHITECTURE.md` describe current truth or intended future state.
-  When implementation changes what those docs assert, the docs update to
-  match the new truth. No retained descriptions of superseded behavior or
+  `docs/ARCHITECTURE.md` describe current truth or intended future state. They
+  are selective rather than exhaustive: omission is allowed, and a future-state
+  claim is valid before implementation exists. When an assertion becomes false,
+  stale, or contradictory, it updates to match the new truth. No retained
+  descriptions of superseded behavior or
   migration commentary. Git is the audit trail.
 - **Late-bind everything.** No upfront roadmap. No pre-populated stages.
   No pre-tagged release bindings. Items advance stages when work actually
@@ -111,7 +113,7 @@ The pattern proves itself when a fresh session in a substrate-bootstrapped repo
 picks up active work without re-feed; when direct production work and autopilot
 both finish decisively while respecting dependency, test-integrity, review, and
 parent-roll-up invariants; and when foundation docs five features later still
-describe the present without legacy comments.
+make true, noncontradictory current-or-future claims without legacy comments.
 
 ## Relationship to workflow
 

package/hooks/scripts/prompt-context.py

@@ -110,6 +110,7 @@ CAPSULES = {
             "Stories fast-advance on verification; features and epics get deeper review.",
             "Reviewer findings are proposals; the receiving orchestrator judges actual risk in repository context.",
             "Only material current-cycle risk blocks completion; park valid lower-priority findings and continue.",
+            "Foundation docs may describe future intent: review existing claims only; omission or absent implementation is not drift.",
             "Advisory review is non-blocking during design, but final autopilot completion needs a successful review path.",
         ],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-agile-workflow",
-  "version": "0.16.3",
+  "version": "0.16.4",
   "description": "Markdown-based work-tracking substrate for AI-driven projects.",
   "author": {
     "name": "nklisch"

package/scripts/work-view.sh

@@ -22,7 +22,7 @@
 set -euo pipefail
 
 # Kept in lockstep with plugin.json by scripts/bump-version.sh. Do not hand-edit.
-WORK_VIEW_VERSION="0.16.3"
+WORK_VIEW_VERSION="0.16.4"
 
 # ============================================================================
 # Version prelude (POSIX / bash 3.2 safe — runs BEFORE the Bash-4 guard)

package/skills/autopilot/SKILL.md

@@ -303,9 +303,11 @@ When the scoped queue appears drained:
    - `standard`: use balanced risk-based fresh-context review.
    - `thorough`: increase complementary and adversarial fresh-context coverage.
    - `maximum`: seek multi-model, multi-pass complementary → adversarial review.
-   Ask for bugs, missed acceptance criteria, unreviewed risks, foundation-doc
-   drift, and substrate-state inconsistencies that would make "complete"
-   premature. Exact reviewer count and pass depth remain model judgment within
+   Ask for bugs, missed acceptance criteria, unreviewed risks, false/stale/
+   contradictory foundation-doc assertions, and substrate-state inconsistencies
+   that would make "complete" premature. Foundation-doc omissions and
+   unimplemented future-state claims are not findings. Exact reviewer count and
+   pass depth remain model judgment within
    the weight's ceiling/intent.
 3. When independent review runs, use a different-class peer when reachable;
    otherwise spawn a generic same-harness fresh-context reviewer from

package/skills/convert/SKILL.md

@@ -514,7 +514,9 @@ parent, and dependency. Common patterns:
 - `work-view --help` for the full flag set
 
 Foundation docs in `docs/` describe the system's current state or intended
-future state, never the past; git history is the audit trail. Item files are
+future state, never the past; git history is the audit trail. Review existing
+assertions only: missing coverage and unimplemented future intent are not drift;
+flag only false, stale, or contradictory claims. Item files are
 the durable state: update the body with implementation discoveries, review
 findings, blockers, and decisions instead of relying on chat history.
 

package/skills/gate-docs/SKILL.md

@@ -3,7 +3,7 @@ name: gate-docs
 description: >
   Documentation gate that enforces the rolling-foundation principle. Delegates the full drift
   detection to a deep documentation scanner agent which scans the bundle's changes for
-  foundation-doc drift (assertions in docs/ that no longer match implementation), changelog gaps,
+  foundation-doc drift (false, stale, or contradictory assertions—not missing coverage), changelog gaps,
   README staleness, and skill/pattern-skill staleness. The orchestrator converts findings into items
   in .work/active/ with gate_origin:docs and tags:[documentation]. Auto-triggers during
   /agile-workflow:release-deploy.
@@ -12,10 +12,12 @@ description: >
 # Gate-Docs
 
 You orchestrate a documentation gate that enforces the **rolling-foundation
-principle**: foundation docs in `docs/` describe current truth or intended
-future state, never past state. After implementation work, foundation-doc
-assertions can drift from reality or from the intended state they are meant to
-describe.
+principle**: foundation docs in `docs/` may describe current truth or intended
+future state, never superseded truth. Future-state claims do not become drift
+merely because implementation has not reached them, and foundation docs are not
+required to mention every capability or bundle change. Drift exists only when an
+assertion is false for the time/state it claims, stale after intent changed, or
+contradictory with another authoritative claim.
 
 The actual drift detection runs inside a **deep documentation scanner agent**
 (a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md`); your role is to
@@ -77,10 +79,14 @@ returns structured findings.
 **Brief template**:
 
 > You are conducting a documentation drift audit for release `<version>` as an
-> agile-workflow scanner. The principle: docs in `docs/` describe current truth
-> or intended future state, never past state. Drift = doc says X, but the
-> completed bundle now does Y or the intended future state has changed to Y. Use
-> read/search/shell tools as needed, but do not spawn nested sub-agents or fix docs.
+> agile-workflow scanner. The principle: foundation docs in `docs/` may describe
+> current truth or intended future state. Drift is assertion-only: a claim is
+> false for the state/time it says it describes, stale because intent changed,
+> or contradictory with another authoritative claim. A future-state assertion
+> is not drift merely because code does not implement it yet. Missing foundation-
+> doc coverage is allowed: do not flag, add, or request claims for bundle changes
+> the foundation docs do not discuss. Use read/search/shell tools as needed, but
+> do not spawn nested sub-agents or fix docs.
 >
 > **Bundle scope** (the changes that may have caused drift):
 > ```
@@ -110,8 +116,9 @@ returns structured findings.
 >    - Generated files (look for `# generated`, `llms-full.txt` — never
 >      edit; flag for regeneration)
 >
-> 2. **Classify each bound item's change type**:
->    | Change type | Doc owners |
+> 2. **Classify each bound item's change type**. This table identifies places to
+>    check for existing claims; it does not require foundation-doc coverage:
+>    | Change type | Potential references |
 >    |---|---|
 >    | New feature / behavior | SPEC.md, ARCHITECTURE.md, relevant guide pages |
 >    | New CLI command or flag | CLI reference, SPEC.md, guide pages |
@@ -123,10 +130,15 @@ returns structured findings.
 >    | Changed interface used by repo skills | Repo-specific skills referencing it |
 >
 > 3. **Drift-check passes** — run each relevant pass yourself:
->    - **Foundation-doc drift** — for VISION.md, SPEC.md, ARCHITECTURE.md,
->      for each assertion (interface, contract, component, behavior), grep
->      the bundle's changed files. Flag any assertion where the doc says X
->      but the code now does Y. Cite file:line for the doc and the code.
+>    - **Foundation-doc drift** — inspect only assertions that exist in
+>      VISION.md, SPEC.md, ARCHITECTURE.md, and domain foundation docs. First
+>      classify each assertion as current-state or intended-future-state. For a
+>      current-state claim, flag only when authoritative implementation now
+>      contradicts it. For a future-state claim, flag only when newer accepted
+>      intent or another authoritative foundation claim contradicts it—not when
+>      implementation is absent. Never flag a bundle capability merely because
+>      no foundation doc mentions it. Cite file:line for the claim and its
+>      contradicting source.
 >    - **README staleness** — verify quick-start, install steps, examples,
 >      command names match the codebase post-bundle.
 >    - **CHANGELOG gap** — for each item bound to release `<version>`,
@@ -157,10 +169,12 @@ returns structured findings.
 > - **Confidence**: High | Medium
 > - **Relevance**: Release-relevant | Ambient
 > - **Doc location**: `<file>:<line>`
-> - **Code location**: `<file>:<line>` (for assertion drift; omit for gaps)
+> - **Contradicting source**: `<file>:<line>` (implementation, newer intent,
+>   or another authoritative claim; omit for non-assertion categories)
 > - **Current doc text**:
 >   > <quote — what the doc currently says>
-> - **Reality**: <what the code now does, post-bundle>
+> - **Contradiction**: <why the quoted claim is false, stale, or contradictory
+>   for the state/time it claims to describe>
 > - **Required edit**: <roll the doc forward to match the new active truth.
 >   Apply rolling-foundation: no "previously" prose, no "in v1.x" notes.
 >   Replace the assertion in place. For generated files, give the
@@ -184,6 +198,9 @@ returns structured findings.
 >   Follow concrete references into adjacent docs, generated catalogs, or
 >   system-wide documentation when needed; do not perform an aimless doc sweep.
 > - Cite file:line for every finding.
+> - Absence is not a foundation-doc finding. Do not propose adding coverage for
+>   an undocumented bundle change, and do not treat unimplemented future intent
+>   as stale current-state documentation.
 > - Required edits ENFORCE rolling-foundation: replace stale assertions in
 >   place. Do NOT propose adding "previously" or "in v1.x" prose. Git is the
 >   audit trail; the doc carries the active truth.
@@ -225,13 +242,13 @@ updated: YYYY-MM-DD
 
 ## Location
 - Doc: `<file>:<line>`
-- Code: `<file>:<line>` (for assertion drift)
+- Contradicting source: `<file>:<line>` (for assertion drift)
 
 ## Current doc text
 > <quote the doc — what it currently says>
 
-## Reality
-<what the code now does, post-bundle>
+## Contradiction
+<why the claim is false, stale, or contradictory for its stated time/state>
 
 ## Required edit
 <roll the doc forward to match the new active truth. Apply rolling-foundation:
@@ -263,17 +280,19 @@ In conversation:
 - **Drift found**: count by category
 - **Items created**: count, with new ids
 - **Generated files needing regen**: list (if any)
-- **Goal reminder**: rolling-foundation enforces docs describing current truth
-  or intended future state, never past state. Findings here become items the
-  release flow drains to `done` before shipping.
+- **Goal reminder**: rolling-foundation permits current truth or intended future
+  state. Only false, stale, or contradictory assertions become findings; missing
+  coverage and unimplemented future intent do not. Findings here become items
+  the release flow drains to `done` before shipping.
 
 ## Guardrails
 
 - **The drift detection happens in the scanner agent, not here.** Your job is
   bundle prep, dispatch, and item-writing. Don't replicate the scanner's
   analysis in the orchestrator's context.
-- Foundation-doc drift is the gate's primary job. The scanner surfaces it;
-  you turn it into items.
+- Foundation-doc drift is assertion-only: false, stale, or contradictory
+  claims. Missing coverage and merely unimplemented future-state claims are not
+  findings and must not produce items or edits.
 - Required edits ENFORCE rolling-foundation: replace stale assertions in
   place. Do NOT propose adding "previously" or "in v1.x" prose.
 - Don't fix the docs in this skill — produce items only. Implementation of

package/skills/principles/SKILL.md

@@ -127,7 +127,7 @@ The unit of work is its file. The brief, the design, the implementation notes, a
 
 ## 9. Rolling-Foundation
 
-Foundation docs (`docs/VISION.md`, `docs/SPEC.md`, `docs/ARCHITECTURE.md`, and any others) describe the project's vision (future-looking) and current intent — what is true now, OR what will be true once in-flight design lands. They roll forward in place as either evolves. No legacy comments. Git carries history; the doc carries truth.
+Foundation docs (`docs/VISION.md`, `docs/SPEC.md`, `docs/ARCHITECTURE.md`, and any others) describe what is true now or the future state the project intends to reach. A future-state claim remains valid before implementation exists. Foundation docs are selective standing context, not an exhaustive inventory: silence about a capability is allowed. They roll forward when an assertion becomes false, stale, or contradictory. Git carries history; the doc carries truth.
 
 ### Two timing styles
 
@@ -136,7 +136,7 @@ Both are legitimate; the project picks one or mixes per change size:
 - **Code-first (default for routine features):** docs update at implementation merge, in the same commit set as the code that lands the change.
 - **Design-first (for large scope, initial ideation, architectural shifts):** docs preflight-update at scope time, leading the code through the implementation window. The doc temporarily describes an intended near-future state. The agile-workflow `scope` skill operates this way for large scope; `ideate` operates this way at project bootstrap.
 
-The discipline is identical in both styles: replace stale assertions in place, never accumulate "previously" / "in v1.x" / migration prose. `gate-docs` at release-deploy time is the backstop — it catches drift between intent and reality regardless of which timing style was used.
+The discipline is identical in both styles: replace stale assertions in place, never accumulate "previously" / "in v1.x" / migration prose. `gate-docs` is an assertion-consistency backstop: it catches false, stale, or contradictory claims, but never treats missing coverage or merely unimplemented future intent as drift.
 
 ### What this forbids
 
@@ -148,16 +148,16 @@ The discipline is identical in both styles: replace stale assertions in place, n
 
 ### What this enables
 
-- A new contributor reads the doc and learns the system as it IS or as it is meant to imminently become — not as it was
+- A new contributor reads the doc and learns the system as it is or as it is intended to become — not as it was
 - Foundation docs stay short and current rather than growing with every change
 - `git log docs/<file>.md` shows every rolling-forward edit — perfect audit trail
-- Discrepancies between intent (what the doc asserts) and reality (what code does) become bugs that gate-docs surfaces, not historical artifacts
+- False, stale, or contradictory assertions become bugs that gate-docs surfaces; omissions and not-yet-implemented future claims do not
 
 ### At design time
 
 - When scoping a feature that changes a foundation-doc assertion, decide the timing: code-first (defer the doc update) or design-first (preflight the update as part of scope)
 - For large-scope `scope` operations, design-first is the default — `scope` rolls foundation docs forward as part of the same operation
-- Identify which foundation doc(s) need rolling forward; reading them at design time prevents stale assumptions
+- Identify any existing foundation assertions the design changes or contradicts; do not add coverage merely because the docs omit the capability
 - If a feature's design contradicts a foundation doc, EITHER the design is wrong OR the doc is. Resolve before designing the implementation.
 
 ### At implementation time
@@ -165,14 +165,15 @@ The discipline is identical in both styles: replace stale assertions in place, n
 - If working code-first: after implementing a change, ask "what does a foundation doc now say that's no longer true?" — update assertions in place, commit with the implementation
 - If working design-first: the doc was preflight-updated at scope time. Verify the implementation matches the doc's assertion; if it deviates, adjust whichever was wrong (implementation or assertion).
 - Replace stale assertions in place. Delete the old text. Never append.
-- The `gate-docs` skill runs at release-deploy time and produces items for any remaining drift — but the goal is to leave it nothing to find.
+- The `gate-docs` skill produces items only for remaining false, stale, or contradictory assertions—not missing coverage or unimplemented future intent.
 
 ### Design checklist
 
-- [ ] Every assertion in SPEC and ARCHITECTURE reflects current code OR imminent in-flight design (no stale assertions from cancelled work)
+- [ ] Every assertion in SPEC and ARCHITECTURE is true for the current or intended-future state it claims (no stale assertions from superseded intent)
 - [ ] VISION.md reflects the project's current direction, not past direction
 - [ ] No "previously" / "originally" / "in v1.x" prose anywhere in `docs/`
-- [ ] When a feature changes behavior or direction, foundation docs update in the same commit set as the change (code-first) or were preflight-updated and are still accurate (design-first)
+- [ ] When a feature invalidates an existing foundation assertion, that assertion updates in the same commit set (code-first) or was preflight-updated and remains accurate (design-first)
+- [ ] No finding or edit was created solely because foundation docs omit a capability or describe future intent not yet implemented
 - [ ] `git log docs/<file>.md` shows the audit trail; the doc shows the present
 
 ---

package/skills/principles/references/models.md

@@ -9,8 +9,8 @@
 > "use a different model class".
 
 Model generations move fast — the *families and classes* below are the durable
-abstraction; specific versions and names (for example Claude Fable, GPT-5.6
-Luna/Terra/Sol, GPT-5.x-Codex, Gemini 3.5, and GLM-5.2) are current resolutions
+abstraction; specific versions and names (for example Claude Fable 5, GPT-5.6
+Luna/Terra/Sol, Gemini 3.5, and GLM-5.2) are current resolutions
 of each class as of writing. Always resolve
 the concrete model against current sources when the choice is load-bearing.
 
@@ -19,11 +19,12 @@ the concrete model against current sources when the choice is load-bearing.
 1. [Capability axes (the decision vocabulary)](#1-capability-axes-the-decision-vocabulary)
 2. [Model-family cards](#2-model-family-cards)
 3. [Role → capability → model](#3-role--capability--model)
-4. [Host → cross-class peer pairing](#4-host--cross-class-peer-pairing)
-5. [Multi-class review for deep/complex work](#5-multi-class-review-for-deepcomplex-work)
-6. [Two-phase design review: advisory then adversarial](#6-two-phase-design-review-advisory-then-adversarial)
-7. [peeragent invocation cheatsheet](#7-peeragent-invocation-cheatsheet)
-8. [Fallbacks when no peer is reachable](#8-fallbacks-when-no-peer-is-reachable)
+4. [Conditional prompt tuning](#4-conditional-prompt-tuning)
+5. [Host → cross-class peer pairing](#5-host--cross-class-peer-pairing)
+6. [Multi-class review for deep/complex work](#6-multi-class-review-for-deepcomplex-work)
+7. [Two-phase design review: advisory then adversarial](#7-two-phase-design-review-advisory-then-adversarial)
+8. [peeragent invocation cheatsheet](#8-peeragent-invocation-cheatsheet)
+9. [Fallbacks when no peer is reachable](#9-fallbacks-when-no-peer-is-reachable)
 
 ---
 
@@ -36,49 +37,47 @@ the in-skill prose names; this is what they mean.
   entire value of a cross-model peer is independent blind spots, *not* a more
   authoritative answer. Two models that share training add little over one.
 - **Reasoning depth** — multi-step deduction, proof-like correctness, holding a
-  large logical structure. Raised by high/xhigh effort tiers; strongest in
-  Opus-class, GPT-5.x-Codex at xhigh, GLM-5.2 at xhigh.
+  large logical structure. Raised by high/xhigh effort tiers; high-capability
+  choices include Fable 5, Opus 4.8, GPT-5.6 Sol, and GLM-5.2.
 - **Long-horizon agentic stamina** — sustained self-correcting multi-step tool
-  use over many turns / long autonomous runs. Strongest in Codex, GLM-5.2
-  (built for up-to-8h agentic runs), and Opus-class.
-- **Context window** — how much the model can hold at once. GLM-5.2 (1M),
-  Opus-class (1M), Gemini 3.5 (2M, Deep Think), Sonnet-class (1M beta).
-- **Latency budget** — wall-clock cost. Top-tier reasoning peers (Opus-class,
-  xhigh Codex/GLM) commonly take **10–30 minutes** for large reviews and may be
-  quiet for most of it. Budget for it; do not treat a long quiet period as a hang.
+  use over many turns / long autonomous runs. Fable 5, Opus 4.8, GPT-5.6 Sol,
+  and GLM-5.2 are credible choices, but none makes weak approval or verification
+  boundaries safe.
+- **Context window** — how much the model can hold at once. GLM-5.2 (1M maximum;
+  stable full-window fidelity remains under-tested independently), Fable 5 / Opus
+  4.8 / Sonnet 5 (1M), Gemini 3.5 (2M, Deep Think).
+- **Latency budget** — wall-clock cost. Top-tier reasoning peers (Fable 5,
+  Opus 4.8, Sol, and xhigh GLM) commonly take **10–30 minutes** for large reviews
+  and may be quiet for most of it. Budget for it; do not treat a long quiet
+  period as a hang.
 - **Write fidelity** — code-writing accuracy and instruction-following for
   production edits. The property that earns a model a *worker* role.
 
 ## 2. Model-family cards
 
 **Claude (Anthropic)** — `--agent claude`
-- Tiers include `opus`, `sonnet`, `haiku`, and Claude Fable where available.
-- Effort: `high | xhigh` (default `xhigh`).
-- Recommendations: Opus for deep review/adversarial work, Sonnet for primary
-  work and scouting, Haiku for cheap leaf fan-out. Fable is a strong but
-  expensive design, orchestration, and review choice; it can implement, but its
-  cost usually makes another capable worker preferable.
+- Current upper tiers are Fable 5, Opus 4.8, and Sonnet 5; Haiku remains the
+  cheap leaf-fan-out tier. Effort: `high | xhigh` (wrapper default `xhigh`).
+- Sonnet 5 high is the capable high-throughput worker/scout; use xhigh for its
+  hardest coding. Opus 4.8 xhigh is the stable premium default for complex
+  coding, debugging, and deep review. Fable 5 high/xhigh is the expensive
+  escalation for the hardest ambiguous, long-running, orchestration, design,
+  and review work—not the routine implementer. Prefer Opus for security-adjacent
+  work where Fable's safety classifier/fallback could interrupt the run.
 
 **GPT-5.6 (OpenAI; host-native where available)**
-- **Luna** is the recommended implementation workhorse: medium thinking for
-  simple/routine work, scaling through xhigh for fairly complicated work short
-  of the hardest tier.
-- **Terra** remains a situational middle pick. Current practitioner preference
-  often favors Sol at low thinking as the bridge above Luna rather than treating
-  Terra as a mandatory rung.
-- **Sol** is preferred for design, review, and complex/large implementation. Low
-  thinking bridges above Luna; raise thinking for the hardest architecture,
-  review, and coding work.
-- These are recommendations, not fixed capability facts. Discover current host
-  availability before selection. Luna, Terra, Sol, and Codex share OpenAI
-  lineage, so switching among them is not cross-model evidence.
-
-**Codex (OpenAI)** — `--agent codex`
-- Current class: GPT-5.x-Codex (model auto-selected; no `--model` flag).
-- Effort: `medium | high | xhigh` (default `high`).
-- Strengths: top-tier long-horizon agentic coding, multi-step tool use.
-- Best roles: cross-class peer from a Claude/Gemini/GLM host; highest-tier
-  worker for long agentic write paths.
+- **Luna** is the cost-efficient routine implementation and fan-out workhorse:
+  start at medium, then raise effort for bounded work that still benefits from
+  the cheaper tier. Do not make it the default for every implementation task.
+- **Terra** remains a situational middle pick for moderate work and bounded
+  context reading. Luna at more effort or Sol at less effort often gives a
+  better cost/capability point, so Terra is not a mandatory rung.
+- **Sol** is the quality-first general coding default at medium/high and the
+  preferred model for design, review, and complex/large implementation at
+  higher effort. Reserve max-like modes for measured quality gains behind tight
+  action boundaries; documented over-persistence grows at the highest efforts.
+- Discover current host availability before selection. Luna, Terra, Sol, and
+  Codex share OpenAI lineage, so switching among them is not cross-model evidence.
 
 **Gemini (Google)** — `--agent gemini`
 - Model: `gemini-3.5` (2M context, Deep Think mode).
@@ -86,31 +85,44 @@ the in-skill prose names; this is what they mean.
 - Best roles: cross-class peer; large-context review where 2M context matters.
 
 **Z.AI GLM 5.2** — `--agent zai`
-- Model: `glm-5.2` only (MoE 744B / 40B-active; stable 1M context; DeepSeek
-  Sparse Attention; built for long-horizon agentic engineering, ~8h runs).
-- Effort: `medium | high | xhigh` (default `high`).
-- Best roles: cross-class peer (distinct training lineage → distinct blind
-  spots); long-horizon agentic worker; highest-tier reviewer at `xhigh`.
-- Note: the peeragent `zai` adapter runs GLM 5.2 **through Pi**, and needs a
-  current peeragent build (`zai` agent). Older cached builds only list
+- Model: `glm-5.2` only (MoE 744B / 40B-active; 1M maximum context; DeepSeek
+  Sparse Attention). Effort: `medium | high | xhigh` (wrapper default `high`).
+- Best roles: cross-class peer; cost-efficient localized implementation and
+  parallel inspection; high-tier reviewer when the relevant behavior is named.
+  Independent evidence is strong but variable: use a second pass or stronger
+  model when correctness depends on product rules distributed across files.
+- The peeragent `zai` adapter runs GLM 5.2 **through Pi** and needs a current
+  peeragent build (`zai` agent). Older cached builds only list
   `codex|claude|gemini`.
 
 ## 3. Role → capability → model
 
 | Role | Needs (capability) | Primary models |
 |---|---|---|
-| Primary worker | write fidelity, agentic stamina | GPT-5.6 Luna medium→xhigh / Sonnet-class / Codex high / GLM-5.2 high; Sol for complex/large implementation |
-| Scanner/scout (deep read-only fan-out) | domain inspection, evidence, scoped artifacts | Haiku / Luna or Sonnet for volume; Sol/Opus/Codex xhigh/GLM xhigh for subtle gates |
-| Deep reviewer | reasoning depth, fresh context | GPT-5.6 Sol / Claude Fable or Opus / Codex xhigh / GLM-5.2 xhigh |
+| Primary worker | write fidelity, agentic stamina | Luna medium→xhigh for routine/high-volume work; Sonnet 5 high or Sol medium/high for substantial work; Opus 4.8 xhigh / Fable 5 high→xhigh / GLM-5.2 high when complexity or horizon earns it |
+| Scanner/scout (deep read-only fan-out) | domain inspection, evidence, scoped artifacts | Haiku / Luna / Sonnet 5 for volume; Sol / Opus 4.8 / Fable 5 / GLM xhigh for subtle gates |
+| Deep reviewer | reasoning depth, fresh context | GPT-5.6 Sol / Claude Opus 4.8 or Fable 5 / GLM-5.2 xhigh, with a second pass for distributed invariants |
 | Advisory peer (Phase 1) | blind-spot diversity, augmentation | a **different class** than the host |
 | Adversarial peer (Phase 2) | blind-spot diversity, attack posture | a **different class** than host + than Phase 1 |
 
-## 4. Host → cross-class peer pairing
+## 4. Conditional prompt tuning
+
+Apply these only when the task shape or an observed trace warrants them; effort
+and a clear success criterion usually beat permanent model-specific boilerplate.
+
+| Model / symptom | Small adjustment |
+|---|---|
+| GPT-5.6 prompt bloat or scope drift | State outcome, success criteria, constraints, approval boundaries, and stop rules once; expose only relevant tools. Avoid generic persistence language. Require tool/diff/test evidence before claiming completion. |
+| Opus 4.8 / Sonnet 5 literalism or low review recall | State the rule's full scope explicitly. For review, ask for coverage first and rank/filter findings afterward. Raise effort before adding process prose; add tool triggers only when tool use is actually weak. |
+| Fable 5 over-planning or unrequested work | Ask for the simplest in-scope result; forbid speculative features/refactors and unrequested side actions. Ground progress claims in tool results. Never request hidden chain-of-thought reproduction. |
+| GLM-5.2 cross-file review misses | Name the behavioral invariant and every surface that must agree. Generic “strict production review” can divert into hardening checklists; for distributed correctness, require explicit validation plus an independent second pass. |
+
+## 5. Host → cross-class peer pairing
 
 The rule: the peer must be a **different model class** than the host, or it is
 not cross-model evidence (fall back to a fresh same-class sub-agent instead).
 For each host, several valid peer classes exist — pick by **maximum blind-spot
-diversity**, and for deep work use **two distinct peer classes** (§5).
+diversity**, and for deep work use **two distinct peer classes** (§6).
 
 | Host class | Valid peer classes (any different class) |
 |---|---|
@@ -123,7 +135,7 @@ When the natural pair is unavailable, fall through to the next class; never
 peer within the host lineage and call it cross-model. A same-lineage reviewer
 may still provide fresh context when labeled accurately.
 
-## 5. Multi-class review for deep/complex work
+## 6. Multi-class review for deep/complex work
 
 The risk and `review_weight` policy lives in
 [advisory-review.md](advisory-review.md). At model-selection time, when that
@@ -131,7 +143,7 @@ policy calls for two classes, choose two distinct training lineages that also
 differ from the host where availability permits. Pair one with each phase;
 disagreement is evidence to investigate, not a vote.
 
-## 6. Two-phase design review: advisory then adversarial
+## 7. Two-phase design review: advisory then adversarial
 
 The phase order, artifact-specific loop shapes, ceilings, and recording format
 live in [advisory-review.md](advisory-review.md). This model-layer reference adds
@@ -139,7 +151,7 @@ one constraint: when two classes are selected, Phase 2 should differ from both
 the host and Phase 1 where the available class set permits it. Never label an
 unknown or same-class reviewer cross-model.
 
-## 7. peeragent invocation cheatsheet
+## 8. peeragent invocation cheatsheet
 
 Resolve the wrapper before calling — never assume `peeragent` is on `PATH`
 (`PEERAGENT_BIN` → bundled `bin/peeragent` → bare `peeragent`). Run in the
@@ -157,7 +169,7 @@ host harness's outside-sandbox mode; never `--full-access` for review.
 Always tell the reviewer **not** to recurse back through peeragent's own
 `peer`/`peer-review` skills or the wrapper — the reviewer is the endpoint.
 
-## 8. Fallbacks when no peer is reachable
+## 9. Fallbacks when no peer is reachable
 
 When peeragent is unavailable, fails, would be same-class, or the needed class
 isn't reachable: spawn a **fresh max-effort generic sub-agent** at the highest

package/skills/review/SKILL.md

@@ -245,8 +245,8 @@ model strength, or repeated mention does not make a finding blocking.
   security, data integrity, public contracts, acceptance criteria, release
   safety, or trustworthy verification. It must be fixed or kept active before
   advancing. Examples include a demonstrated correctness bug, exploitable
-  vulnerability, unintended breaking change, material foundation-doc drift, or
-  a test that proves required behavior is wrong.
+  vulnerability, unintended breaking change, a false/stale/contradictory
+  foundation-doc assertion, or a test that proves required behavior is wrong.
 - **Important**: valid work below the current-cycle blocker bar. Park it in the
   unbound backlog with the risk rationale and advance the reviewed item. Examples
   include unlikely low-consequence edges, worthwhile hardening, nonessential
@@ -362,8 +362,9 @@ Nothing blocking or significant to flag."
   concerns evaporate into review prose.
 - Review's security check is lightweight. For a full security gate, use
   `/agile-workflow:gate-security`.
-- Foundation-doc drift is a blocker, not a nit. Rolling foundation is a hard
-  rule.
+- A false, stale, or contradictory foundation-doc assertion is a blocker, not a
+  nit. Missing coverage and future-state claims whose implementation has not yet
+  landed are not drift and must not be flagged or changed.
 - Do not advance an item past review unless the verdict is Approve or Approve
   with comments. Pushing through receiver-confirmed material blockers defeats
   the point of the stage; parking lower-risk findings does not.

package/skills/review/references/review-lenses.md

@@ -43,10 +43,20 @@ lenses and note any lens skipped with the reason.
 
 ## Foundation-Doc Alignment
 
-- Does implementation invalidate any assertion in foundation docs such as
-  `docs/VISION.md`, `docs/SPEC.md`, or `docs/ARCHITECTURE.md`?
-- If yes, did the implementer roll the doc forward in the same change?
-- Foundation-doc drift is a blocker in substrate mode.
+Foundation docs may describe current state or intended future state and need not
+cover every capability. Review assertions, not omissions:
+
+- Does implementation make an existing current-state assertion in
+  `docs/VISION.md`, `docs/SPEC.md`, `docs/ARCHITECTURE.md`, or another foundation
+  doc false or stale?
+- Does an existing future-state assertion contradict newer accepted intent or
+  another authoritative foundation claim? Lack of implementation alone is not a
+  contradiction.
+- If an assertion is false, stale, or contradictory, did the implementer roll it
+  forward in the same change?
+- Never request a foundation-doc addition merely because the change is missing
+  from those docs. Assertion drift is a blocker in substrate mode; omission is
+  not a finding.
 
 ## Naming And Comments
 

package/skills/review/references/target-resolution.md

@@ -40,7 +40,8 @@ or story should already have passed review. Gather:
   children.
 
 Use the aggregate scope to spot cross-cutting concerns: public API shifts,
-foundation-doc drift, release gaps, and capability completeness.
+false/stale/contradictory foundation-doc assertions (not omissions or
+unimplemented future intent), release gaps, and capability completeness.
 
 ## Empty Diff Handling
 

package/work-view/crates/cli/.work-view-version

@@ -1 +1 @@
-0.16.3
+0.16.4