@antoneeo/agentic-sdlc-skill 1.28.0 → 1.30.0

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

@@ -94,6 +94,23 @@ Hybrid project's devPNT gates write to the same file.
 The log is how the gate's value is measured over time; skipping it makes the gate
 unfalsifiable, the same defect as an unnamed EXISTS or a faked router verdict.
 
+**Revise means converge, not accrete.** Two revision failure modes generate their
+own findings and can make the cap unreachable honestly. (1) *Patch-on-patch*:
+each round's fixes are grafted onto the previous text until stale counts,
+duplicated sections and internal contradictions are findings the revisions
+themselves created. When a round's findings are of that artifact-consistency
+class — and at the latest before a round-3 attempt — rewrite the artifact lean
+and operative against the checklist instead of patching again; a from-scratch
+rewrite is cheaper than a burned round. (2) *Revision narrative in the
+artifact*: the artifact under review carries its own review archaeology
+("v1.2 fixed…", "as the round-2 review noted…"). An artifact states what IS,
+once; how it got there lives in the REVIEW_LOG row's notes, never in the
+artifact — archaeology bloats the object under review and every stale
+self-reference is a future finding. Field measurement (2026-08): an artifact
+that had grown to ~1,250 lines across eight failing rounds passed on the round
+after a ~500-line operative rewrite moved the history out — the rewrite removed
+an entire finding class.
+
 **The reviewer is read-only and advisory.** It never edits, never commits, never
 marks anything DONE, and a PASS is not an approval to merge — the human owns that.
 
@@ -124,6 +141,26 @@ When you hand work to a reviewer (human or agent), give them:
   should have been. The design reviewer checks that every threat surface the change
   touches has a matching security requirement.
 
