@antoneeo/agentic-sdlc-skill 1.31.0 → 1.33.0

package/skills/agentic-sdlc-skill/dispatch.md

@@ -45,12 +45,50 @@ below — so it needs no separate dispatch hook.)
 
 ## Model tiers (client-relative, no provider names)
 
-- Default dispatch: **economy** implementer tier.
+- Default dispatch: **economy** implementer tier. This is legal precisely
+  because a dispatched task carries `task.verify` — the threshold signal that
+  makes a wrong cheap answer visible. **The floor that governs every role, and
+  the rule that a tier may be lowered only where such a signal exists, is
+  `review.md` §The capability floor** — cited, never restated here.
 - After **two** consecutive `verify_result: fail` on the same task: escalate
   to the **deep** tier for the retry (ADR 2026-07-02). Do not escalate on the
   first failure — a single fail is often a brief or environment issue, not a
   capability gap.
 
+## What may be delegated at all
+
+The sections above govern the opt-in PLAN loop; **this one is family-wide** and
+applies to any pass, at any level, dispatch or no dispatch. Delegation is not a
+token-saving technique — a second context re-reads, re-briefs and reports back,
+so the total spend goes UP. What it buys is a main context that stays clean, and
+independence where independence is the point. Judge a pass on two axes:
+
+| | output falsifiable cheaply (`file:line`, an assertion result, a diff) | output is judgement |
+|---|---|---|
+| **reads ≫ report** | **delegate** — the whole win lives here | **never**: the biggest apparent win is where plausible-but-wrong enters |
+| **reads ≈ report** | keep it: the brief costs more than the pass | keep it |
+
+- **Delegate**: locating and verifying (a pass that returns citable facts and
+  discards its exploration trace), executing a probe or battery and reporting
+  the assertion table, and every independent review — the last for correctness,
+  not economy, and it is mandatory regardless of what it costs.
+- **Never delegate**: authoring a governed artifact (Vision, ANALYSIS/E-ISP,
+  threat model, use cases, the Interface Contract), the triage level and router
+  verdict, a reconciliation or scope decision, and any pass whose result the
+  orchestrator must hold across many later turns — delegating that one just
+  moves the reading into the main context via the report.
+- **The delegability condition**: a task whose brief cannot be expressed as
+  **pointers** — paths, ids, a command — is **not delegable** yet; a brief that
+  must carry the content pays those tokens twice, once to write it and once to
+  read it. `plan brief` is this rule already realized for the PLAN loop (it
+  prints `guides` as paths, never pasted content); the condition generalizes it.
+
+**Declared residual**, so the silence is not read as prohibition: this section
+settles the CLASSIFICATION. *When* to reach for a delegated search or
+orientation pass — the trigger, its brief format and its output contract — is a
+separate unit and is not answered here; until it lands, reaching for one is the
+orchestrator's judgement against the table above, not a rule.
+
 ## Review slots — one-shot, not iterative
 
 Exactly three review touches per task, never a loop:

package/skills/agentic-sdlc-skill/guides.md

@@ -60,6 +60,10 @@ already cover how to do this well?*
   match was not targeted (T7). Two guides are legitimate only when they cover
   distinct concerns — typically an operative guide plus the comprehension map of
   the component being touched; three is a smell, not a thorough lookup.
