@antoneeo/agentic-sdlc-skill 1.26.1 → 1.27.1

package/CHANGELOG.md

@@ -2,6 +2,77 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.27.1 / kb 1.5.1 / mkt 0.5.1] - 2026-08-25
+
+### Fixed
+- **The three README front pages did not mention the hook wiring that 1.27.0 added.**
+  `init` now changes what every project gets, and the README *is* the npm page, so two
+  of the three said nothing about it and the third barely did. Each now describes the
+  wiring, the settings.json / settings.local.json split and why it exists, and the
+  broken-hook report. `GUIDE_release.md` step 2 already made this a release duty; it was
+  skipped in 1.27.0 and this is the catch-up.
+- **`publish_all.bat`'s verify block reported the previous version after a successful
+  publish — twice.** `--prefer-online` (added in kb 1.4.8) forces revalidation but cannot
+  outrun CDN propagation of the `latest` tag in the seconds after publishing, so the
+  1.27.0 run printed mkt `0.4.7` when `0.5.0` had in fact landed. The flag alone was the
+  wrong fix and the note claiming otherwise is corrected: the block now **polls** each
+  package until the registry agrees with the local version, and prints both when it does
+  not, so "did it publish?" is answerable from the run instead of a manual `npm view`.
+
+## [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

package/README.md

@@ -54,6 +54,19 @@ agentic-sdlc-init
 
 Run it inside a project to create `ai_docs/`, Vision documents, strategic docs, audit plan, and agent protocol files (`AGENTS.md` — also the Antigravity CLI surface, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
 
+It also **wires the SessionStart orientation hook** into `.claude/`, so an agent opening
+the project is handed the reading guide, the generated manifest, the guide router and the
+last handoff before it does anything — instead of only when it remembers to look. That
+wiring used to be a manual step documented in `ENFORCEMENT.md`; being manual, it was
+skipped, and a project could run fully governed with an agent that never met the process.
+
+The hook command names a validator, so where that validator lives decides which file gets
+it: a repo that vendors it gets a repo-relative command in the shared `.claude/settings.json`
+(portable — commit it); otherwise the path is machine-specific and goes to the git-ignored
+`.claude/settings.local.json`, and each teammate runs `init` once. Re-running `init` never
+duplicates the hook, and a hook whose validator no longer resolves is reported as **broken**
+with the correction rather than counted as installed.
+
 ## Runtime Shape
 
 The actual runtime skill is the folder:

package/gemini-extension.json

@@ -1,6 +1,6 @@
-{
-  "name": "agentic-sdlc-skill",
-  "version": "1.26.1",
-  "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.1",
+  "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.1",
-  "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.1",
+  "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) {