@antoneeo/agentic-sdlc-skill 1.31.0 → 1.33.0

package/CHANGELOG.md

@@ -2,30 +2,139 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
-## [1.31.0] - 2026-09-05
-
-### Changed
-- **Execute-Before-Specify now covers text-about-text (SKILL.md, Phase 3).** A
-  deliverable that is itself text -- doctrine, a schema, a prompt, a reviewer
-  definition -- is probed the same way as code: replay it against the recorded
-  case that motivated it (the incident artifact, the tool-usage transcript, the
-  review that missed the defect), red under the old text, green under the new.
-  "No probe is possible" is shown, never declared. The exemption an earlier
-  proposal would have granted was rejected on evidence: the unit cited as
-  unprobeable text was a code unit that modified six production modules and
-  shipped four assertion harnesses, while doctrine and prompt changes have been
-  measured here by replay (three headless probes of a prompt change; an ad-hoc
-  checklist that caught in one round what ten rounds missed). Paid for per this
-  skill's own `vision.md` cumulative-ratchet rule: 67 words of illustration and
-  rationale deleted from the same paragraph, net -2 words.
-- **Form budget belongs to the first draft (shared spine `review.md`,
-  byte-identical x3).** The lean operative form is the FIRST draft's form, not
-  the round-3 rescue: the review request states the artifact's line count
-  against a budget the author fixed before drafting, and an artifact over budget
-  is the reviewer's first finding, before content. The ~1,250 -> ~500 line
-  measurement already in the file is its anchor. Spine delta is synced in the
-  repo; kb and mkt ship it at their next release.
-
+## [1.33.0] - 2026-09-12
+
+### Added
+- **F-048: the capability floor, and what may be delegated at all.** A review
+  run below the capability its judgement needs certifies the omission it was
+  there to catch. `review.md` now carries a floor — which tier may run which
+  role — with the rule that a tier may be lowered only where a **threshold
+  signal** scores the cheap answer, and an arbitration for the case where the
+  only independent rung sits under it (independence wins, both facts recorded).
+  `dispatch.md` gains the family-wide delegation boundary, keyed on whether a
+  pass's output is falsifiable and on its read/report ratio: a task whose brief
+  cannot be expressed as POINTERS is not delegable. `REVIEW_LOG` gains a
+  `model` column — tiers are client-relative capability levels, never provider
+  names. External evidence: cascade routing pays only where a threshold signal
+  exists, and multi-agent execution costs 3-15x the tokens and buys context
+  isolation rather than savings.
+- **F-049: the floor reaches the AUTHOR, not only the gates.** A session's
+  floor is the highest floor among the roles it performs itself, and authoring
+  a governed artifact is a deep-floor role — its output is judgement and
+  nothing downstream scores it. Fails open by construction: a session that
+  cannot determine its own tier owes nothing. The reliably working half is
+  addressed to the user, in each package's README.
+- **F-050: `benefit` — what the process caught, beside what it costs to read.**
+  The product's central claim becomes computable instead of asserted. It always
+  exits 0 and carries no verdict: a measurement that can fail a build becomes a
+  target, and a targeted measurement stops measuring.
+- **F-051: the Hybrid seam leaves the mandatory read.** The devPNT ownership
+  matrix, triage equivalence, feature-state mapping and shadow discipline move
+  to a triggered `hybrid.md`; `SKILL.md` keeps a pointer carrying the trigger
+  and the consequence. Conservation is guarded by a digest stamped in the moved
+  file and computed from the PRE-MOVE source.
+
+### Fixed
+- **F-053: nine defects a review on a DIFFERENT model found after six units
+  shipped.** Each of those six was reviewed in isolation, and each by the same
+  model family as its author; six rows reading "all findings folded" are one
+  loop, not two eyes. The scoped re-review `review.md` mandates had never been
+  run for seven unreleased rows — it has been now, late, and each row states
+  both verdicts WITH its limitation, because 35 findings across six of them
+  have no surviving per-finding record and no late round can certify them.
+  `benefit` printed "the share above is a floor, not a ceiling", which is
+  backwards — folding the post-implementation rows LOWERS the design share —
+  and excluded 46 of 117 rows in silence; it now prints a computed interval,
+  names the rows that state no count, and prints the read-cost TOTAL with the
+  support files itemised, because printing only the two terms let the one that
+  FELL be quoted while the one that GREW stayed lumped.
+- **The mechanism behind five of those units' probes, recorded as an ADR.** Ten
+  assertions across six units were satisfiable by a LITERAL, because the probe
+  looked for a SHAPE in the output instead of recomputing the VALUE and
+  comparing. Every probe over a computed output now recomputes and compares and
+  carries a positive control on synthetic data; every probe over prose is
+  labelled a wording anchor.
+
+### Read cost
+- `SKILL.md` **-7.9%** (49,413 -> 45,518 B) for a Standalone session. A Hybrid
+  L3 session reads **+5.6%** (`SKILL.md` + `hybrid.md`), and the package's
+  support files grow **+10.8%**: the cost did not fall so much as MOVE out of
+  the file the report prints. Stated here because the Vision's ceremony clause
+  counts relocated cost.
+
+## [1.32.1] - 2026-09-06
+
+### Fixed
+- **F-046 shipped a hook that wired nowhere.** `wireRemindHookInto` used the
+  ORIENT hook's opt-out marker (`orient-hook-wired`) as its own. That file is
+  present on every machine that ever installed the skill, so the installer read
+  it as "the user opted out of the per-turn reminder" and never wrote the hook —
+  for everyone. Two smaller faults in the same function: the marker was checked
+  BEFORE testing whether the hook was already present, and no marker was ever
+  written after a successful wire, so the real opt-out could never arm. The hook
+  now has its own `remind-hook-wired` marker, checked after the presence test and
+  written only on success. Regression pinned in `scripts/test_clients.js` (red
+  against 1.32.0: an orient-marked machine got no hook).
+
+## [1.32.0] - 2026-09-06
+
+### Added
+- **F-046: the protocol reaches every turn (`remind`, UserPromptSubmit, wired by
+  default).** `orient` fires once at session start and decays; a session that
+  never loads the skill never had the protocol at all. Measured 2026-09-06: a
+  release ran against a `GUIDE_release.md` the session never consulted, because
+  `SKILL.md` -- where the duty is written -- had not been read. `remind` prints
+  ONE constant line at every prompt, and its first duty is that one: decide
+  whether the skill governs the work in front of you and, if it does, LOAD it
+  once. The carrier is kb's F-041 item B, LIFTED into the shared spine rather
+  than duplicated, so all three lenses share one machine; each lens declares its
+  own line in `set_profile(remind_line=...)`. Installing the package wires it
+  machine-wide on Claude Code alongside the orientation hook, never instead of
+  it; removing the hook entry is a standing opt-out. Per-turn cost disclosed and
+  accepted by the owner (`vision/rulings.md` r19, the "no ceremony ratchet"
+  Non-Goal's second door), and bounded to stay flat by a contract the new shared
+  `scripts/test_remind.py` guards: constant text, zero reads, one line under 500
+  characters, argv ignored whole, always exit 0.
+
+### Changed
+- **`guides.md` said something false about code guides.** It claimed `stale`
+  works unchanged for `source_kind: code` because "the code-excerpt snapshot
+  drifts when the code changes". A snapshot is a frozen copy and never drifts:
+  freshness is NOT mechanized there, and the duty is the author's twice -- when
+  you MODIFY code a comprehension guide describes, and when you merely READ one
+  before trusting it. Measured 2026-09-06: the guided module had gained 388
+  lines and lost 71 across four commits with `stale` silent.
+
+- **The guide question moves to the analysis phase (SKILL.md).** Two lines in the
+  ANALYSIS -- does a CURRENT guide cover what I am about to touch, and did
+  understanding this force a model of a high-complexity component none covers.
+  The Phase-5 Comprehension checkpoint stays the backstop for a signal that only
+  became visible later; it is no longer the moment of first asking.
+
+## [1.31.0] - 2026-09-05
+
+### Changed
+- **Execute-Before-Specify now covers text-about-text (SKILL.md, Phase 3).** A
+  deliverable that is itself text -- doctrine, a schema, a prompt, a reviewer
+  definition -- is probed the same way as code: replay it against the recorded
+  case that motivated it (the incident artifact, the tool-usage transcript, the
+  review that missed the defect), red under the old text, green under the new.
+  "No probe is possible" is shown, never declared. The exemption an earlier
+  proposal would have granted was rejected on evidence: the unit cited as
+  unprobeable text was a code unit that modified six production modules and
+  shipped four assertion harnesses, while doctrine and prompt changes have been
+  measured here by replay (three headless probes of a prompt change; an ad-hoc
+  checklist that caught in one round what ten rounds missed). Paid for per this
+  skill's own `vision.md` cumulative-ratchet rule: 67 words of illustration and
+  rationale deleted from the same paragraph, net -2 words.
+- **Form budget belongs to the first draft (shared spine `review.md`,
+  byte-identical x3).** The lean operative form is the FIRST draft's form, not
+  the round-3 rescue: the review request states the artifact's line count
+  against a budget the author fixed before drafting, and an artifact over budget
+  is the reviewer's first finding, before content. The ~1,250 -> ~500 line
+  measurement already in the file is its anchor. Spine delta is synced in the
+  repo; kb and mkt ship it at their next release.
+
 ## [1.30.0] - 2026-09-01
 
 ### Added

package/README.md

@@ -16,8 +16,8 @@
 - **devPNT symbiosis**: when devPNT is available, Master Plan, Action Plan, M-VISION, and governed artifacts become the authoritative planning layer, with independent fresh-context reviews of technical artifacts and diffs.
 - **Independent review, twice**: the design is reviewed before it is implemented and the diff before the work is declared done — by somebody other than its author. Three rungs of independence (fresh-context subagent > one-shot run > a declared self-pass, legal only when no higher rung is usable: absent, or permission-gated and declined — a gated rung is asked about, never silently skipped, and the log says which), capped at 3 rounds, one log line per review, and a PASS is invalid on "found nothing" — it must state where each constraint is satisfied.
 - **Question discipline**: a question to the user is legal only when the agent searched first and names the search with its result, and names the decision the answer unblocks. Otherwise it proceeds on a declared assumption — same evidence duty, batched, never a stream of "shall I proceed?".
-- **Installed support files**: Claude, Codex, Gemini, and Google Antigravity receive the full skill folder, including `templates.md`, `architect.md`, `guides.md`, `vision.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `dispatch.md`, `routing.md`, `ENFORCEMENT.md`, and the validator's two files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py`.
-- **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates — `check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`, `migrate`.
+- **Installed support files**: Claude, Codex, Gemini, and Google Antigravity receive the full skill folder, including `templates.md`, `architect.md`, `guides.md`, `vision.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `dispatch.md`, `routing.md`, `hybrid.md`, `ENFORCEMENT.md`, and the validator's two files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py`.
+- **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates — `check`, `validate`, `index`, `stale`, `mark`, `benefit`, `gate`, `plan`, `orient`, `migrate`. `benefit` reports what the review gates have already caught, beside what the doctrine costs to read — it always exits 0 and carries no verdict, because a measurement that can fail a build becomes a target.
 
 ## Installation
 
@@ -84,6 +84,7 @@ skills/agentic-sdlc-skill/
 ├── review.md
 ├── dispatch.md
 ├── routing.md
+├── hybrid.md
 ├── ENFORCEMENT.md
 └── scripts/
     ├── sdlc_check.py
@@ -138,3 +139,32 @@ For native Gemini Agent Skills, the npm installer now copies the skill folder in
 Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo)).
 
 MIT (c) 2026 Antonio Pinto.
