@windyroad/jtbd 0.12.6 → 0.12.7

package/.claude-plugin/plugin.json

@@ -90,5 +90,5 @@
     }
   },
   "name": "wr-jtbd",
-  "version": "0.12.6"
+  "version": "0.12.7"
 }

package/agents/agent.md

@@ -21,6 +21,23 @@ You are the JTBD Lead. You review proposed changes against the project's Jobs To
 4. Review proposed changes against every documented job and the persona
 5. Report: PASS if aligned, or list specific misalignments and gaps
 
+## Review Mode: Pre-edit / proposed-change vs. Post-edit / applied
+
+You operate in one of two review modes depending on the calling prompt's framing. Recognising the mode is load-bearing — mis-classifying a pre-edit proposal as if it were post-edit drift is the P313 (Pre-edit governance-gate catch-22 — review agent withholds PASS because edits "aren't applied yet") catch-22 the gate is designed to close.
+
+**Pre-edit mode (the default at a governance-gate firing).** The PreToolUse JTBD gate fires BEFORE a project-file edit lands on disk. The calling prompt describes a PROPOSED change, fix plan, RFC, ticket-body amendment, or about-to-be-made edit — the change is not yet on disk by design. Recognition signals (any one is sufficient): the prompt uses words like "proposed", "plan to", "about to", "PRE-EDIT", "PRE-EDIT alignment gate"; the prompt names the to-be-edited files but the edits are described in prose not yet applied; the prompt is an AFK orchestrator iter dispatch implementing a `## Fix Strategy` against a problem ticket; the prompt is a SKILL handing you an RFC body or story body before the implementation commit lands.
+
+In pre-edit mode:
+
+- If you receive a review request describing PROPOSED changes (not-yet-applied), classify alignment of the PROPOSAL itself. Not-yet-applied state of the proposed change is the EXPECTED baseline of a pre-edit gate. Do NOT treat "edits aren't applied yet" / "the residual old state is still live" / "the change isn't on disk yet" as ISSUES FOUND — that is the gate's design intent (P313 closes this catch-22).
+- The ground truth you classify against is the **proposal** as described in the calling prompt (the diff sketch, the fix-strategy prose, the file-edit plan). The disk state is the legitimate "old state" the proposal is about to replace — including any JTBD policy file the proposal itself amends. A re-review fired by a `human-oversight: <state>` marker that invalidated because the JTBD policy changed in this session MUST classify the proposal that re-amends the policy, NOT withhold PASS because the prior policy text is still live on disk.
+- PASS the review when the proposal aligns with documented jobs and the primary persona, the proposal does not introduce an undocumented user flow, and (where applicable) any cited persona/JTBD is ratified. ISSUES FOUND / JOB UPDATE NEEDED / PERSONA UPDATE NEEDED on a pre-edit review must cite a problem with the **proposal**, not with the not-yet-applied-ness of the proposal.
+- All other review machinery below (Job Alignment, Persona Fit, Screen Mapping, API / Action Alignment, Unratified Dependency) applies normally — pre-edit mode does not relax any of those substantive checks. It constrains only the verdict-grammar around the not-yet-applied baseline.
+
+**Post-edit mode (the explicit alignment-review or applied-change review).** The calling prompt asks you to verify already-applied edits against documented jobs — typically a `/wr-jtbd:review-jobs` invocation against staged changes and recent commits, or a release-gate audit. Recognition signals: the prompt names "staged changes", "recent commits", "the current diff", "verify alignment", or "review the applied changes against documented jobs". In post-edit mode you may flag drift between disk state and JTBD docs exactly as the original verdict grammar describes — the change is on disk by construction; the not-yet-applied carve-out does not apply.
+
+**Default when ambiguous.** When the calling prompt does not name the mode explicitly, default to **pre-edit mode** if a PreToolUse gate context is plausible (the prompt was likely fired by `jtbd-detect.sh` or an AFK iter dispatch). The pre-edit default is the safer fail-mode: a true post-edit drift will still surface as ISSUES FOUND / JOB UPDATE NEEDED on the substance; a true pre-edit proposal mis-classified as post-edit fires the P313 catch-22.
+
 ## What You Check
 
 All review criteria come from the JTBD documentation. Read the docs first and apply them. Typical checks include:

package/agents/test/jtbd-pre-edit-review-mode.bats

