rungate 0.4.0 → 0.5.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.
Files changed (65) hide show
  1. package/config/behavioral-sc-map.json +170 -0
  2. package/config/brief-policies.json +28 -0
  3. package/config/ceremony-profiles.json +207 -0
  4. package/config/check-registry.json +114 -0
  5. package/config/matcher-registry.json +142 -0
  6. package/config/prove-evidence.schema.json +65 -0
  7. package/config/spec-policies.json +36 -0
  8. package/config/universal-rules.yaml +15 -0
  9. package/config/workflow-schema.json +279 -0
  10. package/lib/ac-quality.ts +119 -0
  11. package/lib/cli-commands.ts +7 -1
  12. package/lib/config-loader.ts +129 -5
  13. package/lib/conformity.ts +1122 -31
  14. package/lib/context-docs.ts +182 -0
  15. package/lib/create-brief.ts +22 -17
  16. package/lib/create-sc.ts +35 -8
  17. package/lib/doc-scan-targets.ts +435 -0
  18. package/lib/gate-check-audit.ts +9 -9
  19. package/lib/github.ts +195 -0
  20. package/lib/js-top-level-code.ts +27 -2
  21. package/lib/organize.ts +129 -40
  22. package/lib/package-closure.ts +387 -0
  23. package/lib/project-aliases.ts +100 -0
  24. package/lib/release-preflight.ts +352 -48
  25. package/lib/rungate-schema.ts +23 -1
  26. package/lib/sc-cover.ts +92 -1
  27. package/lib/sc-ids.ts +151 -0
  28. package/lib/scaffold/defaults.ts +40 -0
  29. package/lib/scaffold/managed-workflow.ts +125 -27
  30. package/lib/scaffold/owned-files.ts +6 -0
  31. package/lib/scaffold/profiles.ts +94 -0
  32. package/lib/scaffold/rehearsal.ts +355 -0
  33. package/lib/scaffold/steps.ts +787 -105
  34. package/lib/scaffold/write-steps.ts +208 -0
  35. package/lib/scratch-cleanup.ts +198 -0
  36. package/lib/scratch-roots.ts +94 -0
  37. package/lib/source-anchor.ts +144 -0
  38. package/lib/success-doc.ts +779 -0
  39. package/lib/suite-run-reading.ts +194 -0
  40. package/lib/test-census.ts +199 -0
  41. package/lib/trajectory.ts +377 -0
  42. package/lib/validators/spec-validators.ts +52 -35
  43. package/lib/workflow-security.ts +152 -7
  44. package/lib/workflow-test-harness.ts +349 -0
  45. package/lib/worktree-cleanup.ts +123 -7
  46. package/lib/worktree-repo.ts +165 -0
  47. package/package.json +10 -1
  48. package/scripts/audit-specs.ts +134 -37
  49. package/scripts/audit-transcript.ts +259 -0
  50. package/scripts/create-sc.ts +15 -1
  51. package/scripts/create-success.ts +162 -0
  52. package/scripts/detect-sc-drift.ts +200 -0
  53. package/scripts/extract-constraints.ts +16 -36
  54. package/scripts/scaffold-project.ts +51 -137
  55. package/scripts/split-spec.ts +315 -0
  56. package/scripts/sync-sc-status.ts +751 -0
  57. package/specs/SPEC-TEMPLATE.md +200 -0
  58. package/templates/SUCCESS-TEMPLATE.md +72 -0
  59. package/templates/agent-briefs/_shared.md +9 -0
  60. package/templates/agent-briefs/aditi.md +46 -0
  61. package/templates/agent-briefs/discovery.md +37 -0
  62. package/templates/agent-briefs/marcus.md +39 -0
  63. package/templates/agent-briefs/quinn.md +67 -0
  64. package/templates/agent-briefs/rook.md +40 -0
  65. 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