@windyroad/jtbd 0.5.1-preview.99 → 0.5.2-preview.122
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/agents/agent.md
CHANGED
|
@@ -86,12 +86,28 @@ If the code serves a user type not described by the existing persona:
|
|
|
86
86
|
|
|
87
87
|
These are FAIL verdicts — the JTBD documentation must be updated before the code can proceed.
|
|
88
88
|
|
|
89
|
-
##
|
|
89
|
+
## Output Contract (P037)
|
|
90
|
+
|
|
91
|
+
Your response has two communication channels. Both are required; neither replaces the other.
|
|
92
|
+
|
|
93
|
+
**1. Inline response (primary, user-facing, REQUIRED in every response):**
|
|
94
|
+
|
|
95
|
+
Every response MUST begin with one of the four verdict templates from "How to Report" above — `JTBD Review: PASS`, `JTBD Review: ISSUES FOUND`, `JTBD Review: JOB UPDATE NEEDED`, or `JTBD Review: PERSONA UPDATE NEEDED`. The inline verdict is the authoritative primary channel — it is what the caller reads and acts on.
|
|
96
|
+
|
|
97
|
+
- On **PASS**: include the aligned job ID, a brief alignment summary, and the persona-fit confirmation (which constraints were checked).
|
|
98
|
+
- On **ISSUES FOUND / JOB UPDATE NEEDED / PERSONA UPDATE NEEDED**: include actionable remediation guidance — the specific file + line, the issue, the affected job (or "no matching job"), and the fix (what would need to change for the review to pass).
|
|
99
|
+
|
|
100
|
+
You MUST NOT emit a bare verdict without body. "FAIL" alone, "ISSUES FOUND" alone, or a list of reviewed files without a verdict line are all forbidden output shapes. If there are no issues, emit PASS with alignment summary; if there are issues, emit ISSUES FOUND with at least one concrete remediation item. Every response must contain enough inline detail that the caller can act without a re-query.
|
|
101
|
+
|
|
102
|
+
**2. Verdict marker file (internal signal, REQUIRED to coordinate with hooks):**
|
|
103
|
+
|
|
104
|
+
After emitting your inline response, write your verdict to `/tmp/jtbd-verdict`. This file is consumed by the `jtbd-mark-reviewed.sh` PostToolUse hook to gate subsequent edits. It is NOT a substitute for the inline response:
|
|
90
105
|
|
|
91
|
-
After completing your review, write your verdict to `/tmp/jtbd-verdict`:
|
|
92
106
|
- `printf 'PASS' > /tmp/jtbd-verdict` — change aligns with documented jobs and persona
|
|
93
107
|
- `printf 'FAIL' > /tmp/jtbd-verdict` — misalignment, job gap, or persona gap detected
|
|
94
108
|
|
|
109
|
+
The inline verdict and the marker file MUST agree. If inline says PASS, the file says PASS; if inline says ISSUES FOUND / JOB UPDATE NEEDED / PERSONA UPDATE NEEDED, the file says FAIL.
|
|
110
|
+
|
|
95
111
|
## Constraints
|
|
96
112
|
|
|
97
113
|
- You are read-only. You do not edit files (except writing the verdict file).
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
#!/usr/bin/env bats
|
|
2
|
+
# Doc-lint guard: wr-jtbd:agent output contract — the agent MUST emit a
|
|
3
|
+
# structured inline verdict in every response, regardless of the
|
|
4
|
+
# /tmp/jtbd-verdict file write. Closes P037 (JTBD reviewer sometimes
|
|
5
|
+
# returns a bare verdict without remediation reason).
|
|
6
|
+
#
|
|
7
|
+
# Structural assertion — Permitted Exception to the source-grep ban
|
|
8
|
+
# (ADR-005 / P011).
|
|
9
|
+
#
|
|
10
|
+
# Cross-reference:
|
|
11
|
+
# P037 (JTBD reviewer bare-verdict bug)
|
|
12
|
+
# @jtbd JTBD-001 (enforce governance without slowing down)
|
|
13
|
+
|
|
14
|
+
setup() {
|
|
15
|
+
AGENT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
|
|
16
|
+
AGENT_FILE="${AGENT_DIR}/agent.md"
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
@test "agent.md contains inline verdict templates (How to Report section)" {
|
|
20
|
+
run grep -n "How to Report" "$AGENT_FILE"
|
|
21
|
+
[ "$status" -eq 0 ]
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
@test "agent.md declares inline output is REQUIRED in every response (P037)" {
|
|
25
|
+
# Must say inline output is required / must be emitted every time.
|
|
26
|
+
run grep -niE "(always|every|must|required).*inline|inline.*(always|every|must|required)" "$AGENT_FILE"
|
|
27
|
+
[ "$status" -eq 0 ]
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
@test "agent.md declares the primary communication channel is inline, not the file (P037)" {
|
|
31
|
+
# Must clarify the verdict file is an internal signal, not a replacement for inline output
|
|
32
|
+
run grep -niE "(primary|authoritative).*(inline|user-facing|response)|inline.*(primary|authoritative)" "$AGENT_FILE"
|
|
33
|
+
[ "$status" -eq 0 ]
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
@test "agent.md requires a specific verdict line on every response (PASS or ISSUES FOUND)" {
|
|
37
|
+
# The verdict line is explicit - bold JTBD Review: PASS / ISSUES FOUND
|
|
38
|
+
run grep -nE "JTBD Review: (PASS|ISSUES FOUND|JOB UPDATE NEEDED|PERSONA UPDATE NEEDED)" "$AGENT_FILE"
|
|
39
|
+
[ "$status" -eq 0 ]
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
@test "agent.md requires remediation guidance on every FAIL verdict (P037)" {
|
|
43
|
+
# On ISSUES FOUND the agent must include actionable guidance (what to change / what job / what fix)
|
|
44
|
+
run grep -niE "remediation|actionable|what (should|would need)|fix:|issue:" "$AGENT_FILE"
|
|
45
|
+
[ "$status" -eq 0 ]
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
@test "agent.md cross-references P037 so readers can trace the contract's origin" {
|
|
49
|
+
run grep -n "P037" "$AGENT_FILE"
|
|
50
|
+
[ "$status" -eq 0 ]
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
@test "agent.md explicitly forbids bare verdict without reason (P037)" {
|
|
54
|
+
# Directly addresses the observed bug: verdict without body
|
|
55
|
+
run grep -niE "(must not|MUST NOT|do not|DO NOT|never) (emit|return|produce) (a )?bare|without (reason|remediation|detail|actionable|explanation)" "$AGENT_FILE"
|
|
56
|
+
[ "$status" -eq 0 ]
|
|
57
|
+
}
|