@antoneeo/agentic-sdlc-skill 1.26.0 → 1.27.0

package/CHANGELOG.md

@@ -2,6 +2,107 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.27.0 / kb 1.5.0 / mkt 0.5.0] - 2026-08-25
+
+F-036 — the orientation hook installs itself.
+
+### Fixed
+- **`ENFORCEMENT.md` 4 said "wire it on every project" and nothing ever did.** The
+  SessionStart orientation hook was real, tested and fail-open, but installing it was a
+  manual step, so it was skipped — and a session that never enters Phase 1 explicitly
+  then never meets the guide router at all. Field result: an agent worked a governed
+  project without invoking the process. `init` now wires the hook itself.
+- **The invariant that looked like it guarded this guarded only prose** — it asserted
+  the documentation section exists (`assertIn("## 4. SessionStart hook", t)`) and that
+  `orient` runs. It gains a companion asserting the shipped installer actually CALLS the
+  writer. Mutation-tested: the first draft asserted the bare symbol and passed on a file
+  that imports the writer without invoking it, which is exactly the disabled-installer
+  case it exists to catch.
+
+### Fixed (also)
+- **ENFORCEMENT 4/2's own worked hook examples named a skill directory that two of
+  the three lenses do not install.** kb and mkt both printed
+  `.claude/skills/agentic-sdlc/scripts/...`; kb installs under `kb-agentic` and mkt
+  under `mkt-agentic-sdlc`, so anyone who copied the snippet got a hook that runs,
+  prints `can't open file`, and emits nothing — the wired-and-dead defect this release
+  detects, sitting in the instructions that produce it. Four paths corrected, and a new
+  invariant derives the expected directory and validator from what the distribution
+  actually ships and fails if an example names anything else. Mutation-tested.
+
+### Added
+- **A portability rule the doctrine did not have.** The hook command names a validator,
+  and where that validator lives decides which settings file may carry it: a repo that
+  vendors the validator gets a repo-relative command in the shared, committed
+  `.claude/settings.json`; a normal project gets an absolute path, which goes to the
+  git-ignored `.claude/settings.local.json` instead — committing it would hand every
+  teammate a hook naming a directory they do not have. `init` picks the file and adds
+  the local one to `.gitignore`. ENFORCEMENT 4's own worked example showed an absolute
+  path and did not mention the distinction; it now does.
+- **A wired-but-dead hook is detected and reported instead of counted as done.** Found
+  in the field: a repository whose hook named a sibling lens's path, so it ran every
+  session, printed `can't open file`, and emitted nothing. A bare "is a hook present?"
+  check answers "already wired" to that and makes the silence permanent, so the existing
+  command's validator path is checked on disk. Never rewritten — it may be hand-tuned —
+  but never passed off as working either.
+
+### Notes
+- `init` declines rather than guessing: no Python, skill not installed, a settings file
+  that is not valid JSON (never rewritten — a merge would discard what is in it), or a
+  skill path containing a double quote. Each case prints the snippet to paste.
+- Only Claude Code's hook shape is wired. Codex and Gemini keep the manual snippet: this
+  repository has no fixture pinning their schema, and writing a hook file in a shape
+  nobody has verified is how the wired-but-dead defect above was born.
+- A blocking `PreToolUse` gate would be real enforcement rather than a nudge, and it is
+  refused by the Vision's no-ceremony-ratchet Non-Goal. Recorded in the analysis so the
+  next person to have the idea finds the ruling instead of re-deriving it.
+
+## [1.26.1 / kb 1.4.7 / mkt 0.4.7] - 2026-08-06
+
+The late design review of F-034 (`review.md` row 1b, run after 1.26.0 had shipped because the
+gate had been skipped) returned FAIL with four blockers. Three were defects in the shipped
+doctrine and are fixed here; the fourth was a governance-record gap, fixed in `ai_docs/`.
+
+### Fixed
+- **`dispatch.md` contradicted the scoped re-review it delegates to `review.md` to define.**
+  It said "exactly three review touches per task, never a loop" and "not an extra review slot",
+  while `review.md` requires every review-driven correction to be re-reviewed — so an agent
+  executing a dispatched plan received two irreconcilable instructions. Reconciled: the scoped
+  re-review is a round **inside** slot 2 or 3, never a fourth slot; "never a loop" bounds the
+  slots, not the rounds within one. (Shared spine — the contradiction had shipped in all three
+  distributions; `dispatch.md` was missing from 1.26.0's impact map.)
+- **The claim-to-evidence rule had no enforcement point.** Its acceptance criterion promised a
+  completion claim without fresh proof would be "nameable by the closure review", but
+  `review.md` §Reviewing had no such finding class and the reviewer is never handed `SKILL.md`.
+  Added: an unproven or stale completion claim — including one resting on a narrower check than
+  the claim needs, or on a delegated agent's report rather than the diff — is now a finding.
+- **`SKILL.md`'s branch hygiene contradicted its own destructive guard.** One bullet ordered the
+  agent to "clean up the branch/worktree; never leave orphan branches"; the next reserved
+  destruction for the user's explicit request. The cleanup is now PROPOSED once the user has
+  chosen, with the anti-orphan duty kept as something to raise rather than to perform.
+- **Two gaps in the scoped re-review's own wording:** a PASS that carried findings is now
+  explicitly provisional until its corrections pass a round (the commonest real case, previously
+  unruled — the rule's trigger fired but its gate was already behind the fixes); and the single
+  REVIEW_LOG row now carries the round-1 verdict alongside the final one (`FAIL → PASS`) instead
+  of collapsing a first-round FAIL into a bare PASS, which erased the evidence the same file
+  says logging exists to preserve.
+
+- **`revise_rounds` had no defined meaning**, in the very document `SKILL.md` names as the owner
+  of the review log's schema and column meanings — and the historical rows already used it both
+  ways. Defined: it counts **review rounds**, not fix cycles (the first review is round 1, each
+  scoped re-review adds one), so a review whose findings were corrected always reads ≥ 2 and 3 is
+  the ceiling. The `verdict` column's format is defined alongside it (`FAIL → PASS` when the
+  round-1 and final verdicts differ), and the second example row — which taught a bare `PASS`
+  after two real findings closed in one round — now teaches both rules instead of contradicting
+  one. Raised at the review's round-3 cap and fixed before release rather than deferred.
+
+### Changed
+- `ai_docs/solutions/ANALYSIS_execution_integrity.md` gains what the design review found
+  missing: the **ceremony-cost disclosure** Non-Goal 3 requires (measured on the shipped diff)
+  with the owner's explicit acceptance recorded; the **rulings placement** run per mechanism
+  against the ledger's own criterion (the previous claim used a narrower "user-facing" test the
+  ledger does not define); the **lens-scoping decision** stated; and a named disposition for the
+  chronic `stale` debt. No shipped file changes from these.
+
 ## [1.26.0 / kb 1.4.6 / mkt 0.4.6] - 2026-08-06
 
 ### Added

