@windyroad/architect 0.3.2 → 0.4.0
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
|
@@ -62,6 +62,31 @@ Flag when a proposed change represents an undocumented decision:
|
|
|
62
62
|
- **New script**: Does this introduce a new workflow step?
|
|
63
63
|
- **Structural change**: Does this reorganize code in a way that affects how the team works?
|
|
64
64
|
|
|
65
|
+
### Runtime-Path Performance Review (per ADR-023)
|
|
66
|
+
|
|
67
|
+
When a proposed change touches any of the following runtime-path surfaces, you MUST perform a per-request performance review in addition to the ADR-conformance review:
|
|
68
|
+
|
|
69
|
+
**Trigger categories:**
|
|
70
|
+
|
|
71
|
+
- **HTTP cache directives** — changes to `cache-control`, `etag`, `last-modified`, or other cache/revalidation headers on any endpoint.
|
|
72
|
+
- **Rate limiting, throttling, or request quotas** — changes to limiter configuration, quota budgets, or per-user/per-IP throttle rules.
|
|
73
|
+
- **Response content size or compression** — changes to payload shape, compression settings, or content negotiation that affect bytes-on-the-wire per request.
|
|
74
|
+
- **Per-request handler behaviour** — any edit to a request handler whose change alters wall-clock latency, CPU cost, or I/O per request (not purely refactor).
|
|
75
|
+
- **New endpoints with non-trivial traffic profile** — an endpoint is non-trivial if it is invoked from client code paths documented in the project's JTBD or README, OR named in an ADR as a "runtime-path" surface.
|
|
76
|
+
|
|
77
|
+
**When the trigger fires, your review MUST report:**
|
|
78
|
+
|
|
79
|
+
1. **Per-request cost delta** — estimated CPU, memory, and network delta per request in concrete units (ms, bytes, KB/s). Do not emit qualitative phrases.
|
|
80
|
+
2. **Request-frequency estimate** — how often the endpoint is invoked: typically `requests/user-session × sessions/day` (or equivalent aggregate). You MUST cite the source of the estimate as one of: a specific ADR, a specific JTBD, a telemetry link, or the literal string "no data — worst-case assumption".
|
|
81
|
+
3. **Product — aggregate load delta** — multiply per-request cost delta by request-frequency estimate. Report the aggregate (e.g. ms-seconds per day, bytes per hour). This is the quantity that matters for the verdict, not the per-request number alone.
|
|
82
|
+
4. **Verdict against any in-scope performance-budget ADR** — scan `docs/decisions/` for files named `performance-budget-*`. If a budget applies to the endpoint or subsystem being changed, compare the aggregate load delta against the budget's limits and report PASS / FLAG. If no performance-budget ADR covers the endpoint, report "no performance budget in scope; recommend creating one or explicitly accepting ungoverned risk."
|
|
83
|
+
|
|
84
|
+
**Qualitative-claim ban:** You MUST NOT emit qualitative phrases like "load is negligible", "microseconds only", "no measurable impact", "minimal cost", or equivalent hedged wording without attaching the concrete numeric backing described in steps 1-3 above. A quantified estimate that is honestly "worst-case assumption, no data" is acceptable; a qualitative claim without numbers is not.
|
|
85
|
+
|
|
86
|
+
**Performance-budget ADR template:** ADR-023 embeds a copy-paste template downstream projects place at `docs/decisions/<NNN>-performance-budget-<scope>.proposed.md`. When flagging a missing budget, point the user at ADR-023's Decision Outcome for the template.
|
|
87
|
+
|
|
88
|
+
**When the trigger does NOT fire**, skip this review — performance review is scoped to runtime-path changes to keep review cost proportionate.
|
|
89
|
+
|
|
65
90
|
### When NOT to flag
|
|
66
91
|
|
|
67
92
|
Do NOT flag:
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
#!/usr/bin/env bats
|
|
2
|
+
# Doc-lint guard: architect agent.md must include the runtime-path
|
|
3
|
+
# performance-review step per ADR-023 (wr-architect agent performance
|
|
4
|
+
# review scope). Closes P046 (wr-architect agent misses performance
|
|
5
|
+
# implications on high-traffic endpoints).
|
|
6
|
+
#
|
|
7
|
+
# Structural assertion — Permitted Exception to the source-grep ban
|
|
8
|
+
# (ADR-005 / P011).
|
|
9
|
+
#
|
|
10
|
+
# Cross-reference:
|
|
11
|
+
# P046 (wr-architect agent misses per-request performance implications)
|
|
12
|
+
# ADR-023 (wr-architect agent performance review scope)
|
|
13
|
+
# @jtbd JTBD-002 (ship with confidence)
|
|
14
|
+
# @jtbd JTBD-101 (extend the suite with clear patterns)
|
|
15
|
+
|
|
16
|
+
setup() {
|
|
17
|
+
AGENT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
|
|
18
|
+
AGENT_FILE="${AGENT_DIR}/agent.md"
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
@test "agent.md contains a runtime-path performance review section (ADR-023)" {
|
|
22
|
+
run grep -nE "[Pp]erformance [Rr]eview|[Rr]untime-[Pp]ath" "$AGENT_FILE"
|
|
23
|
+
[ "$status" -eq 0 ]
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
@test "agent.md lists the runtime-path trigger categories (cache / throttle / rate-limit / per-request handler)" {
|
|
27
|
+
# Cache directives
|
|
28
|
+
run grep -niE "cache-control|etag|last-modified" "$AGENT_FILE"
|
|
29
|
+
[ "$status" -eq 0 ]
|
|
30
|
+
# Rate limiting / throttle
|
|
31
|
+
run grep -niE "rate[- ]limit|throttl|quota" "$AGENT_FILE"
|
|
32
|
+
[ "$status" -eq 0 ]
|
|
33
|
+
# Per-request handler
|
|
34
|
+
run grep -niE "per-request|per request handler" "$AGENT_FILE"
|
|
35
|
+
[ "$status" -eq 0 ]
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
@test "agent.md requires quantification: per-request cost delta (ADR-023 Confirmation criterion 2a)" {
|
|
39
|
+
run grep -niE "per-request cost delta|cost delta per request" "$AGENT_FILE"
|
|
40
|
+
[ "$status" -eq 0 ]
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
@test "agent.md requires request-frequency estimate with cited source (ADR-023)" {
|
|
44
|
+
run grep -niE "[Rr]equest[- ][Ff]requency" "$AGENT_FILE"
|
|
45
|
+
[ "$status" -eq 0 ]
|
|
46
|
+
# Must require citing a source (ADR/JTBD/telemetry/worst-case)
|
|
47
|
+
run grep -niE "cite|source" "$AGENT_FILE"
|
|
48
|
+
[ "$status" -eq 0 ]
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
@test "agent.md requires product (cost x frequency) computation" {
|
|
52
|
+
run grep -niE "(cost.*frequency|frequency.*cost|aggregate load|product)" "$AGENT_FILE"
|
|
53
|
+
[ "$status" -eq 0 ]
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
@test "agent.md bans qualitative-only performance claims (ADR-023 Confirmation criterion 2b)" {
|
|
57
|
+
# The prompt must forbid phrases like "load is negligible", "microseconds only"
|
|
58
|
+
run grep -niE "(must not|MUST NOT).*(qualitative|negligible|microsecond)" "$AGENT_FILE"
|
|
59
|
+
[ "$status" -eq 0 ]
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
@test "agent.md references performance-budget ADR convention by name (ADR-023 Confirmation criterion 2c)" {
|
|
63
|
+
run grep -niE "performance[- ]budget" "$AGENT_FILE"
|
|
64
|
+
[ "$status" -eq 0 ]
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
@test "agent.md instructs a verdict against any in-scope performance-budget ADR" {
|
|
68
|
+
# Must describe what to do when a budget is present vs missing
|
|
69
|
+
run grep -niE "verdict|recommend creating|no performance budget" "$AGENT_FILE"
|
|
70
|
+
[ "$status" -eq 0 ]
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
@test "agent.md cross-references ADR-023 so readers can trace the rule's origin" {
|
|
74
|
+
run grep -n "ADR-023" "$AGENT_FILE"
|
|
75
|
+
[ "$status" -eq 0 ]
|
|
76
|
+
}
|