@antoneeo/mkt-agentic-sdlc-skill 0.2.0 → 0.3.0

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

@@ -1,82 +1,116 @@
-# Mechanical Enforcement (optional)
-
-The prompt is not enforcement. Where the project needs repeatable guarantees,
-wire the validator into the workflow. Everything here is optional: the skill
-must stay usable without Python or hooks, declaring what it cannot verify.
-
-## 1. Pre-delivery gate (the one that matters)
-
-Before presenting any E2/E3 deliverable as finished:
-
-```bash
-python <skill_dir>/scripts/mkt_check.py check --root <project_root>
-```
-
-`check` runs `validate + ledger + budget + funnel + trace`. Errors block the
-delivery; warnings ship only with explicit user acknowledgment. This is the
-marketing twin of "tests must pass before DONE".
-
-## 2. CI
-
-For a marketing repo kept under version control:
-
-```yaml
-# e.g. GitHub Actions step
-- run: python skills/mkt-agentic-sdlc/scripts/mkt_check.py validate --strict --root .
-- run: python skills/mkt-agentic-sdlc/scripts/mkt_check.py ledger --root .
-```
-
-Use `--strict` only in CI: locally, warnings are guidance; in CI they are
-drift.
-
-## 3. Git hook (pre-commit)
-
-```bash
-#!/bin/sh
-python skills/mkt-agentic-sdlc/scripts/mkt_check.py check --root . || {
-  echo "mkt_check failed — fix the plan before committing."; exit 1; }
-```
-
-## 4. What the validator cannot check (honesty list)
-
-- Whether a BENCHMARK's URL actually supports the claimed number (it checks
-  presence, not truth) — that is the review's R2/R3 territory.
-- Whether the positioning passes the swap test (R1) — adversarial review only.
-- Whether kill/scale thresholds are sensible — review, with ledger evidence.
-- Whether the deliverable language matches the target market — Discovery
-  record + review.
-
-Declare these residuals when reporting a CLEAN check: mechanical CLEAN plus
-review PASS is the full gate, neither alone.
-
-## 5. Skill self-test (skill development only)
-
-Two deterministic batteries — the release gate. Run both:
-
-```bash
-python -m unittest discover -s skills/mkt-agentic-sdlc/scripts -p "test_*.py"
-```
-
-- `test_mkt_check.py` — the validator itself; gate for changes to
-  `mkt_check.py` or to the parseable template formats in `templates.md` (the
-  two must move together: a template format change without a validator change
-  is drift).
-- `test_skill_invariants.py` — the doctrine invariants: asserts the
-  load-bearing rules are still present in `SKILL.md` and the support files
-  (the three guarantees, the review red-flags R1/R11b/R15, the elicitation
-  rules, the research URL rule, the parseable template tokens, every support
-  file wired). Fails when a rule is deleted or weakened — a real regression,
-  never flakiness.
-
-## 6. Behavioral eval layer (opt-in, non-gating)
-
-```bash
-python skills/mkt-agentic-sdlc/evals/run_behavioral.py skills/mkt-agentic-sdlc/evals/scenarios/<scenario>.md
-```
-
-Declarative scenarios exercise real agent *adherence* (elicitation asks only
-owned facts, no number without a ledger entry, swap-test enforced, low-cost
-trap flagged, E2-without-strategy escalates, no guaranteed-success promise).
-The driver seeds a throwaway fixture, prints the prompt + pass criteria, makes
-NO model call, and never gates — LLM nondeterminism is why the deterministic
-gate stays §5. See `evals/scenarios/README.md`.
+# Mechanical enforcement (optional, recommended for teams)
+
+Prompt-level rules depend on the model's discipline and degrade with long contexts, compaction and competing instructions. Three levels of increasing guarantee:
+
+## 1. Interactive validation (default, no setup)
+
+The agent runs a single gate at closure (Phase 5):
+
+```
+python "<skill_dir>/scripts/mkt_check.py" check
+```
+
+(`check` = validate + ledger + budget + funnel + trace in one command.) Exit code ≠ 0 ⇒ the feature is not declared closed. This is the minimum level the skill expects.
+
+## 2. Check in CI (recommended for teams)
+
+Copy **both** validator files into the repository — `scripts/mkt_check.py` (the entry point) **and** `scripts/sdlc_core.py` (the shared core it imports) — keeping them side by side, e.g. `tools/mkt_check.py` + `tools/sdlc_core.py`. Then add to the pipeline:
+
+```
+python tools/mkt_check.py validate --strict
+```
+
+The validator ships as two files: the core carries the behaviour and is identical in every distribution of the family, the entry point names the domain. Copying only `mkt_check.py` fails immediately with a message saying so — loudly, never as a silently green pipeline. (Copying `sdlc_core.py` alone also works: `python tools/sdlc_core.py validate --strict` behaves identically, defaulting to the code domain.)
+
+Effect: an unregenerated index, invalid frontmatter, a missing security section or incoherent states **block the pipeline** instead of relying on the agent's memory. `--strict` also fails on warnings and on a missing `ai_docs/`, so a wrong working directory cannot produce a green pipeline. This works because documents travel in the same PR as the code (Phase 5 rule).
+
+Note: the copy in the repo is the authoritative one for CI; update it when you update the skill — both files, together.
+
+**Projects whose docs root is not `ai_docs/`.** Pass `--docs-dir <name>` (e.g. `--docs-dir mkt_docs`) on any subcommand, or set `AGENTIC_SDLC_DOCS_DIR`. Without either, the validator walks up from the working directory and takes the nearest root it recognizes. If it finds two side by side — the shape of a half-finished migration — it refuses and names both rather than validating half a project and printing a verdict. `ai_docs/` remains the default and the recommended root: the parameter exists so a legacy tree can be read and migrated, not so a second one can be kept.
+
+## 3. PreToolUse hook (gate on writes)
+
+Blocks Edit/Write on protected paths when no `ANALYSIS_*.md` is `IN_PROGRESS`. In the project's `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"C:\\Users\\<user>\\.claude\\skills\\agentic-sdlc\\scripts\\mkt_check.py\" gate --hook --protected \"src/auth;src/crypto\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Semantics: exit code 2 + message on stderr ⇒ the write is blocked and the message is shown to the agent, which must create the ANALYSIS (Phase 3) before retrying.
+
+**Usage warnings:**
+- The gate is deliberately coarse: applied to all of `src/` it would also block the legitimate L1/L2 tasks foreseen by the Triage. Use it **only on security-critical directories** (`--protected "src/auth;src/crypto"`), where "never without analysis" is the desired policy.
+- 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.
+
+## 4. SessionStart hook (orientation, recommended default)
+
+Emits the `ai_docs/` orientation — reading guide (`README.md`), manifest (`INDEX.md`), guide router (`reference/INDEX.md`) and last `handoff.md` — plus the Rule-Zero triage reminder to stdout at session start, so the agent begins already oriented instead of reading them only if it remembers to. It is **fail-open**: a missing, unreadable or oversized doc is skipped, the output is size-capped, and it always exits 0 — a broken or empty `ai_docs/` never blocks the session. It is **zero-execution** (it reads and prints, never runs anything).
+
+**Wire it on every project that has `ai_docs/` and a Python interpreter.** It was opt-in until v1.16.0 and the field result was the defect this level exists to prevent: the guide router stayed unread unless the user asked for it by hand, so guides were written and never consulted. Prompt-level placement (Rule Zero declares the router verdict; Phase 1 reads the router) carries the process on its own — this hook is the backstop that survives long contexts, compaction and a session that never enters Phase 1 explicitly. Skip it only where Python is unavailable, and know what you are trading.
+
+Wire it via each client's SessionStart mechanism — the same command everywhere (add `--hybrid` on devPNT/Hybrid projects):
+
+Claude Code — in the project's `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"C:\\Users\\<user>\\.claude\\skills\\agentic-sdlc\\scripts\\mkt_check.py\" orient"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Codex — in `.codex/hooks.json`, the same `SessionStart` → `{"type":"command","command":"… orient"}` shape (this replaces the legacy static-echo protocol some fixtures still carry).
+
+Gemini CLI — wire the same command into its startup-hook mechanism if present; otherwise the step simply degrades to the manual Phase-1 reads (no capability lost).
+
+**Usage notes:**
+- The hook assumes the working directory is the project root (standard Claude Code hook behavior); it also accepts `--root <path>`.
+- **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.
+
+## 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 `mkt_check.py` + `sdlc_core.py`; §1–§4 are theirs.)
+
+The skill self-tests its own doctrine invariants. Two layers over one scenario corpus:
+
+**Static battery — the deterministic release gate.** Run before any publish:
+
+```
+python -m unittest discover -s skills/mkt-agentic-sdlc/scripts -p "test_*.py"
+```
+
+It aggregates the test files (`test_plan.py` + `test_session_start.py` + `test_skill_invariants.py` + `test_domain_rules.py` + `test_golden_regression.py` + `test_mkt_check.py`) and asserts the skill's invariants: the M4 triggers/hook/worktree doctrine is present and wired, support-file pointers resolve, and the generated indexes are idempotent. A non-zero exit **blocks the release** — a failing eval is always a real regression, never flakiness: the battery is stdlib-only and makes no model or network call. One test does spawn a subprocess — `test_golden_regression.py` runs the shipped validator over a frozen corpus, which is the only way to compare what a user actually sees; it is local, offline and deterministic. If `test_indexes_idempotent` fails, run `mkt_check.py index` and re-run. If `test_golden_regression` fails, the validator's behaviour on an unchanged project changed: treat that as a regression until someone declares it intended.
+
+**Behavioral corpus — opt-in, non-CI.** `evals/scenarios/*.md` (declarative, model-neutral) + `evals/run_behavioral.py` seed a fixture and print a prompt + pass criteria for a human/agent to run and self-assess. Because live adherence is nondeterministic, this layer **never gates** — it is the reproducible way to check that, e.g., the consult trigger actually fires on a seeded repo (the "demonstrably" artifact).
+
+**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.