+
+## Which model to run it on
+
+The skill names **capability tiers**, never providers — a model name in doctrine
+rots at the next release. The binding is yours to make, and the rule is one line:
+
+> **A session's floor is the highest floor among the roles it performs itself.**
+
+Authoring a governed artifact — the vision, the analysis, the use cases, the
+threat model — is a **deep-tier** role: its output is judgement, and nothing
+downstream scores it. So a session that will DESIGN wants your strongest model.
+A session that only executes an already-approved plan, or does small maintenance,
+can sit a tier lower. The cheapest tier is the wrong choice for the main session
+whatever the task, because the failure there is not a wrong answer — it is
+**silently not applying the process**: a triage never run, a router verdict
+declared without the lookup, a gate nobody noticed. That failure is invisible to
+every check in here.
+
+**The reviewer's tier is not automatically yours.** On some clients a subagent
+inherits the session's model; on others it takes one from its own definition, so
+a strong session can be reviewed by a weak one — and a weak session can buy a
+strong review. Set it deliberately; the
+`model` column in the review log is where the choice becomes visible.
+
+**Avoid one combination**: authoring below the floor AND reviewing below the floor
+on the same unit. One disclosed weakness is a disclosed weakness; two is an
+artifact nobody competent ever read. Where your client offers nothing better, the
+review still runs and both facts are recorded — a disclosed worst case beats
+skipping the review.

