@antoneeo/agentic-sdlc-skill 1.32.0 → 1.34.0

package/CHANGELOG.md

@@ -2,6 +2,93 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.34.0] - 2026-09-14
+
+### Changed
+- **F-055: Apache-2.0 with a NOTICE, in place of MIT.** The package root and the
+  installed skill folder now carry `LICENSE` (the Apache-2.0 text) and `NOTICE`
+  (the attribution), and `package.json` and the `SKILL.md` frontmatter say
+  `Apache-2.0`. Redistributing the skill, or a version you modified, means keeping
+  both files. Using it in your own project carries no obligation: the documents it
+  creates or templates there are yours, and so is a copy of the validator and its
+  tests placed there to check them (README, License). Versions up to 1.33.0 remain
+  available under MIT. The README also asks, as a request and not a condition,
+  for a mention when the skill is used in commercial work.
+
+## [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

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+Agentic SDLC skill family
+Copyright 2026 Antonio Pinto
+
+This product includes software developed by Antonio Pinto
+(https://github.com/Antoneeo/agentic-sdlc-skill).

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` — plus the `LICENSE` and `NOTICE` it ships under.
+- **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,7 +84,10 @@ skills/agentic-sdlc-skill/
 ├── review.md
 ├── dispatch.md
 ├── routing.md
+├── hybrid.md
 ├── ENFORCEMENT.md
+├── LICENSE
+├── NOTICE
 └── scripts/
     ├── sdlc_check.py
     └── sdlc_core.py
@@ -137,4 +140,47 @@ 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.
+## License
+
+Apache-2.0 — the full terms are in the `LICENSE` file, the attribution in `NOTICE`. Copyright 2026 Antonio Pinto.
+
+If you redistribute this skill, or a version you modified, keep `LICENSE` and `NOTICE` with it.
+
+Using the skill in your own project carries no obligation: the documents it creates or templates there are yours, and so is a copy of the validator and its tests placed in that project to check its own documents.
+
+Versions up to 1.33.0 were released under the MIT license and remain available under it.
+
+If you use the skill in commercial work, a mention on your product page or website is appreciated. It is a request, not a condition of the license. A ready-made badge:
+
+```markdown
+[![Made with agentic-sdlc](https://img.shields.io/badge/made%20with-agentic--sdlc-blue)](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill)
+```
+
+## 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.32.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.34.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,54 @@
-{
-  "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.32.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.34.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": "Apache-2.0",
+  "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",
+    "skills/agentic-sdlc-skill/LICENSE",
+    "skills/agentic-sdlc-skill/NOTICE",
+    "gemini-extension.json",
+    "README.md",
+    "CHANGELOG.md",
+    "NOTICE",
+    "scripts/lib.js",
+    "scripts/init.js",
+    "scripts/postinstall.js",
+    "scripts/preuninstall.js"
+  ]
+}

package/scripts/lib.js

@@ -672,14 +672,45 @@ function findRemindHook(settings) {
 // 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 };
-  if (orientMarkerHas(target)) return { code: 'opted-out', target };
-  const settings = state.settings;
-  const existing = findRemindHook(settings);
+  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 = {};
@@ -693,6 +724,7 @@ function wireRemindHookInto(target, python, validator) {
   } catch (e) {
     return { code: 'write-failed', target, command, error: e.message };
   }
+  remindMarkerAdd(target);
   return { code: 'wired', target, command };
 }
 
@@ -718,6 +750,8 @@ module.exports = {
   wireOrientHook,
   wireRemindHookInto,
   wireGlobalRemindHook,
+  remindMarkerHas,
+  remindMarkerAdd,
   remindHookCommand,
   findRemindHook,
   wireGlobalOrientHook,

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)
 
@@ -216,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.