@nklisch/pi-agile-workflow 0.16.1 → 0.16.4

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>`,
@@ -155,11 +167,14 @@ returns structured findings.
 >   changelog-gap | repo-skill-staleness | pattern-skill-staleness |
 >   generated-file-needs-regen | doc-misplacement
 > - **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
@@ -179,9 +194,13 @@ returns structured findings.
 > ```
 >
 > **Rules**:
-> - Scan only the bundle's changes plus the docs that own those areas.
->   Don't audit every doc in the repo.
+> - Bundle changes and their owning docs are the focus, not a hard boundary.
+>   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.
@@ -210,7 +229,7 @@ stage: implementing       # high-confidence drift
 tags: [documentation]
 parent: null
 depends_on: []
-release_binding: <version>
+release_binding: <version> | null  # null for ambient findings
 gate_origin: docs
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
@@ -223,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:
@@ -239,6 +258,10 @@ no "previously" prose, no "in v1.x" notes. Replace the assertion in place.>
 For generated files needing regeneration, the item describes the regeneration
 command rather than a manual edit.
 
+Release-relevant drift uses the normal confidence mapping and binds to the
+release. Ambient staleness merely discovered while following references goes to
+the unbound backlog.
+
 Default confidence -> placement mapping:
 - **High** → `stage: implementing` in `.work/active/stories/`
 - **Medium** → `stage: drafting` in `.work/active/stories/`
@@ -257,22 +280,25 @@ 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
   the fixes happens via `/agile-workflow:implement` on each item.
-- Audit only the bundle's changes plus the docs that own those areas — the
-  scanner enforces this; don't override.
+- Release-bound changes define focus, not a hard boundary. Follow concrete
+  documentation ownership and reference chains; route merely ambient drift to
+  the unbound backlog rather than silently expanding the release.
 - Generated files get items describing the regeneration command, not manual
   edits.

package/skills/gate-patterns/SKILL.md

@@ -107,7 +107,7 @@ output.
 > Use read/search/shell tools as needed. Do not spawn nested sub-agents or modify
 > source files.
 >
-> **Bundle scope**:
+> **Bundle focus** (start here; follow recurring shapes across the repository):
 > ```
 > <bundle-files>
 > ```
@@ -120,8 +120,10 @@ output.
 >
 > **Methodology**:
 >
-> 1. **Pattern discovery passes** — inspect the bundle's changed files plus
->    their immediate consumers (since reuse implies multiple call sites):
+> 1. **Pattern discovery passes** — inspect the bundle's changed files first,
+>    then follow candidate shapes through consumers and the wider repository
+>    where needed to establish genuine recurrence. Bound files are the focus,
+>    not a hard scan boundary:
 >    - **Shared abstractions & utilities** — find new shared/reusable code
 >      introduced in the bundle: utility functions, base classes, common
 >      helpers, types used across multiple modules. List each with
@@ -225,6 +227,8 @@ output.
 >   the divergence instead.
 > - Don't fabricate patterns. If discovery yields nothing, return an empty
 >   "New patterns" section.
+> - Expansion beyond the bundle must follow a concrete candidate pattern or
+>   inconsistency; do not perform an unfocused whole-repo style audit.
 
 ### Phase 4: Write pattern files
 

package/skills/gate-refactor/SKILL.md

@@ -139,8 +139,10 @@ M-times-N redundant file reads and allows cross-library finding deduplication.
 **Brief template**:
 
 > You are conducting a refactor gate scan for release `<version>` as an agile-workflow
-> scanner. Use read/search/shell tools as needed. Scan ONLY the bundle's changed files —
-> not the whole repo. Do not spawn nested sub-agents or implement fixes.
+> scanner. Use read/search/shell tools as needed. Start with the bundle's changed
+> files and follow concrete rule-relevant references into adjacent consumers,
+> dependencies, or shared systems. Do not perform an aimless whole-repo sweep,
+> spawn nested sub-agents, or implement fixes.
 >
 > **Bundle scope** (files changed by the bundle):
 > ```
@@ -169,6 +171,7 @@ M-times-N redundant file reads and allows cross-library finding deduplication.
 >
 > 1. Read every file in the bundle scope.
 > 2. For each file, check against all rules from all loaded libraries in a single pass.
+>    Expand only when a rule or concrete reference requires adjacent/system-wide context.
 > 3. For each finding, record:
 >    - **Library tag**: which library's rule was violated (e.g. `structural`).
 >    - **Rule slug**: which specific rule was violated (from the library's rule inventory).
@@ -176,11 +179,13 @@ M-times-N redundant file reads and allows cross-library finding deduplication.
 >    - **Issue**: one-sentence description of the violation.
 >    - **Fix**: specific proposed change (or "needs analysis" for findings requiring judgment).
 >    - **Confidence**: `high` / `medium` / `low` per the library's guidance for that rule.
+>    - **Relevance**: `Release-relevant` or `Ambient`.
 > 4. Deduplicate against the already-tracked set.
 > 5. Return findings as a structured list.
 >
 > **Rules**:
-> - Scan only the bundle scope. Do not expand to the whole repo.
+> - Bundle scope is the focus, not a hard boundary. Follow concrete rule-relevant
+>   evidence and record why any out-of-bundle surface was inspected.
 > - Cite file:line for every finding.
 > - Do not fabricate findings. If a rule produces no matches, emit nothing for it.
 > - Skip already-tracked findings (exact file:line + rule-slug match).
@@ -199,6 +204,7 @@ M-times-N redundant file reads and allows cross-library finding deduplication.
 > - **Library**: <library-tag>
 > - **Rule**: <rule-slug>
 > - **Confidence**: High | Medium | Low
+> - **Relevance**: Release-relevant | Ambient
 > - **Location**: `<file>:<line>`
 > - **Issue**: <one sentence>
 > - **Fix**: <specific proposed change or "needs analysis">
@@ -248,7 +254,7 @@ stage: implementing | drafting    # by gate_finding_routing
 tags: [refactor]
 parent: null
 depends_on: []
-release_binding: <version>
+release_binding: <version> | null  # null for ambient findings
 gate_origin: refactor
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
@@ -265,7 +271,7 @@ stage: implementing | drafting    # by gate_finding_routing
 tags: []
 parent: null
 depends_on: []
-release_binding: <version>
+release_binding: <version> | null  # null for ambient findings
 gate_origin: refactor
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
@@ -296,6 +302,10 @@ High | Medium | Low
 <specific proposed change, or "needs analysis" for medium/low>
 ```
 