+- **The severity contract**: state with the request what counts as a blocker
+  versus a lesser finding. A blocker is *unfit-to-proceed* evidence only — a
+  false claim about existing code, a published falsehood, a missing impacted
+  file, an unresolvable internal contradiction, a real regression; an
+  improvement idea, a wish, or a style preference is at most a WARN and never
+  fails the artifact. An uncalibrated "hunt hard" mandate produces
+  blocker-inflated rounds that fail artifacts on wishes — each one burns a
+  round from the cap of 3 and patches the artifact for prose, the accretion
+  failure the round-cap rule names. Stating the taxonomy calibrates the
+  *scale*; it never pre-judges any specific finding (that stays forbidden
+  below) — the reviewer still decides where every finding lands.
+
+**Pre-audit before you request.** Before handing the artifact over, run a
+scripted author pre-audit: mechanically resolve every `file:line` / symbol
+anchor the artifact cites against the real tree, and recount every count it
+states — with a script, not by eye. Anchors rot between drafts, and a reviewer
+that trips on a broken anchor spends its round proving your citation instead of
+your design. Measured cost is near zero (one grep-loop); measured catch: four
+rotted anchors in a single artifact, pre-review.
+
 **The verdict travels back as the reviewer's own final output** — the text it
 returns when it finishes, nothing else. A reviewer that tries to message the
 requester mid-run depends on a delivery channel it cannot verify (a subagent
@@ -301,6 +338,20 @@ When you are the reviewer:
   NOT checked here — architecture-awareness is the Capability Ledger / Impact
   review's job; a clause for it would duplicate that.) A lens whose template
   defines no such section (knowledge, marketing) never fires this clause.
+- **Behavioural-claim probes (same reviews; fires only in the lens whose
+  SKILL.md defines Execute-Before-Specify — the code lens today; that paragraph
+  is the owning definition — cite it, never restate it).** On an L3 design
+  artifact, a claim of the form "the code today does X" must trace to an
+  assertion in the artifact's shipped harness
+  (`ai_docs/solutions/harness_[feature]/`): the check is mechanical — re-run
+  the harness and compare, instead of re-deriving the claims by reading. Three
+  findings live here and nowhere else: a behavioural claim backed by no probe
+  (report it as unproven — reading the source yourself is the same
+  insufficient evidence the rule bans for the author); a harness absent while
+  the prose carries behavioural claims; and a probe that no longer passes
+  against the current tree. Structural facts (a file exists, a symbol's
+  signature, its callers) are the blast-radius clause's territory, never probe
+  findings. A lens whose SKILL.md defines no such duty never fires this clause.
 
 ## Anti-patterns
 

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

@@ -1646,6 +1646,143 @@ def cmd_mark(root, paths):
     return 0
 
 
+# ------------------------------------------------- orientation-hook wiring
+# F-041: read-only mirror of the installer-side detection in lib.js
+# (findOrientHook + orientHookValidator). The JS owns WRITING hooks, with its
+# injection guards; this side only DETECTS, at `check`, so a project whose
+# sessions start unoriented hears about it in-project (ENFORCEMENT par.4: the
+# hook is wired at init only -- pre-F-036 and agent-bootstrapped projects never
+# got it, and a wired-but-dead hook is "the worst of the three states").
+# The file list is a SUPERSET of the JS one: .codex/hooks.json is documented in
+# ENFORCEMENT par.4 but never written by init. Pinned equal on both sides:
+# the entry-point names, and (F-042) the user-settings path derivation --
+# CLAUDE_CONFIG_DIR when set, else <home>/.claude -- empty-string env falsy
+# on both sides.
+ORIENT_HOOK_ENTRY_POINTS = ("sdlc_check.py", "mkt_check.py")
+ORIENT_HOOK_CONFIG_FILES = (".claude/settings.json",
+                            ".claude/settings.local.json",
+                            ".codex/hooks.json")
+ORIENT_HOOK_CONFIG_CAP = 1024 * 1024  # settings are tiny; cap pathological files
+_ORIENT_HOOK_CMD_RE = re.compile(r" orient(\s|$)")
+_ORIENT_HOOK_TOKEN_RE = re.compile(r'"([^"]*)"|(\S+)')
+
+
+def _orient_entries_in(p):
+    """Yield the SessionStart commands invoking an orient entry point from ONE
+    client config file. Fail-open: an unreadable, oversized, malformed or
+    directory-shaped file contributes nothing. Reads are utf-8-sig -- a BOM'd
+    settings.json (PowerShell/Notepad) must not read as unwired (declared
+    divergence from Node's JSON.parse)."""
+    try:
+        if not p.is_file() or p.stat().st_size > ORIENT_HOOK_CONFIG_CAP:
+            return
+        data = json.loads(p.read_text(encoding="utf-8-sig"))
+    except Exception:
+        return
+    if not isinstance(data, dict):
+        return
+    hooks = data.get("hooks")
+    groups = hooks.get("SessionStart") if isinstance(hooks, dict) else None
+    if groups is None:
+        groups = data.get("SessionStart")  # the .codex/hooks.json shape
+    if not isinstance(groups, list):
+        return
+    for group in groups:
+        if not isinstance(group, dict):
+            continue
+        inner = group.get("hooks")
+        for h in inner if isinstance(inner, list) else [group]:
+            cmd = h.get("command") if isinstance(h, dict) else None
+            if (isinstance(cmd, str)
+                    and any(n in cmd for n in ORIENT_HOOK_ENTRY_POINTS)
+                    and _ORIENT_HOOK_CMD_RE.search(cmd)):
+                yield cmd
+
+
+def _orient_user_settings_path():
+    """The machine-global settings file (F-042 wires it at install time).
+
+    Read at CALL time -- a DECLARED divergence from AGENTIC_SDLC_KB_ROOT's
+    import-time read: unittest imports this module once before any test runs,
+    so an import-time seam would be frozen before the matrix could set it.
+    AGENTIC_SDLC_USER_SETTINGS is the test-isolation seam (python-side only);
+    the production derivation mirrors lib.js: CLAUDE_CONFIG_DIR || ~/.claude."""
+    seam = os.environ.get("AGENTIC_SDLC_USER_SETTINGS")
+    if seam:
+        return Path(seam)
+    cfg = os.environ.get("CLAUDE_CONFIG_DIR")
+    return (Path(cfg) if cfg else Path.home() / ".claude") / "settings.json"
+
+
+def _orient_hook_commands(root):
+    """Yield (command, at_user_level) across every known client config: the
+    three project-relative files, then the machine-global user settings --
+    the file the installer wires (F-042), without which a fixed machine's
+    projects would read as unwired forever."""
+    for rel in ORIENT_HOOK_CONFIG_FILES:
+        for cmd in _orient_entries_in(Path(root) / rel):
+            yield cmd, False
+    for cmd in _orient_entries_in(_orient_user_settings_path()):
+        yield cmd, True
+
+
+def orient_hook_state(root):
+    """'wired' | 'dead' | 'unwired'.
+
+    A matching entry whose tokens name no validator is "cannot tell" and counts
+    as wired (the lib.js contract: never report broken on cannot-tell). 'dead'
+    requires every matching entry to name a validator that does not resolve:
+    the client runs ALL SessionStart hooks -- project-level AND user-level
+    merge -- so one live entry at either level still orients the session
+    (any-resolves aggregation across levels). Relative tokens resolve against
+    the project root (the vendored-validator convention); a USER-level relative
+    token has no cwd to resolve against and is treated as cannot-tell."""
+    matched = False
+    for cmd, at_user_level in _orient_hook_commands(root):
+        matched = True
+        token = None
+        for m in _ORIENT_HOOK_TOKEN_RE.finditer(cmd):
+            tok = m.group(1) if m.group(1) is not None else m.group(2)
+            if any(tok.endswith(n) for n in ORIENT_HOOK_ENTRY_POINTS):
+                token = tok
+                break
+        if token is None:
+            return "wired"
+        tp = Path(token)
+        if not tp.is_absolute():
+            if at_user_level:
+                return "wired"  # cannot tell: no cwd exists at user level
+            tp = Path(root) / tp
+        if tp.exists():
+            return "wired"
+    return "dead" if matched else "unwired"
+
+
+def print_orient_hook_note(root):
+    """Print the FS-A wiring note (unwired / dead), or nothing when wired.
+
+    Informational only, by contract: never an exit code, never a validate
+    warning (--strict CI must not fail on a hook that legitimately lives in
+    git-ignored settings.local.json). Called by the spine's cmd_check AND by
+    an overlay that replaces check with its own pipeline (the marketing lens
+    does): the note is check-layer behaviour, whoever owns the check."""
+    try:
+        state = orient_hook_state(root)
+        if state == "unwired":
+            print("[note] agent sessions start without automatic orientation on this "
+                  "machine (no session-orientation hook found at project or user level). "
+                  "Fix once: update or reinstall the skill npm package (on Claude Code "
+                  "with Python it wires the hook machine-wide), or wire it per "
+                  "ENFORCEMENT.md par.4")
+        elif state == "dead":
+            print("[note] a session-orientation hook is configured but points at a "
+                  "validator that no longer exists, so sessions start unoriented. Fix: "
+                  "update or reinstall the skill npm package, or correct the command. "
+                  "Details: ENFORCEMENT.md par.4")
+    except Exception:
+        pass  # detection must never break check
+
+
 def cmd_check(root, strict=False, hybrid=False):
     print("===== validate =====")
     rc_v = cmd_validate(root, strict=strict, hybrid=hybrid)
@@ -1653,6 +1790,7 @@ def cmd_check(root, strict=False, hybrid=False):
     rc_s = cmd_stale(root, hybrid=hybrid)
     print(f"\ncheck: {'CLEAN' if not (rc_v or rc_s) else 'NOT CLEAN'} "
           f"(validate rc={rc_v}, stale rc={rc_s})")
+    print_orient_hook_note(root)
     return 1 if (rc_v or rc_s) else 0