package/gemini-extension.json

@@ -1,6 +1,6 @@
-{
-  "name": "agentic-sdlc-skill",
-  "version": "1.31.0",
-  "description": "Documentation-First SDLC protocol with triage, Vision governance and optional devPNT integration.",
-  "author": "Antonio Pinto (https://github.com/Antoneeo)"
-}
+{
+  "name": "agentic-sdlc-skill",
+  "version": "1.33.0",
+  "description": "Documentation-First SDLC protocol with triage, Vision governance and optional devPNT integration.",
+  "author": "Antonio Pinto (https://github.com/Antoneeo)"
+}

package/package.json

@@ -1,50 +1,51 @@
-{
-  "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.31.0",
-  "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
-  "keywords": [
-    "claude-code",
-    "claude-skill",
-    "gemini-cli",
-    "skill",
-    "sdlc",
-    "documentation",
-    "ai-agent"
-  ],
-  "author": "Antonio Pinto (https://github.com/Antoneeo)",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "agentic-sdlc-init": "scripts/init.js",
-    "agentic-sdlc-install-skill": "scripts/postinstall.js"
-  },
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "preuninstall": "node scripts/preuninstall.js"
-  },
-  "files": [
-    "skills/agentic-sdlc-skill/SKILL.md",
-    "skills/agentic-sdlc-skill/templates.md",
-    "skills/agentic-sdlc-skill/architect.md",
-    "skills/agentic-sdlc-skill/guides.md",
-    "skills/agentic-sdlc-skill/vision.md",
-    "skills/agentic-sdlc-skill/tdd.md",
-    "skills/agentic-sdlc-skill/debugging.md",
-    "skills/agentic-sdlc-skill/elicitation.md",
-    "skills/agentic-sdlc-skill/review.md",
-    "skills/agentic-sdlc-skill/dispatch.md",
-    "skills/agentic-sdlc-skill/routing.md",
-    "skills/agentic-sdlc-skill/ENFORCEMENT.md",
-    "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
-    "skills/agentic-sdlc-skill/scripts/sdlc_core.py",
-    "gemini-extension.json",
-    "README.md",
-    "CHANGELOG.md",
-    "scripts/lib.js",
-    "scripts/init.js",
-    "scripts/postinstall.js",
-    "scripts/preuninstall.js"
-  ]
-}
+{
+  "name": "@antoneeo/agentic-sdlc-skill",
+  "version": "1.33.0",
+  "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
+  "keywords": [
+    "claude-code",
+    "claude-skill",
+    "gemini-cli",
+    "skill",
+    "sdlc",
+    "documentation",
+    "ai-agent"
+  ],
+  "author": "Antonio Pinto (https://github.com/Antoneeo)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "agentic-sdlc-init": "scripts/init.js",
+    "agentic-sdlc-install-skill": "scripts/postinstall.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "preuninstall": "node scripts/preuninstall.js"
+  },
+  "files": [
+    "skills/agentic-sdlc-skill/SKILL.md",
+    "skills/agentic-sdlc-skill/templates.md",
+    "skills/agentic-sdlc-skill/architect.md",
+    "skills/agentic-sdlc-skill/guides.md",
+    "skills/agentic-sdlc-skill/vision.md",
+    "skills/agentic-sdlc-skill/tdd.md",
+    "skills/agentic-sdlc-skill/debugging.md",
+    "skills/agentic-sdlc-skill/elicitation.md",
+    "skills/agentic-sdlc-skill/review.md",
+    "skills/agentic-sdlc-skill/dispatch.md",
+    "skills/agentic-sdlc-skill/hybrid.md",
+    "skills/agentic-sdlc-skill/routing.md",
+    "skills/agentic-sdlc-skill/ENFORCEMENT.md",
+    "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
+    "skills/agentic-sdlc-skill/scripts/sdlc_core.py",
+    "gemini-extension.json",
+    "README.md",
+    "CHANGELOG.md",
+    "scripts/lib.js",
+    "scripts/init.js",
+    "scripts/postinstall.js",
+    "scripts/preuninstall.js"
+  ]
+}

