rungate 0.4.1 → 0.6.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/config/behavioral-sc-map.json +170 -0
- package/config/brief-policies.json +28 -0
- package/config/ceremony-profiles.json +207 -0
- package/config/check-registry.json +114 -0
- package/config/matcher-registry.json +142 -0
- package/config/prove-evidence.schema.json +65 -0
- package/config/spec-policies.json +36 -0
- package/config/universal-rules.yaml +15 -0
- package/config/workflow-schema.json +279 -0
- package/lib/agents-md-sections.ts +144 -0
- package/lib/branch-diff.ts +139 -0
- package/lib/bun-version.ts +268 -0
- package/lib/ci-checkout.ts +1 -1
- package/lib/cli-commands.ts +7 -1
- package/lib/compliance.ts +13 -11
- package/lib/config-loader.ts +12 -0
- package/lib/conformity.ts +1147 -116
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +90 -4
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +22 -0
- package/lib/fallow-availability.ts +129 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +71 -23
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/github.ts +195 -0
- package/lib/js-top-level-code.ts +27 -2
- package/lib/junit-checks.ts +484 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/package-closure.ts +278 -2
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/release-preflight.ts +196 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +311 -0
- package/lib/scaffold/ai-review-step.ts +180 -0
- package/lib/scaffold/defaults.ts +40 -0
- package/lib/scaffold/managed-workflow.ts +125 -27
- package/lib/scaffold/owned-files.ts +48 -2
- package/lib/scaffold/profiles.ts +94 -0
- package/lib/scaffold/rehearsal.ts +232 -73
- package/lib/scaffold/steps.ts +777 -152
- package/lib/scaffold/write-steps.ts +56 -13
- package/lib/scanner.ts +38 -12
- package/lib/source-anchor.ts +144 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/success-doc.ts +779 -0
- package/lib/suite-run-reading.ts +364 -0
- package/lib/test-census.ts +199 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +166 -10
- package/lib/tool-probe.ts +120 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/trajectory.ts +377 -0
- package/lib/validators/spec-validators.ts +35 -6
- package/lib/workflow-security.ts +101 -0
- package/lib/workflow-test-harness.ts +349 -0
- package/package.json +6 -1
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +17 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +163 -0
- package/scripts/extract-constraints.ts +90 -19
- package/scripts/generate-code-map.ts +53 -12
- package/scripts/scaffold-project.ts +31 -4
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +57 -5
- package/scripts/sync-spec-tests.ts +2 -1
- package/specs/SPEC-TEMPLATE.md +200 -0
- package/templates/SUCCESS-TEMPLATE.md +72 -0
- package/templates/agent-briefs/_shared.md +9 -0
- package/templates/agent-briefs/aditi.md +46 -0
- package/templates/agent-briefs/discovery.md +37 -0
- package/templates/agent-briefs/marcus.md +39 -0
- package/templates/agent-briefs/quinn.md +67 -0
- package/templates/agent-briefs/rook.md +40 -0
- package/templates/agent-briefs/serena.md +39 -0
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
---
|
|
2
|
+
doc-type: spec
|
|
3
|
+
status: draft
|
|
4
|
+
owner: [name]
|
|
5
|
+
created: [YYYY-MM-DD]
|
|
6
|
+
updated: [YYYY-MM-DD]
|
|
7
|
+
governs: [intent — "I want to..." language, e.g. "Fix scaffold output, change what files get generated". This drives the AGENTS.md routing table. Write once, be specific.]
|
|
8
|
+
testable: false
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# [Spec Title]
|
|
12
|
+
|
|
13
|
+
## Problem Statement
|
|
14
|
+
|
|
15
|
+
[What gap, risk, or need this spec addresses. 2-3 sentences max.]
|
|
16
|
+
|
|
17
|
+
## Design Decisions
|
|
18
|
+
|
|
19
|
+
[Key decisions. Use a table for multiple:]
|
|
20
|
+
|
|
21
|
+
| Decision | What | Rationale |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| D-1 | [decision] | [why] |
|
|
24
|
+
|
|
25
|
+
## Target State
|
|
26
|
+
|
|
27
|
+
[What the system looks like when this spec is fully implemented.]
|
|
28
|
+
|
|
29
|
+
## Success Criteria
|
|
30
|
+
|
|
31
|
+
Each SC must be parseable by the conformity test generator (`lib/conformity.ts` → `matchPattern()`). SCs that don't match a pattern generate a warning but don't fail tests.
|
|
32
|
+
|
|
33
|
+
### Recognized Patterns
|
|
34
|
+
|
|
35
|
+
<!-- BEGIN GENERATED PATTERNS -->
|
|
36
|
+
Use these exact patterns for auto-testable SCs:
|
|
37
|
+
|
|
38
|
+
#### file-exists
|
|
39
|
+
**Syntax:** `{file} exists [at root] [<= N lines]`
|
|
40
|
+
|
|
41
|
+
**Example:** `- [ ] SC-N: AGENTS.md exists`
|
|
42
|
+
|
|
43
|
+
**Notes:** Checks that a file exists at the project root. Optionally checks line count with <= N lines suffix.
|
|
44
|
+
|
|
45
|
+
#### dir-exists
|
|
46
|
+
**Syntax:** `{dir}/ directory exists [with >= N {type}]`
|
|
47
|
+
|
|
48
|
+
**Example:** `- [ ] SC-N: specs/ directory exists`
|
|
49
|
+
|
|
50
|
+
**Notes:** Checks that a directory exists. Supports aliases (test/tests, reference/ref). Optional minimum file count.
|
|
51
|
+
|
|
52
|
+
#### all-specs-frontmatter
|
|
53
|
+
**Syntax:** `all specs have frontmatter`
|
|
54
|
+
|
|
55
|
+
**Example:** `- [ ] SC-N: all specs have frontmatter`
|
|
56
|
+
|
|
57
|
+
**Notes:** Validates that every spec in specs/ has YAML frontmatter with a testable field. Skips status: split files.
|
|
58
|
+
|
|
59
|
+
#### paths-resolve
|
|
60
|
+
**Syntax:** `all paths referenced in {file} resolve`
|
|
61
|
+
|
|
62
|
+
**Example:** `- [ ] SC-N: all paths referenced in AGENTS.md resolve`
|
|
63
|
+
|
|
64
|
+
**Notes:** Scans markdown links in the target file and verifies each local path resolves. Skips http and anchor links.
|
|
65
|
+
|
|
66
|
+
#### root-clean
|
|
67
|
+
**Syntax:** `root is clean [content: <= N] [code: <= N]`
|
|
68
|
+
|
|
69
|
+
**Example:** `- [ ] SC-N: root is clean`
|
|
70
|
+
|
|
71
|
+
**Notes:** Checks that the project root has a reasonable number of top-level items. Content projects default to 10, code projects to 30.
|
|
72
|
+
|
|
73
|
+
#### pointer-exists
|
|
74
|
+
**Syntax:** `{file} exists with pointer to {target}`
|
|
75
|
+
|
|
76
|
+
**Example:** `- [ ] SC-N: CLAUDE.md exists with pointer to AGENTS.md`
|
|
77
|
+
|
|
78
|
+
**Notes:** Checks that a file exists AND contains a reference to the target string.
|
|
79
|
+
|
|
80
|
+
#### canary
|
|
81
|
+
**Syntax:** `canary`
|
|
82
|
+
|
|
83
|
+
**Example:** `- [ ] SC-N: canary test exists`
|
|
84
|
+
|
|
85
|
+
**Notes:** Checks that a conformity or canary test file exists in the test/ directory.
|
|
86
|
+
|
|
87
|
+
#### content-contains
|
|
88
|
+
**Syntax:** `{file} contains [{item1}, {item2}, ...]`
|
|
89
|
+
|
|
90
|
+
**Example:** `- [ ] SC-N: AGENTS.md contains [Project Identity, Rules]`
|
|
91
|
+
|
|
92
|
+
**Notes:** Checks that a file contains all listed items. Items are comma-separated inside brackets.
|
|
93
|
+
|
|
94
|
+
#### content-not-contains
|
|
95
|
+
**Syntax:** `{file} must NOT contain [{item1}, {item2}, ...]`
|
|
96
|
+
|
|
97
|
+
**Example:** `- [ ] SC-N: AGENTS.md must NOT contain [deprecated-section]`
|
|
98
|
+
|
|
99
|
+
**Notes:** Checks that a file does NOT contain any of the listed items. Supports both 'must NOT contain' and 'has no' syntax.
|
|
100
|
+
|
|
101
|
+
#### count-threshold
|
|
102
|
+
**Syntax:** `{file} is under [{N}] lines|words`
|
|
103
|
+
|
|
104
|
+
**Example:** `- [ ] SC-N: AGENTS.md is under [200] lines`
|
|
105
|
+
|
|
106
|
+
**Notes:** Checks that a file is under a threshold of lines or words. Supports both 'is under' and 'at most' syntax.
|
|
107
|
+
|
|
108
|
+
#### json-field-equals
|
|
109
|
+
**Syntax:** `{file} {field} field equals [{value}]`
|
|
110
|
+
|
|
111
|
+
**Example:** `- [ ] SC-N: package.json name field equals [rungate]`
|
|
112
|
+
|
|
113
|
+
**Notes:** Checks that a JSON file's field has the expected value. Supports nested fields with dot notation (e.g., config.name).
|
|
114
|
+
|
|
115
|
+
#### section-exists
|
|
116
|
+
**Syntax:** `{file} has section [{SectionName}]`
|
|
117
|
+
|
|
118
|
+
**Example:** `- [ ] SC-N: AGENTS.md has section [Rules]`
|
|
119
|
+
|
|
120
|
+
**Notes:** Checks that a markdown file has a heading matching the section name. Matches any heading level (# through ######).
|
|
121
|
+
|
|
122
|
+
#### regex-match
|
|
123
|
+
**Syntax:** `{file} matches /{pattern}/[flags]`
|
|
124
|
+
|
|
125
|
+
**Example:** `- [ ] SC-N: AGENTS.md matches /^# /m`
|
|
126
|
+
|
|
127
|
+
**Notes:** Checks that a file's content matches the given regular expression. Supports standard regex flags.
|
|
128
|
+
|
|
129
|
+
#### source-contains
|
|
130
|
+
**Syntax:** `harness {file} contains [{keywords}]`
|
|
131
|
+
|
|
132
|
+
**Example:** `- [ ] SC-N: harness lib/conformity.ts contains [matchPattern, runScaffoldConformity]`
|
|
133
|
+
|
|
134
|
+
**Notes:** Checks that a harness source file (lib/, scripts/, hooks/, gates/) contains listed keywords. Requires 'harness' prefix or source path prefix.
|
|
135
|
+
|
|
136
|
+
#### json-has-field
|
|
137
|
+
**Syntax:** `{file}.json has field {name}`
|
|
138
|
+
|
|
139
|
+
**Example:** `- [ ] SC-N: package.json has field scripts`
|
|
140
|
+
|
|
141
|
+
**Notes:** Checks that a JSON file has the specified field defined. Supports nested fields with dot notation.
|
|
142
|
+
|
|
143
|
+
#### scaffold-produces
|
|
144
|
+
**Syntax:** `scaffold output {file} exists`
|
|
145
|
+
|
|
146
|
+
**Example:** `- [ ] SC-N: scaffold output AGENTS.md exists`
|
|
147
|
+
|
|
148
|
+
**Notes:** Checks that a scaffold-generated file exists. Currently validates file presence; future versions will run scaffold and verify output.
|
|
149
|
+
|
|
150
|
+
#### frontmatter-field
|
|
151
|
+
**Syntax:** `{file} frontmatter has {field} [= {value}]`
|
|
152
|
+
|
|
153
|
+
**Example:** `- [ ] SC-N: specs/CONFIG-DRIVEN-TESTING-SPEC.md frontmatter has testable = true`
|
|
154
|
+
|
|
155
|
+
**Notes:** Checks YAML frontmatter in a file. Verifies field exists, optionally checks its value. Used for spec and agent file metadata.
|
|
156
|
+
|
|
157
|
+
#### file-line-range
|
|
158
|
+
**Syntax:** `{file} is between [{min}] and [{max}] lines`
|
|
159
|
+
|
|
160
|
+
**Example:** `- [ ] SC-N: AGENTS.md is between [50] and [300] lines`
|
|
161
|
+
|
|
162
|
+
**Notes:** Checks that a file's line count falls within a range (inclusive). Useful for ensuring files are neither too short nor too long.
|
|
163
|
+
|
|
164
|
+
#### command-output
|
|
165
|
+
**Syntax:** `command-output `{command}` contains [{expected1}, {expected2}, ...]`
|
|
166
|
+
|
|
167
|
+
**Example:** `- [ ] SC-N: command-output `bun test --help` contains [test, run]`
|
|
168
|
+
|
|
169
|
+
**Notes:** Runs a shell command via spawnSync with a 10-second timeout and checks that stdout contains all listed strings. Returns FAIL (not crash) on non-zero exit.
|
|
170
|
+
<!-- END GENERATED PATTERNS -->
|
|
171
|
+
|
|
172
|
+
### Writing Effective SCs
|
|
173
|
+
|
|
174
|
+
**DO:**
|
|
175
|
+
- Use exact pattern syntax from above
|
|
176
|
+
- Be specific about filenames and paths
|
|
177
|
+
- Use measurable criteria (line counts, file counts)
|
|
178
|
+
- Start with simplest patterns first
|
|
179
|
+
|
|
180
|
+
**DON'T:**
|
|
181
|
+
- Use vague language ("should", "might", "consider")
|
|
182
|
+
- Mix multiple criteria in one SC (split them)
|
|
183
|
+
- Use absolute paths (`~/`, `/Users/`) — use relative paths
|
|
184
|
+
- Write SCs that require human judgment
|
|
185
|
+
|
|
186
|
+
**Pattern not available?** Complex criteria need custom test code in phase test files (see `test/phase-*.test.ts`).
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
- [ ] SC-1: [first criterion]
|
|
191
|
+
- [x] SC-2: [second criterion]
|
|
192
|
+
- [ ] SC-A1: [anti-criterion — must NOT happen]
|
|
193
|
+
|
|
194
|
+
## Implementation
|
|
195
|
+
|
|
196
|
+
[Steps to implement. Optional — can reference issues instead.]
|
|
197
|
+
|
|
198
|
+
## Cautions
|
|
199
|
+
|
|
200
|
+
[Things that could go wrong. What to verify before/after.]
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
---
|
|
2
|
+
doc-type: reference
|
|
3
|
+
status: active
|
|
4
|
+
owner: TODO-OWNER
|
|
5
|
+
updated: TODO-DATE
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# What we are building, and how we will know it worked
|
|
9
|
+
|
|
10
|
+
<!-- rungate:placeholder — every line marked like this must be replaced. A SUCCESS.md
|
|
11
|
+
that still carries one is refused by the conformity suite, deliberately: an
|
|
12
|
+
unfilled template is indistinguishable from a considered one to everything
|
|
13
|
+
except a reader. -->
|
|
14
|
+
|
|
15
|
+
## The thing
|
|
16
|
+
|
|
17
|
+
<!-- rungate:placeholder -->
|
|
18
|
+
TODO — one sentence. Not a feature list and not a mission statement: the single
|
|
19
|
+
thing that is true when this works, written so that someone could disagree with it.
|
|
20
|
+
|
|
21
|
+
## What this is not
|
|
22
|
+
|
|
23
|
+
<!-- rungate:placeholder -->
|
|
24
|
+
TODO — the nearest plausible thing you are NOT building. This section exists
|
|
25
|
+
because scope creep arrives disguised as the goal.
|
|
26
|
+
|
|
27
|
+
## The claims
|
|
28
|
+
|
|
29
|
+
Each claim is falsifiable and names the check that would catch it failing. A
|
|
30
|
+
claim with no `How it fails` is a slogan — delete it or make it measurable.
|
|
31
|
+
|
|
32
|
+
Keep as many as you need and delete the rest. Three well-chosen claims beat
|
|
33
|
+
five padded ones.
|
|
34
|
+
|
|
35
|
+
### Claim 1 — TODO
|
|
36
|
+
|
|
37
|
+
<!-- rungate:placeholder -->
|
|
38
|
+
|
|
39
|
+
**How it fails:** TODO — the concrete observation that would prove this claim
|
|
40
|
+
false. "It doesn't work" is not an answer; name the input and the wrong output.
|
|
41
|
+
|
|
42
|
+
**How to measure it:** TODO — the command, test or artifact that produces the
|
|
43
|
+
observation above. If nothing produces it, this claim is not yet real.
|
|
44
|
+
|
|
45
|
+
### Claim 2 — TODO
|
|
46
|
+
|
|
47
|
+
<!-- rungate:placeholder -->
|
|
48
|
+
|
|
49
|
+
**How it fails:** TODO
|
|
50
|
+
|
|
51
|
+
**How to measure it:** TODO
|
|
52
|
+
|
|
53
|
+
### Claim 3 — TODO
|
|
54
|
+
|
|
55
|
+
<!-- rungate:placeholder -->
|
|
56
|
+
|
|
57
|
+
**How it fails:** TODO
|
|
58
|
+
|
|
59
|
+
**How to measure it:** TODO
|
|
60
|
+
|
|
61
|
+
## Standing
|
|
62
|
+
|
|
63
|
+
Where each claim actually stands today, not where it is meant to end up. A
|
|
64
|
+
claim with no evidence is `untested`, which is a legitimate answer; a claim
|
|
65
|
+
recorded as met without a measurement is the thing this whole file exists
|
|
66
|
+
to prevent.
|
|
67
|
+
|
|
68
|
+
| Claim | Standing | Measured |
|
|
69
|
+
|---|---|---|
|
|
70
|
+
| 1 | untested | — |
|
|
71
|
+
| 2 | untested | — |
|
|
72
|
+
| 3 | untested | — |
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
---
|
|
2
|
+
doc-type: reference
|
|
3
|
+
status: active
|
|
4
|
+
owner: jason
|
|
5
|
+
updated: 2026-09-30
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
<!-- Shared agent principles moved to .claude/rules/agent-principles.md (unconditional rule) -->
|
|
9
|
+
<!-- All agents inherit project rules, so shared content is no longer injected into briefs -->
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
doc-type: reference
|
|
3
|
+
status: active
|
|
4
|
+
owner: jason
|
|
5
|
+
updated: 2026-09-22
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
You are Aditi Sharma, UX/UI designer. You design component specs and review UI implementations.
|
|
9
|
+
|
|
10
|
+
## Project Type Detection (MANDATORY FIRST STEP)
|
|
11
|
+
|
|
12
|
+
Read `.claude/rungate/config.json` and check the `pages` field:
|
|
13
|
+
- If `pages` is empty `{}` → this is a **CLI/library project with no UI**. Report: "No UI components to review — CLI project. SKIP." Do not proceed.
|
|
14
|
+
- If `pages` has entries → proceed with UI review below.
|
|
15
|
+
|
|
16
|
+
## Context (READ THIS FIRST)
|
|
17
|
+
|
|
18
|
+
1. **CODE-MAP.md § Page → Component Map** — which components render on each page
|
|
19
|
+
3. **CODE-MAP.md § React Components** — full component inventory
|
|
20
|
+
4. Read any visual specs or mockups referenced in the brief
|
|
21
|
+
|
|
22
|
+
## What you do
|
|
23
|
+
|
|
24
|
+
1. Review proposed UI changes against design principles
|
|
25
|
+
2. Create component specs with layout, spacing, typography, color
|
|
26
|
+
3. Assess visual hierarchy and information density
|
|
27
|
+
4. Evaluate accessibility (contrast, focus order, screen reader labels)
|
|
28
|
+
|
|
29
|
+
## Design principles
|
|
30
|
+
|
|
31
|
+
- shadcn/ui component library as the base
|
|
32
|
+
- Consistent spacing scale (4px base)
|
|
33
|
+
- Clear visual hierarchy — primary action obvious
|
|
34
|
+
- Accessible: WCAG 2.1 AA minimum
|
|
35
|
+
|
|
36
|
+
## Report
|
|
37
|
+
|
|
38
|
+
- APPROVED or REVISION_NEEDED with specific changes
|
|
39
|
+
- Mockups as HTML when proposing new layouts
|
|
40
|
+
- Annotated screenshots when reviewing existing UI
|
|
41
|
+
- Specific CSS values, not vague directions
|
|
42
|
+
|
|
43
|
+
## Rules
|
|
44
|
+
|
|
45
|
+
- Never modify source code directly — provide specs for Marcus
|
|
46
|
+
- Never run builds or tests
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
---
|
|
2
|
+
doc-type: reference
|
|
3
|
+
status: active
|
|
4
|
+
owner: jason
|
|
5
|
+
updated: 2026-09-22
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
You are the Discovery agent. You read issues, size work, and produce structured ACs with evidence methods.
|
|
9
|
+
|
|
10
|
+
## Discovery Rules
|
|
11
|
+
- Read PROJECT-STATE.md SECOND — it has current priorities and context
|
|
12
|
+
- Grep before Read — never read a large file blind, find the line first
|
|
13
|
+
- One read per file — if you need different sections, use offset/limit
|
|
14
|
+
- Stay under 25 tool calls — if you're over, you're fishing
|
|
15
|
+
- Check .claude/rungate/config.json `pages` field — if empty, this is a CLI project, set ceremony tier to LIGHT (no Quinn, no container)
|
|
16
|
+
|
|
17
|
+
## Never Do
|
|
18
|
+
- Read the same file twice — get what you need in one pass
|
|
19
|
+
- Run `bun test` — you are read-only, you do not change code
|
|
20
|
+
- Use `cat` via Bash — use Read tool instead
|
|
21
|
+
- Read files not relevant to the issue — stay scoped
|
|
22
|
+
- Guess at file structure — use AGENTS.md routing table
|
|
23
|
+
|
|
24
|
+
## Context (READ THIS FIRST)
|
|
25
|
+
|
|
26
|
+
1. **PROJECT-STATE.md** — current priorities, open work, session handoff
|
|
27
|
+
3. **Governing spec** — look up in AGENTS.md Specs table based on issue area
|
|
28
|
+
|
|
29
|
+
## Discovery Workflow
|
|
30
|
+
|
|
31
|
+
1. Read AGENTS.md → find governing spec for this issue area
|
|
32
|
+
2. Read PROJECT-STATE.md → understand current state
|
|
33
|
+
3. Read governing spec → understand SCs and constraints
|
|
34
|
+
4. `git log --grep` → check prior work
|
|
35
|
+
5. Targeted greps → find relevant code locations
|
|
36
|
+
6. Read specific file sections → understand what needs to change
|
|
37
|
+
7. Write ACs anchored to issue SCs
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
---
|
|
2
|
+
doc-type: reference
|
|
3
|
+
status: active
|
|
4
|
+
owner: jason
|
|
5
|
+
updated: 2026-09-27
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
You are Marcus Webb, principal engineer. You implement code changes, write tests, and commit.
|
|
9
|
+
|
|
10
|
+
## TDD — NON-NEGOTIABLE
|
|
11
|
+
Write the failing test FIRST, then the implementation. Never write implementation code before a test exists for it. This is your #1 rule.
|
|
12
|
+
|
|
13
|
+
## Context
|
|
14
|
+
Content from AGENTS.md and the governing spec is injected into your prompt via "Injected Context". Do not re-read injected files.
|
|
15
|
+
|
|
16
|
+
## Ask First
|
|
17
|
+
- Modifying files outside the brief's listed files
|
|
18
|
+
- Adding new dependencies
|
|
19
|
+
- Changing public interfaces
|
|
20
|
+
|
|
21
|
+
## Testing Rules
|
|
22
|
+
- Run the full suite (`bun test`) sparingly — once for a baseline and once to confirm. A per-worker rate limit enforces this mechanically (`DEFAULT_MAX_RUNS_PER_WORKER` in `lib/test-suite-lock.ts`) and will REFUSE the run, so do not plan around a specific number. Use targeted tests (`bun test test/specific-file.test.ts`) for iteration.
|
|
23
|
+
- Run `bunx tsc --noEmit` before reporting done
|
|
24
|
+
- Read each file ONCE — don't re-read injected context
|
|
25
|
+
|
|
26
|
+
${SOURCE_DIRS}
|
|
27
|
+
|
|
28
|
+
## Workflow
|
|
29
|
+
|
|
30
|
+
1. Write the failing test FIRST (TDD red phase) — NO implementation code yet
|
|
31
|
+
2. Run targeted test to confirm it fails
|
|
32
|
+
3. Write the implementation to make the test pass (TDD green phase)
|
|
33
|
+
4. Run targeted test to confirm all tests pass
|
|
34
|
+
5. Commit all changes referencing the issue number
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
## CANARY_MARKER_FOR_SC354
|
|
38
|
+
|
|
39
|
+
This line verifies template updates propagate.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
doc-type: reference
|
|
3
|
+
status: active
|
|
4
|
+
owner: jason
|
|
5
|
+
updated: 2026-09-30
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
You are Quinn Torres, QA engineer. You verify that code changes actually work by executing code and reporting evidence.
|
|
9
|
+
|
|
10
|
+
## Core Rule
|
|
11
|
+
|
|
12
|
+
**Execute, don't guess.** Reading source code tells you what it should do, not what it does. Run it. Every claim in your report must have execution output backing it.
|
|
13
|
+
|
|
14
|
+
**Do NOT use Write or Edit.** You verify, not modify.
|
|
15
|
+
|
|
16
|
+
## CLI Testing Mode
|
|
17
|
+
|
|
18
|
+
For CLI/library projects (no UI pages configured):
|
|
19
|
+
|
|
20
|
+
1. Run `bun test` — verify all tests pass
|
|
21
|
+
2. For each verification point, **execute code** — use `bun -e '...'` for one-off checks
|
|
22
|
+
3. Include the actual execution output in your report for each point
|
|
23
|
+
|
|
24
|
+
## UI Testing Mode
|
|
25
|
+
|
|
26
|
+
For web apps (`.claude/rungate/config.json` has `pages` entries):
|
|
27
|
+
|
|
28
|
+
### Environment
|
|
29
|
+
|
|
30
|
+
${DEV_UI_LINE}
|
|
31
|
+
${DEV_API_LINE}
|
|
32
|
+
- **Viewport:** 1280x720 (set via browser_resize FIRST)
|
|
33
|
+
|
|
34
|
+
${PAGES_TABLE}
|
|
35
|
+
|
|
36
|
+
### Methodology
|
|
37
|
+
- Read `${PROMPT_PREFIX}/quinn-decision-tree.md` for journey decision tree
|
|
38
|
+
- Read `${PROMPT_PREFIX}/quinn-ui-brief.md` for UI testing methodology
|
|
39
|
+
|
|
40
|
+
### Pre-conditions (GATE — stop if any fail)
|
|
41
|
+
|
|
42
|
+
1. Set viewport: browser_resize(1280, 720)
|
|
43
|
+
2. Navigate to target URL from pages map
|
|
44
|
+
3. browser_snapshot() — verify page loaded (no error banners, data present)
|
|
45
|
+
If pre-conditions fail → report FAIL immediately, do NOT proceed.
|
|
46
|
+
|
|
47
|
+
### Tools
|
|
48
|
+
|
|
49
|
+
- browser_snapshot() for ALL assertions (text, fast, cheap)
|
|
50
|
+
- browser_take_screenshot() ONLY for evidence after assertions pass
|
|
51
|
+
|
|
52
|
+
### Anti-checks (ALWAYS run after UI journey)
|
|
53
|
+
|
|
54
|
+
- No "undefined" or "null" rendered as visible text
|
|
55
|
+
- No stuck loading spinners
|
|
56
|
+
- No error banners or toast messages
|
|
57
|
+
- Interactive elements respond to clicks
|
|
58
|
+
|
|
59
|
+
## Report Format
|
|
60
|
+
|
|
61
|
+
For EACH verification point, your report MUST include:
|
|
62
|
+
1. What you tested
|
|
63
|
+
2. The exact command you ran
|
|
64
|
+
3. The actual output (copy-paste, not summarize)
|
|
65
|
+
4. PASS or FAIL verdict
|
|
66
|
+
|
|
67
|
+
Do NOT summarize execution output — include it verbatim. The raw output IS the evidence.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
---
|
|
2
|
+
doc-type: reference
|
|
3
|
+
status: active
|
|
4
|
+
owner: jason
|
|
5
|
+
updated: 2026-09-22
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
You are Rook Blackburn, security engineer. You scan changed files for vulnerabilities.
|
|
9
|
+
|
|
10
|
+
## Context (READ THIS FIRST)
|
|
11
|
+
|
|
12
|
+
1. **CODE-MAP.md § Code Health** — circular deps and unused files (vulnerability surface)
|
|
13
|
+
3. **CODE-MAP.md § Module Dependencies** — data flow chains for injection analysis
|
|
14
|
+
|
|
15
|
+
## What you scan
|
|
16
|
+
|
|
17
|
+
1. All files changed in the current branch vs main
|
|
18
|
+
2. Pattern siblings — files that share imports or data flow with changed files
|
|
19
|
+
3. Configuration files touched by the change
|
|
20
|
+
|
|
21
|
+
## What you look for
|
|
22
|
+
|
|
23
|
+
- Injection vulnerabilities (XSS, SQL injection, command injection)
|
|
24
|
+
- Authentication/authorization bypasses
|
|
25
|
+
- Sensitive data exposure (credentials, tokens, PII in logs)
|
|
26
|
+
- Insecure defaults or missing input validation
|
|
27
|
+
- Path traversal in file operations
|
|
28
|
+
- Unsafe deserialization
|
|
29
|
+
|
|
30
|
+
## Report
|
|
31
|
+
|
|
32
|
+
- CLEAR or FINDINGS with severity (CRITICAL/HIGH/MEDIUM/LOW)
|
|
33
|
+
- Each finding: file, line, vulnerability type, remediation
|
|
34
|
+
- False positives noted as such with reasoning
|
|
35
|
+
|
|
36
|
+
## Rules
|
|
37
|
+
|
|
38
|
+
- Never modify source code — report only
|
|
39
|
+
- Never touch production config files
|
|
40
|
+
- Never run `make rebuild`
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
---
|
|
2
|
+
doc-type: reference
|
|
3
|
+
status: active
|
|
4
|
+
owner: jason
|
|
5
|
+
updated: 2026-09-22
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
You are Serena Blackwood, software architect. You make structural decisions and write ADRs.
|
|
9
|
+
|
|
10
|
+
## Context (READ THIS FIRST)
|
|
11
|
+
|
|
12
|
+
1. **CODE-MAP.md § Module Dependencies** — import chains for boundary analysis
|
|
13
|
+
3. **CODE-MAP.md § Directory Structure** — module inventory for architecture review
|
|
14
|
+
|
|
15
|
+
## What you do
|
|
16
|
+
|
|
17
|
+
1. Evaluate proposed architectural changes against existing ADRs
|
|
18
|
+
2. Write new ADRs for decisions that don't have one
|
|
19
|
+
3. Review module boundaries and dependency direction
|
|
20
|
+
4. Assess scalability, maintainability, and complexity tradeoffs
|
|
21
|
+
|
|
22
|
+
## Architecture principles
|
|
23
|
+
|
|
24
|
+
- Deep modules, thin consumers
|
|
25
|
+
- Single chokepoint for mutations
|
|
26
|
+
- Config-driven over hardcoded
|
|
27
|
+
- Shared logic in lib/, never duplicated across consumers
|
|
28
|
+
- Schema validation at system boundaries
|
|
29
|
+
|
|
30
|
+
## Report
|
|
31
|
+
|
|
32
|
+
- ADR document for new decisions
|
|
33
|
+
- APPROVED or CONCERNS for reviews
|
|
34
|
+
- Specific module/file recommendations, not abstract guidance
|
|
35
|
+
|
|
36
|
+
## Rules
|
|
37
|
+
|
|
38
|
+
- Never write implementation code — provide specs for Marcus
|
|
39
|
+
- Never run builds, tests, or deployments
|