@@ -0,0 +1,48 @@
+#!/usr/bin/env bats
+# Doc-lint guard: jtbd agent.md must carry an explicit pre-edit /
+# proposed-change review-mode carve-out so the agent classifies alignment
+# of the PROPOSAL when the calling prompt describes a not-yet-applied
+# change, instead of mis-classifying not-yet-applied state as ISSUES FOUND
+# (P313 catch-22: gate blocks edits; reviewer wants edits done first).
+#
+# tdd-review: structural-permitted (justification: P176 — agent behaviour is
+# prompt-driven with no skill-invocation harness to exercise the verdict
+# behaviourally; ADR-052 Surface 2 structural-justified case, NOT an ADR-005
+# Permitted Exception — ADR-052 narrows ADR-005 to exclude prose-doc greps).
+# When P176 lands, upgrade to a behavioural test that feeds the agent a
+# pre-edit proposal and asserts the PASS verdict.
+#
+# Cross-reference:
+#   P313 (Pre-edit governance-gate catch-22 — pass withheld pending edits)
+#   ADR-052 Surface 2 (structural-justified verdict) + P176 (harness gap)
+#   @jtbd JTBD-001 (Enforce Governance Without Slowing Down)
+
+setup() {
+  AGENT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  AGENT_FILE="${AGENT_DIR}/agent.md"
+}
+
+@test "agent.md carries a Review Mode section distinguishing pre-edit from post-edit (P313)" {
+  run grep -nE "^## Review Mode: Pre-edit / proposed-change vs\. Post-edit / applied" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md classifies alignment of the PROPOSAL in pre-edit mode (P313 verbatim core sentence)" {
+  run grep -nE "classify alignment of the PROPOSAL itself" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md treats not-yet-applied state as the EXPECTED baseline of a pre-edit gate (P313)" {
+  run grep -nE "EXPECTED baseline of a pre-edit gate" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md explicitly rejects 'edits aren't applied yet' as a valid ISSUES FOUND substance (P313)" {
+  run grep -nE "Do NOT treat .edits aren't applied yet" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md cites P313 as the catch-22 closure (audit-trail)" {
+  run grep -nE "P313" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}

package/hooks/test/jtbd-eval-scope.bats

@@ -21,25 +21,25 @@ teardown() {
 }
 
 @test "eval: scope text mentions problem files exemption (P029)" {
-  run bash "$HOOK"
+  run bash "$HOOK" </dev/null
   [ "$status" -eq 0 ]
   [[ "$output" == *"docs/problems/"* ]] || [[ "$output" == *"problem tickets"* ]]
 }
 
 @test "eval: scope text mentions BRIEFING.md exemption (P029)" {
-  run bash "$HOOK"
+  run bash "$HOOK" </dev/null
   [ "$status" -eq 0 ]
   [[ "$output" == *"BRIEFING"* ]]
 }
 
 @test "eval: scope text mentions docs/briefing/ exemption (P100)" {
-  run bash "$HOOK"
+  run bash "$HOOK" </dev/null
   [ "$status" -eq 0 ]
   [[ "$output" == *"docs/briefing/"* ]]
 }
 
 @test "eval: scope text mentions RISK-POLICY exemption (P029)" {
-  run bash "$HOOK"
+  run bash "$HOOK" </dev/null
   [ "$status" -eq 0 ]
   [[ "$output" == *"RISK-POLICY"* ]]
 }

package/hooks/test/jtbd-eval.bats

@@ -19,7 +19,7 @@ teardown() {
 
 @test "eval: suggests update-guide when docs/jtbd/ missing (no UI files)" {
   # No UI files, no docs — should still suggest
-  run bash "$HOOK"
+  run bash "$HOOK" </dev/null
   [ "$status" -eq 0 ]
   [[ "$output" == *"wr-jtbd:update-guide"* ]]
 }
@@ -27,7 +27,7 @@ teardown() {
 @test "eval: suggests update-guide when docs/jtbd/ missing (with UI files)" {
   mkdir -p src
   touch src/App.tsx
-  run bash "$HOOK"
+  run bash "$HOOK" </dev/null
   [ "$status" -eq 0 ]
   [[ "$output" == *"wr-jtbd:update-guide"* ]]
 }
@@ -35,7 +35,7 @@ teardown() {
 @test "eval: injects enforcement when docs/jtbd/README.md exists" {
   mkdir -p docs/jtbd
   echo "# Index" > docs/jtbd/README.md
-  run bash "$HOOK"
+  run bash "$HOOK" </dev/null
   [ "$status" -eq 0 ]
   [[ "$output" == *"MANDATORY JTBD CHECK"* ]]
 }
@@ -46,7 +46,7 @@ teardown() {
   # migrates into the directory layout.
   mkdir -p docs
   echo "# Jobs" > docs/JOBS_TO_BE_DONE.md
-  run bash "$HOOK"
+  run bash "$HOOK" </dev/null
   [ "$status" -eq 0 ]
   [[ "$output" != *"MANDATORY JTBD CHECK"* ]]
   [[ "$output" == *"wr-jtbd:update-guide"* ]]
@@ -56,14 +56,14 @@ teardown() {
   mkdir -p docs/jtbd
   echo "# Index" > docs/jtbd/README.md
   echo "# Jobs" > docs/JOBS_TO_BE_DONE.md
-  run bash "$HOOK"
+  run bash "$HOOK" </dev/null
   [ "$status" -eq 0 ]
   [[ "$output" == *"docs/jtbd"* ]]
   [[ "$output" == *"MANDATORY JTBD CHECK"* ]]
 }
 
 @test "eval: does not reference UI-only scoping in output" {
-  run bash "$HOOK"
+  run bash "$HOOK" </dev/null
   [ "$status" -eq 0 ]
   [[ "$output" != *"UI files"* ]]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/jtbd",
-  "version": "0.12.6",
+  "version": "0.12.7",
   "description": "Jobs-to-be-done enforcement for UI changes",
   "bin": {
     "windyroad-jtbd": "./bin/install.mjs"