+- **Check a `code` guide against the code before you trust it.** No check can do
+  this for you (§6): the reader is the only one who sees that the map and the
+  component have parted. A divergence you observe is yours to close in the same
+  unit of work.
 - **Under subagent dispatch** the consult happens at plan-authoring time (the
   orchestrator populates each task's `guides` field); a context-free subagent
   reads the pointers it was handed and does not run its own router lookup. See
@@ -271,17 +275,17 @@ state it explicitly when handing off a newly created guide.
 
 ## 6. Maintenance
 
-- **Source changed**: create a new snapshot (new hash), regenerate the guide
-  from it (new `source_hash`), and if the guide is replacing a prior guide
-  rather than updating in place, mark the old one `status: SUPERSEDED`.
-- **`stale` flags hash drift**: `sdlc_check.py stale` (also under `--hybrid`)
-  compares each guide's recorded `source_hash` against the live snapshot file
-  and reports `[stale]` when they diverge — that is the signal to regenerate,
-  not a manual freshness check.
-- **`source_kind: code` freshness**: `stale` works unchanged (the code-excerpt
-  snapshot drifts when the code changes → regenerate). ADDITIONALLY, when you modify
-  the code a comprehension guide describes, refresh that guide in the SAME closure
-  (docs travel with the code) — do not wait for `stale` to catch it. A stale
-  comprehension guide is a confident-wrong map, worse than none.
+- **Source changed**: new snapshot, regenerate the guide from it (new
+  `source_hash`); a guide REPLACING another is `status: SUPERSEDED` on the old
+  one. `sdlc_check.py stale` (also under `--hybrid`) reports `[stale]` when a
+  guide's recorded hash and its snapshot file diverge — the signal to regenerate.
+- **`source_kind: code` freshness is NOT mechanized.** `stale` compares the guide
+  to its snapshot, and a code snapshot is a frozen copy — so a map whose component
+  was rewritten reports FRESH forever (measured 2026-09-06: +388/-71 lines in the
+  guided module, `stale` silent). The duty is therefore the author's, twice: when
+  you MODIFY code a comprehension guide describes, refresh the guide in the same
+  closure (docs travel with the code); when you merely READ one, check it against
+  the code before trusting it. Too large to absorb → mark it `SUPERSEDED` rather
+  than leave a confident-wrong map badged CURRENT, which is worse than none.
 - **Agent-global KB guides** use the same pipeline and validator via
   `--root ~/.agentic-sdlc`; freshness via the same `stale` engine.

package/skills/agentic-sdlc-skill/hybrid.md

@@ -0,0 +1,106 @@
+# The Hybrid Seam — coexistence with devPNT
+
+**For whom**: the agent working a project where the `devpnt_*` tools are available
+and point at this project.
+**Answers**: "which mode am I in, who owns what when both authorities are live,
+and how do the two vocabularies map onto each other".
+**Does not answer**: the process itself — triage, the phases, the gates and the
+write triggers are `SKILL.md`'s, and they are identical in both modes.
+
+Moved out of `SKILL.md` by F-051 so a Standalone session stops paying for a seam
+it cannot reach. **The content below is unchanged**: this file is a relocation,
+not a rewrite.
+
+<!-- moved-block-sha256: f11e6d5b9cd4710849fa9d3701f16ff0da39f2d163e8ffdb8adbff6a119b3614 -->
+### Hybrid in symbiosis with devPNT
+
+Use this mode when the `devpnt_*` tools are available and point at the current project.
+
+Authoritative hierarchy:
+1. **devPNT M-VISION**: strategic beacon of the milestone. Before design or code, read it and verify benefits, success signals, scope-in and non-goals.
+2. **devPNT Master Plan**: strategic roadmap and milestones.
+3. **devPNT Action Plan**: current tactical work for the active goal.
+4. **devPNT governed artifacts**: `D-UC`, `P-TM`, `E-ISP`, `E-TDD`, `E-TP`, ADR.
+5. **Local `ai_docs/`**: readable context, Standalone fallback, local handoff or shadow/mirror when useful.
+
+Hybrid rules:
+- devPNT is the governed source for plans and artifacts; do not create a second truth in `ai_docs/`.
+- The skill stays autonomous: if devPNT is not there, switch to Standalone without losing capability.
+- If the user request, the local Vision and the M-VISION diverge, stop and make the conflict explicit.
+- Do not create or modify milestones without respecting the M-VISION.
+- Never auto-accept devPNT proposals: present the preview and wait for explicit confirmation.
+- If the local devPNT protocol imposes stricter bootstrap, plans or gates, follow them.
+
+## Coexistence with devPNT (the Hybrid seam)
+
+This section is the single authoritative answer to "who owns what" when both the
+skill and devPNT are active. The skill owns the **process** (triage, phases, Vision
+Gate, lifecycle); devPNT owns the **machinery** (governed storage, versioned
+proposals, semantic analysis, independent reviewers). devPNT strengthens the
+process; it never replaces it.
+
+### Ownership matrix
+
+| Artifact | Standalone master | Hybrid master | Mirror rule |
+|---|---|---|---|
+| Product vision | `vision/project_vision.md` | `vision/project_vision.md` (product scope) | devPNT KL vision is regenerated from it, never edited independently |
+| Milestone vision | `vision/roadmap.md` milestones | devPNT M-VISION | `roadmap.md` may reference the M-VISION key; it never restates its content |
+| Feature design | `solutions/ANALYSIS_[feature].md` | devPNT E-ISP/E-TDD (+ D-UC/P-TM) | shadow exported from the ACCEPTED DB version as `SHADOW_[doc_key]_vX.Y.md`; on divergence the DB wins and the shadow is regenerated |
+| Plans | `## Action Plan` inside the ANALYSIS | devPNT Master/Action Plan | none |
+| Feature state | ANALYSIS frontmatter `status` | Action Plan node status | mapping table below; at closure both must move together |
+| ADR | `architecture/` (canonical dir) | devPNT DB (`adr_YYYY-MM-DD_slug`) | optional filesystem shadow `SHADOW_adr_*` exported at closure for grep-ability |
+| Audit / freshness | `audit/audit_plan.md` + `stale`/`mark` | devPNT KL coverage + summary status | run `check --hybrid` (skips audit-plan staleness) |
+| Design review (pre-implementation) | `review.md` moment 1, on the ANALYSIS | devPNT §4.5 gate on `E-ISP`/`E-TDD` | same slot, richer backend — run ONE of them, never both |
+| *(mode is per unit of change, not per project)* | a Hybrid-capable project may work one feature Standalone: the slot follows the ARTIFACT the design lives in, and the mode is declared in that artifact. `validate --hybrid` suppresses the Standalone design-review backstop, since devPNT owns the slot there | | |
+| Review log | `audit/reviews/REVIEW_LOG.md` | devPNT `REVIEW_LOG.md` (same path) | always filesystem |
+| Operative guides | `ai_docs/reference/` | `ai_docs/reference/` — **filesystem-first even in Hybrid** | devPNT bootstrap may point at their index; it never copies their content |
+| Handoff | `audit/handoff.md` | `audit/handoff.md` | always filesystem |
+
+### Triage equivalence (one threshold, two vocabularies)
+
+devPNT's "significance threshold" and the skill's triage are the SAME test. Do not
+run two classifications:
+
+| Skill triage | devPNT equivalent | Governed artifacts |
+|---|---|---|
+| L1 Trivial | trivial exempt | none |
+| L2 Small | localized obvious edit | none — but see escalation |
+| L3 Significant | governed unit of change | D-UC/P-TM/E-ISP/E-TDD per the devPNT trigger policy |
+| Spike | exempt (non-mergeable) | `SPIKE_[topic].md` only |
+
+Escalation triggers (any one of these makes it L3, in BOTH vocabularies): touches
+more than one module, changes a public API/contract/message format, changes a data
+model or state machine, has a security surface, risks duplicating existing logic,
+or the design choice is non-obvious. An L2 that trips one of these is not an L2.
+
+### Feature state mapping
+
+| ANALYSIS frontmatter | devPNT plan node |
+|---|---|
+| PLANNED | READY (or BLOCKED / ON_HOLD while waiting) |
+| IN_PROGRESS | PROGRESS |
+| COMPLETED | DONE |
+| CANCELLED | CANCELLED |
+
+Closure discipline: never mark the node DONE while the shadow/ANALYSIS still says
+IN_PROGRESS, or vice versa. They move in the same closure step.
+
+### Shadow discipline (Hybrid)
+
+- Shadow filename: `SHADOW_[doc_key]_vX.Y.md`, first line
+  `<!-- SHADOW generated from devPNT (doc_key vX.Y) - do not edit by hand -->`.
+  Never save a shadow under an `ANALYSIS_*` name: that name means "authoritative
+  Standalone document" and the validator treats it as such.
+- **Export the approved E-TDD shadow BEFORE implementation** (not only at closure).
+  It gives context-free subagents their design input, unlocks `gate --hybrid`, and
+  guarantees the filesystem fallback if devPNT becomes unavailable mid-feature.
+- At closure, refresh all shadows from the accepted DB versions.
+
+### Validator in Hybrid
+
+Pass `--hybrid` explicitly (never auto-detected — an explicit flag beats a guessed
+mode): `check --hybrid` and `stale --hybrid` skip audit-plan staleness (mapping is
+delegated to devPNT/KL) — guide-drift checking still runs (`ai_docs/reference/`
+is filesystem-first even in Hybrid, see the ownership matrix above); `gate --hybrid`
+also unlocks on the presence of an E-TDD shadow in `solutions/` (the Hybrid design
+gate) instead of requiring an IN_PROGRESS ANALYSIS.

package/skills/agentic-sdlc-skill/review.md

@@ -82,15 +82,92 @@ its outcome. The trigger term "permission-gated" scopes the STOP; the row word
 
 Use a different model from the author's where the client allows it.
 
+**The capability floor — which tier may run this role.** Independence says the
+reviewer must not be the author; it says nothing about whether the reviewer *can
+do the job*. A gate run below the capability its judgement needs produces the
+myopia the gate exists to catch, **while reporting as an independent review** —
+worse than no gate, because it certifies. So each role carries a minimum tier.
+Tiers are **client-relative capability levels, never provider names** (a name
+rots at the next model release; the tier→model binding lives in the client's own
+agent definition, never in this file):
+
+| Role | Floor | Why there |
+|---|---|---|
+| **authoring a governed artifact** (Vision, the analysis/design, use cases, the Interface Contract, threat model — `dispatch.md`'s never-list owns the enumeration) | **deep** | the purest case of the rule below: the output is judgement, nothing scores it, and `dispatch.md`'s never-list forbids moving it elsewhere — so the session's own capability IS this work's capability |
+| design review, closure review, any verdict on judgement | **deep** | the output is a judgement whose wrongness no check can see |
+| a light conformance or consistency pass (schema, coverage, citation resolution) | **light** | the criterion is stated and mechanical |
+| implementer dispatch, probe execution, anchor resolution, index regeneration | **economy** | a threshold signal catches a wrong cheap answer |
+
+The rule underneath the table: **a tier may be lowered only where a threshold
+signal exists** — `task.verify`, a test, a diff against a spec, an assertion
+harness — because that is what makes a wrong cheap answer visible instead of
+plausible. Where the output is judgement and nothing scores it, there is no
+signal to lower against, and the floor is the whole policy.
+
+**A session's floor is the highest floor among the roles it performs itself.** The
+table above binds reviewers and dispatched subagents, chosen per call — but the
+session doing the authoring was chosen by the USER before the agent existed, and
+an agent cannot re-tier itself mid-session. So the rule that reaches it is not
+routing, it is **disclosure**: where a session can determine that it is below the
+floor for a role it performs itself, it says so **once per session, at the first
+such role** — not once per unit — and the disclosure is repeated in the review
+row's existing `reviewer` cell (Hybrid: `notes`), which is what makes the pair
+below visible without adding a column.
+
+**Say plainly how thin this reach is.** A session knows its model NAME; tiers here
+are deliberately client-relative and this file maps no name to a tier, so the
+antecedent is satisfiable only where a session can recognize its own tier — which
+is also the session least likely to run the check. Where a session **cannot
+determine its own tier**, it owes nothing: the rule binds what an agent can know
+and say, never a capability it cannot acquire. **The reliably working half of this
+rule is the one addressed to the user, not to the agent** — which is why the
+package READMEs carry the tier-selection guidance, and why that is not a footnote.
+
+**Never both below the floor on the same unit — except when nothing better
+exists.** Where the authoring session ran below floor, the independent review's
+floor becomes non-negotiable and the same unit should not ALSO run a below-floor
+review. **The exception is the case *When independence and capability conflict*
+governs below**: where no independent rung at or above the floor exists at all,
+that rule wins, the review still runs, BOTH disclosures are recorded, and the
+result is not a violation but the worst admissible state — honestly labelled.
+Forbidding it outright would push the agent toward the abstention that rule
+explicitly rejects.
+
+**When independence and capability conflict, independence wins.** A client whose
+only independent rung is bound below the floor (a single-model client, or a
+subagent facility whose agent definition fixes a cheap model) still runs the
+gate: a below-floor *independent* reviewer catches the class the author is
+structurally blind to, while a self-pass catches none of it. What the floor then
+requires is **disclosure, not abstention** — the row records the tier that
+actually ran (`below floor: <reason>`), and that record IS the remedy. Where a
+higher-capability path exists but is permission-gated, nothing new applies: *The
+gated rung* above already governs, one question per gate per intact context.
+Where the client exposes no capability choice at all, the row says
+`single (client exposes no choice)` and the floor is satisfied by construction —
+it is a routing rule, and a routing rule with one route is not a failure.
+
 **Rounds are capped at 3.** FAIL → revise → re-review. If findings still stand
 after the third, stop and surface them to the user with the artifact — a gate that
 can block forever gets removed. **Log one row per completed review, PASS or FAIL**
 — a FAIL surfaced to the user is the highest-value outcome the gate produces, and
 logging only passes would erase exactly that evidence. The row goes in
 `ai_docs/audit/reviews/REVIEW_LOG.md` (create it if absent — `templates.md`):
-`| date | doc_key | tier | reviewer | findings_raised | findings_real | verdict | revise_rounds |`,
-with `tier` = `design` or `closure` in Standalone. One schema for both modes: a
-Hybrid project's devPNT gates write to the same file.
+`| date | doc_key | tier | model | reviewer | findings_raised | findings_real | verdict | revise_rounds |`,
+with `tier` = `design` or `closure` in Standalone. **`model` records the capability
+tier that actually ran** — `deep`, `light`, `economy`, `single (client exposes no
+choice)`, or `below floor: <reason>` — never a provider name in doctrine (a project
+may of course write its own model names in its own log). Without it the floor above
+is a belief: the row would say a gate ran and never whether it could do its job, and
+the correlation with `revise_rounds` and `findings_real` — the only evidence the
+policy pays — could not be drawn.
+
+**One schema for both modes**, meaning one required CORE plus each mode's own
+**mode-specific** realization columns. The core is what both modes actually share: `date`, `doc_key`,
+`tier`, `model`, `findings_raised`, `findings_real`, `verdict`, `revise_rounds`.
+Around it, Standalone adds `reviewer` and Hybrid adds `instrument` and `notes` —
+a devPNT row carries no `reviewer` column at all, so "one identical column list"
+was never true of the two modes. This costs nothing for the reason `templates.md`
+§`ai_docs/audit/reviews/REVIEW_LOG.md` owns and states.
 The log is how the gate's value is measured over time; skipping it makes the gate
 unfalsifiable, the same defect as an unnamed EXISTS or a faked router verdict.
 

package/skills/agentic-sdlc-skill/scripts/sdlc_check.py

@@ -13,7 +13,7 @@ image, copy BOTH (`ENFORCEMENT.md` §2 has the recipe); copying this one alone
 fails at import, loudly and immediately, which is the intended failure.
 
 Usage is `sdlc_core.py`'s: check / validate / index / stale / mark / gate /
-orient / plan.
+orient / benefit / plan.
 """
 import sys
 from pathlib import Path
@@ -50,7 +50,7 @@ sdlc_core.set_profile(
     unit_noun="feature",
     support_files=("templates.md", "architect.md", "guides.md", "vision.md", "tdd.md",
                    "debugging.md", "elicitation.md", "review.md", "dispatch.md",
-                   "routing.md", "ENFORCEMENT.md"),
+                   "routing.md", "hybrid.md", "ENFORCEMENT.md"),
     capabilities=(
         # spine
         "triage", "write_triggers", "workstream_registry", "vision_gate",
@@ -60,6 +60,15 @@ sdlc_core.set_profile(
         "subagent_dispatch", "legacy_narrative_handoff", "question_discipline",
     ),
     design_gate_between=("### 3. Request Analysis", "### 4. Development and Testing"),
+    remind_line=(
+        "first decide if this skill governs the work; if yes, LOAD it once -- an "
+        "unread protocol cannot be applied. Declare the level (L1/L2/L3/Spike) "
+        "and the guide-router verdict before acting; an imperative is a request "
+        "to triage. Name the mechanism before fixing the first defect you can "
+        "measure -- symptom patches recur and stack. Replay governing text -- "
+        "doctrine, a prompt, a schema -- against the case that motivated it: red "
+        "under the old text, green under the new."
+    ),
 )