package/gemini-extension.json

@@ -1,6 +1,6 @@
-{
-  "name": "agentic-sdlc-skill",
-  "version": "1.26.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.27.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,50 @@
-{
-  "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.26.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.27.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"
+  ]
+}

package/scripts/init.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { SKILL_SOURCE, INSTALLED_SKILL_NAME, SELF_LENS, SIBLING_LENSES, CLIENTS, clientDetected, skillTarget, loadTemplates, templateFor } = require('./lib');
+const { SKILL_SOURCE, INSTALLED_SKILL_NAME, SELF_LENS, SIBLING_LENSES, CLIENTS, clientDetected, skillTarget, wireOrientHook, loadTemplates, templateFor } = require('./lib');
 
 const cwd = process.cwd();
 
@@ -156,8 +156,22 @@ const protocolFiles = {
 // written aside and merged by hand.
 let protocolPreexisting = false;
 
-for (const client of CLIENTS) {
-  if (clientDetected(client)) {
+// Probed ONCE and reused by section 6c: re-filtering CLIENTS there would
+// run every client's detection a second time.
+const detectedClients = CLIENTS.filter(clientDetected);
+const PYTHON_CANDIDATES = ['python', 'python3', 'py'];
+const detectedPython = (() => {
+  for (const py of PYTHON_CANDIDATES) {
+    try {
+      execSync(`${py} --version`, { stdio: 'ignore' });
+      return py;
+    } catch (e) { /* try the next interpreter */ }
+  }
+  return null;
+})();
+
+for (const client of detectedClients) {
+  {
     console.log(`✅ ${client.label} detected.`);
     const created = writeIfNotExists(protocolFiles[client.key], protocolContent, `${client.label} protocol pointer`);
     if (!created) protocolPreexisting = true;
@@ -221,16 +235,119 @@ Delete it once the merge is done.
   }
 }
 
+
+// 6c. SessionStart orientation hook (F-036).
+// ENFORCEMENT.md §4 asks for this on every project with a docs root and Python.
+// It was a manual step until now, so it was skipped -- and a session that never
+// enters Phase 1 explicitly then never meets the guide router at all.
+
+// devPNT projects want `--hybrid`: without it the hook reports audit-plan
+// staleness that devPNT/KL owns, and noise at every session start is how a
+// session-start message stops being read.
+const hybridProject = fs.existsSync(path.join(cwd, '.devpnt'));
+
+// Only touch .gitignore when the wiring landed in the machine-specific file:
+// if that file is not ignored, the absolute path reaches teammates anyway and
+// the whole reason for choosing it is undone. Append-only and marker-guarded,
+// exactly like gitattributes() above. Wrapped, because the installer has already
+// written the seed files and must not die here.
+const ignoreLocalSettings = () => {
+  const marker = '.claude/settings.local.json';
+  if (!fs.existsSync(path.join(cwd, '.git'))) return;
+  const filePath = path.join(cwd, '.gitignore');
+  try {
+    const current = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+    // Line-wise, not substring: a `!.claude/settings.local.json` un-ignore would
+    // satisfy `includes()` and leave the machine-specific path committed.
+    if (current.split(/\r?\n/).some((l) => l.trim() === marker)) return;
+    fs.writeFileSync(filePath, current + [
+      '',
+      '# agentic-sdlc: the orientation hook here names a path on THIS machine.',
+      marker,
+      '',
+    ].join(EOL), 'utf8');
+    console.log(`OK    .gitignore: ${marker} ignored (it names a machine-specific path).`);
+    console.log('      If it is already tracked, run: git rm --cached ' + marker);
+  } catch (e) {
+    console.log(`⚠️  Could not update .gitignore (${e.message}). Add "${marker}" by hand.`);
+  }
+};
+
+const claudeClient = detectedClients.find((c) => c.key === 'claude');
+const otherClients = detectedClients.filter((c) => c.key !== 'claude');
+if (!claudeClient) {
+  console.log('ℹ️  Claude Code not detected: SessionStart orientation hook not wired.');
+} else {
+  const r = wireOrientHook({
+    cwd, client: claudeClient, python: detectedPython,
+    hybrid: hybridProject, docsLabel: 'ai_docs',
+  });
+  switch (r.code) {
+    case 'wired':
+      console.log(`🪝 Wired the SessionStart orientation hook in .claude/${r.file}.`);
+      if (r.local) {
+        console.log('   It names a path on THIS machine, so it went to the git-ignored');
+        console.log('   file: each teammate runs init once to get their own.');
+        ignoreLocalSettings();
+      }
+      break;
+    case 'already':
+      console.log(`⏭️  SessionStart orientation hook already wired (.claude/${r.file}).`);
+      if (r.file === 'settings.local.json') ignoreLocalSettings();
+      break;
+    case 'broken':
+      console.log(`⚠️  The SessionStart orientation hook in .claude/${r.file} is BROKEN —`);
+      console.log('   its validator does not resolve, so it has been emitting nothing:');
+      console.log(`     ${r.existing}`);
+      console.log('   Not overwritten (it may be hand-tuned). Correct it to:');
+      console.log(`     ${r.command}`);
+      break;
+    case 'unverifiable':
+      console.log(`ℹ️  A SessionStart orientation hook exists in .claude/${r.file} but names`);
+      console.log('   no validator this installer recognises, so it was left alone:');
+      console.log(`     ${r.existing}`);
+      break;
+    case 'malformed':
+      console.log(`⚠️  .claude/${r.file} has a shape this installer will not rewrite`);
+      console.log(`   (${r.why}): left untouched. Add the hook by hand — command:`);
+      console.log(`     ${JSON.stringify(r.command)}`);
+      break;
+    case 'write-failed':
+      console.log(`⚠️  Could not write .claude/${r.file} (${r.error}). Add by hand:`);
+      console.log(`     ${JSON.stringify(r.command)}`);
+      break;
+    case 'no-python':
+      console.log('ℹ️  Python not found: SessionStart orientation hook not wired.');
+      break;
+    case 'no-validator':
+      console.log('ℹ️  Skill not installed yet: orientation hook not wired. Install it');
+      console.log('   (below), then re-run init.');
+      break;
+    case 'unsafe-path':
+      console.log('⚠️  The validator path contains a character that cannot be placed in a');
+      console.log(`   hook command safely: ${r.validator}`);
+      console.log('   Refusing to build one. Wire it by hand (ENFORCEMENT.md §4).');
+      break;
+  }
+}
+for (const c of otherClients) {
+  // Said out loud rather than skipped in silence: ENFORCEMENT.md §4's manual
+  // snippet is these clients' only route, and a silent skip is what let the
+  // "documented default nobody installs" defect live in the first place.
+  console.log(`ℹ️  ${c.label}: hook not wired (only Claude Code's shape is verified) —`);
+  console.log('   wire it by hand from ENFORCEMENT.md §4 if that client supports it.');
+}
+
 // 7. Generate ai_docs/INDEX.md so the very first `validate` is already clean.
 // The manifest is generated, never seeded: delegate to the validator if Python is available.
 const validator = path.join(SKILL_SOURCE, 'scripts', 'sdlc_check.py');
 let indexed = false;
-for (const py of ['python', 'python3', 'py']) {
+// detectedPython is probed once, above: one answer for the hook and for this.
+if (detectedPython) {
   try {
-    execSync(`${py} "${validator}" index --root "${cwd}"`, { stdio: 'ignore' });
+    execSync(`${detectedPython} "${validator}" index --root "${cwd}"`, { stdio: 'ignore' });
     console.log('📇 Generated ai_docs/INDEX.md (document manifest).');
     indexed = true;
-    break;
   } catch (e) { /* try the next interpreter */ }
 }
 if (!indexed) {