+Release-relevant findings use the normal confidence mapping and bind to the
+release. Ambient rule violations discovered outside the bundle go to the
+unbound backlog regardless of confidence.
+
 Default confidence -> placement mapping:
 
 | Confidence | Stage | Tier |
@@ -343,7 +353,9 @@ In conversation:
 
 - **The scan happens in the scanner agent, not here.** Your job is library discovery, bundle prep,
   dispatch, and item-writing. Do not replicate the scanner's analysis.
-- Scan only the bundle's changed files, not the whole repo.
+- Release-bound files define focus, not a hard boundary. Follow concrete
+  rule-relevant evidence into adjacent or system-wide code, but do not perform
+  an unfocused whole-repo scan; route ambient findings to the unbound backlog.
 - Never apply fixes in this skill — produce items only.
 - **No-libraries is not an error.** Graceful skip with a log entry is the correct behavior when
   no scan-* libraries are installed.

package/skills/gate-security/SKILL.md

@@ -91,8 +91,8 @@ structured findings.
 > agile-workflow scanner. Use read/search/shell/current-source lookup tools as
 > needed, but do not spawn nested sub-agents or implement fixes.
 >
-> **Bundle scope** (audit ONLY these files; this is a release gate, not a
-> repo-wide audit):
+> **Bundle focus** (start here; follow concrete security-relevant call paths,
+> dependencies, shared infrastructure, and controls as needed):
 > ```
 > <bundle-files>
 > ```
@@ -138,7 +138,8 @@ structured findings.
 >       logs, missing error boundaries, verbose prod errors. All prod apps.
 >
 > 3. **Domain audit passes** — for each selected domain, audit the bundle's
->    changed files against that domain's checklist. Use current-source lookup
+>    changed files against that domain's checklist, following concrete evidence
+>    into adjacent security boundaries, dependencies, and shared controls. Use current-source lookup
 >    when needed to verify best practices for `<stack>+<domain>` combinations
 >    before judging.
 >
@@ -160,6 +161,7 @@ structured findings.
 > - **Title**: <one-line>
 > - **Severity**: Critical | High | Medium | Low
 > - **Domain**: <domain name>
+> - **Relevance**: Release-relevant | Ambient
 > - **Location**: `<file>:<line>`
 > - **Evidence**:
 >   ```<lang>
@@ -182,7 +184,8 @@ structured findings.
 > ```
 >
 > **Rules**:
-> - Audit only the files listed in Bundle scope. Do NOT expand the audit.
+> - Bundle files are the focus, not a hard boundary. Expand only along concrete
+>   security-relevant evidence and record why out-of-bundle surfaces were inspected.
 > - Cite file:line for every finding.
 > - Don't fabricate. If evidence is missing, don't report.
 > - Skip findings that match the already-tracked list.
@@ -211,7 +214,7 @@ stage: implementing      # Critical or High
 tags: [security]
 parent: null
 depends_on: []
-release_binding: <version>
+release_binding: <version> | null  # null for ambient findings
 gate_origin: security
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
@@ -237,6 +240,11 @@ Critical | High | Medium | Low
 <what should change — direction, not a finished fix>
 ```
 
+Release-relevant findings use the normal severity mapping and bind to the
+release. Ambient findings discovered outside the release's material risk go to
+the unbound backlog regardless of severity; a genuinely critical repository
+vulnerability is release-relevant when shipping would expose or perpetuate it.
+
 Default severity -> placement mapping:
 - **Critical** / **High** → `stage: implementing` in `.work/active/stories/`
 - **Medium** → `stage: drafting` in `.work/active/stories/`
@@ -271,5 +279,6 @@ In conversation:
   returns nothing. Don't paper that over.
 - Idempotent re-runs: pass already-tracked findings into the scanner brief so it
   skips duplicates. Double-check on item-write before creating.
-- Audit only the bundle's changes, not the whole repo. Repo-wide audits are
-  a standalone `repo-eval`'s job, not a release gate's.
+- Release-bound items define focus, not a hard boundary. Follow concrete
+  security evidence into adjacent or system-wide controls, but do not perform
+  an unfocused whole-repo audit. Route merely ambient findings to the unbound backlog.