package/scripts/lib.js

@@ -639,6 +639,105 @@ function removeGlobalOrientHooks(removedRoots) {
   return removedFrom;
 }
 
+// --- Per-turn reminder hook (F-046) ----------------------------------------
+// `orient` fires once and decays; a session that never loads the skill never
+// had the protocol at all. This hook re-arms one constant line every prompt.
+// It is wired ALONGSIDE the orient hook and never instead of it, and it is its
+// own function because `wireOrientHook` returns early when the session hook is
+// already there -- which is the state of every existing installation.
+// Owner-accepted per-turn cost: `ai_docs/vision/rulings.md` r19.
+
+const REMIND_HOOK_TIMEOUT = 5;
+
+function remindHookCommand(python, validator) {
+  return python + ' "' + validator + '" remind';
+}
+
+function findRemindHook(settings) {
+  const groups = settings && settings.hooks && settings.hooks.UserPromptSubmit;
+  if (!Array.isArray(groups)) return null;
+  for (const group of groups) {
+    if (!group || typeof group !== 'object') continue;
+    const inner = Array.isArray(group.hooks) ? group.hooks : [group];
+    for (const h of inner) {
+      const cmd = h && typeof h.command === 'string' ? h.command : '';
+      if (ORIENT_ENTRY_POINTS.some((n) => cmd.includes(n)) && / remind(\s|$)/.test(cmd)) {
+        return cmd;
+      }
+    }
+  }
+  return null;
+}
+
+// Writes the hook into `target` (an already-chosen settings file) unless it is
+// there or the user opted out. Returns a code, never throws: an installer must
+// not die on someone's settings file.
+function remindMarkerPath() {
+  const root = process.env.AGENTIC_SDLC_KB_ROOT
+    || path.join(os.homedir(), '.agentic-sdlc');
+  return path.join(root, 'remind-hook-wired');
+}
+function remindMarkerTargets() {
+  try {
+    return fs.readFileSync(remindMarkerPath(), 'utf8')
+      .split(/\r?\n/).map((x) => x.trim()).filter(Boolean);
+  } catch (e) {
+    return [];
+  }
+}
+function remindMarkerHas(target) {
+  return remindMarkerTargets().some((t) => pathsEqual(t, target));
+}
+function remindMarkerAdd(target) {
+  try {
+    if (remindMarkerHas(target)) return;
+    fs.mkdirSync(path.dirname(remindMarkerPath()), { recursive: true });
+    fs.appendFileSync(remindMarkerPath(), target + String.fromCharCode(10), 'utf8');
+  } catch (e) { /* fail-open */ }
+}
+
+function wireRemindHookInto(target, python, validator) {
+  if (!python) return { code: 'no-python' };
+  if (!validator || ORIENT_UNSAFE_IN_PATH.test(validator)) return { code: 'unsafe-path', validator };
+  const state = orientSettingsState(target);
+  if (!state.ok) return { code: 'malformed', target, why: state.why };
+  const settings0 = state.settings;
+  // Order matters, and the first version had it wrong too: the hook being
+  // PRESENT is `already`, and only its ABSENCE plus our marker means the user
+  // removed it -- a standing opt-out. Marker-first would refuse to re-check a
+  // hook someone still has.
+  const present = findRemindHook(settings0);
+  if (present) return { code: 'already', target, command: present };
+  if (remindMarkerHas(target)) return { code: 'opted-out', target };
+  const settings = settings0;
+  const existing = null;
+  if (existing) return { code: 'already', target, command: existing };
+  const command = remindHookCommand(python, validator);
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.UserPromptSubmit)) settings.hooks.UserPromptSubmit = [];
+  settings.hooks.UserPromptSubmit.push({
+    hooks: [{ type: 'command', command, timeout: REMIND_HOOK_TIMEOUT }],
+  });
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, JSON.stringify(settings, null, 2) + String.fromCharCode(10), 'utf8');
+  } catch (e) {
+    return { code: 'write-failed', target, command, error: e.message };
+  }
+  remindMarkerAdd(target);
+  return { code: 'wired', target, command };
+}
+
+
+// The machine-global twin of wireGlobalOrientHook, same target and validator.
+function wireGlobalRemindHook(options) {
+  const client = options.client;
+  const validator = path.join(skillTarget(client), 'scripts', ORIENT_ENTRY_POINT);
+  if (!fs.existsSync(validator)) return { code: 'no-validator', validator };
+  return wireRemindHookInto(path.join(client.home, 'settings.json'), options.python, validator);
+}
+
+
 module.exports = {
   PACKAGE_ROOT,
   SKILL_SOURCE,
@@ -649,6 +748,12 @@ module.exports = {
   clientDetected,
   skillTarget,
   wireOrientHook,
+  wireRemindHookInto,
+  wireGlobalRemindHook,
+  remindMarkerHas,
+  remindMarkerAdd,
+  remindHookCommand,
+  findRemindHook,
   wireGlobalOrientHook,
   removeGlobalOrientHooks,
   detectPython,

package/scripts/postinstall.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const {
   SKILL_SOURCE, CLIENTS, clientDetected, skillTarget, copyRecursive,
-  wireGlobalOrientHook, detectPython,
+  wireGlobalOrientHook, wireGlobalRemindHook, detectPython,
 } = require('./lib');
 
 function installSkill(client) {
@@ -39,6 +39,18 @@ for (const client of CLIENTS) {
     // marker remembers. A convenience must never fail an npm install: wrapped.
     if (client.key === 'claude' && installed) {
       try {
+        // F-046: the per-turn reminder, wired alongside and never instead of
+        // the session hook. `orient` decays; this one re-arms one constant line
+        // every prompt, and its first duty is the one that was missing -- decide
+        // whether the skill governs the work and, if so, load it once, because
+        // an unread protocol cannot be applied. Owner-accepted per-turn cost:
+        // ai_docs/vision/rulings.md r19.
+        const rr = wireGlobalRemindHook({ client, python: detectPython() });
+        if (rr.code === 'wired') {
+          console.log('🔗 Per-turn protocol reminder wired for every project on this machine');
+          console.log(`   (${rr.target}). One constant line per prompt; remove that hook`);
+          console.log('   entry to opt out — it will not be re-added.');
+        }
         const r = wireGlobalOrientHook({ client, python: detectPython() });
         if (r.code === 'wired') {
           console.log('🔗 Session orientation wired for every project on this machine');

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

@@ -57,7 +57,7 @@ Semantics: exit code 2 + message on stderr ⇒ the write is blocked and the mess
 - The paths in `--protected` are prefixes relative to the project root, separated by `;`.
 - `ai_docs/`, `tests/` and `test/` are always excluded from blocking.
 - The hook assumes the working directory is the project root (standard behavior of Claude Code hooks).
-- **Hybrid/devPNT projects**: add `--hybrid` to the gate command. Governed designs live in the devPNT DB, so the gate also unlocks when an approved E-TDD shadow (`ai_docs/solutions/SHADOW_*tdd*.md`, exported before implementation — see the SKILL.md shadow discipline) is present. Without the flag the gate would block legitimate governed work. The flag is deliberately explicit: never auto-detected.
+- **Hybrid/devPNT projects**: add `--hybrid` to the gate command. Governed designs live in the devPNT DB, so the gate also unlocks when an approved E-TDD shadow (`ai_docs/solutions/SHADOW_*tdd*.md`, exported before implementation — see `hybrid.md` §Shadow discipline) is present. Without the flag the gate would block legitimate governed work. The flag is deliberately explicit: never auto-detected.
 
 ## 4. SessionStart hook (orientation, recommended default)
 
@@ -157,6 +157,46 @@ Gemini CLI — wire the same command into its startup-hook mechanism if present;
 - **Hybrid/devPNT projects**: add `--hybrid` — the hook then appends a one-line pointer to run `devpnt_mcp_get_bootstrap` for the Master Plan / Knowledge Layer and does not replicate them; the filesystem orientation (router + handoff + README) still emits.
 - Like the CI gate (§2), if you copied the validator into the repo, the hook references that copy — keep both files current when you update the skill.
 
+### Per-turn reminder: `remind` (UserPromptSubmit -- wired by default)
+
+`orient` fires once, at session start; a long session drifts after it, and a session
+that never loads the skill never had the protocol at all. Measured (F-046, 2026-09-06):
+a release ran against a `GUIDE_release.md` the session never consulted, because
+`SKILL.md` -- where the duty is written -- had not been read. `sdlc_check.py remind` prints
+ONE constant line at every prompt, and its first duty is that one: decide whether the
+skill governs the work in front of you and, if it does, load it once.
+
+Cost: 478 characters, ~80 tokens per prompt, paid on every turn including
+trivial ones. That is admissible only because the owner accepted it explicitly
+(`ai_docs/vision/rulings.md` r19, the "no ceremony ratchet" Non-Goal's second door) --
+and the acceptance was for a FLAT cost. Hence the contract, guarded by
+`scripts/test_remind.py`: the line is **constant and reads nothing** (so nothing repo-
+or session-controlled rides into the agent's context through it, and the cost cannot
+grow with the session), it is **one line under 500 characters**, and it **can never
+break a prompt** (argv ignored whole, always exit 0). A trivial turn pays a yes/no
+judgement, never a load.
+
+Installing the package wires it machine-wide on Claude Code, alongside the orientation
+hook and never instead of it; **removing that hook entry is a standing opt-out.** To
+wire it by hand:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"C:\Users\<user>\.claude\skills\agentic-sdlc\scripts\sdlc_check.py\" remind"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
 ## 5. Skill eval battery (release gate)
 
 **Skill development only.** `test_*.py` and `evals/` are deliberately absent from the npm `files` allowlist — they never reach an installed consumer, so this section applies to whoever builds the skill, not to a project that uses it. (Consumers get `sdlc_check.py` + `sdlc_core.py`; §1–§4 are theirs.)
@@ -176,3 +216,12 @@ It aggregates the test files (`test_plan.py` + `test_session_start.py` + `test_s
 **Optional CI** (same shape as §2, not mandatory): add a `run:` step invoking the `unittest discover` command above.
 
 **T10 note:** if you copied the validator (both files) and the `test_*.py` battery into the repo for CI, that copy is authoritative — keep it current when you update the skill.
+
+## `benefit` is a report, never a CI gate
+
+`sdlc_check.py benefit` reports what the review gates caught and what the
+doctrine costs to read. It always exits 0 and emits no warning: **never wire
+it into CI**. It is the criterion by which future units are judged, and a
+measurement that can fail a build becomes a target -- a targeted measurement
+stops measuring. Run it when deciding whether a proposed rule is worth its
+ceremony, not on every push.