mandrel 2.7.0 → 2.9.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 (95) hide show
  1. package/.agents/README.md +104 -330
  2. package/.agents/agents/auditor.md +135 -0
  3. package/.agents/agents/plan-critic.md +80 -0
  4. package/.agents/audit-checklists/dependencies.md +7 -0
  5. package/.agents/audit-checklists/documentation.md +1 -0
  6. package/.agents/docs/SDLC.md +69 -162
  7. package/.agents/docs/configuration.md +159 -499
  8. package/.agents/docs/quality-gates.md +59 -180
  9. package/.agents/instructions.md +170 -295
  10. package/.agents/rules/changelog-style.md +8 -66
  11. package/.agents/rules/ci-remediation.md +65 -124
  12. package/.agents/rules/gherkin-standards.md +10 -31
  13. package/.agents/rules/git-conventions-reference.md +28 -61
  14. package/.agents/rules/git-conventions.md +1 -1
  15. package/.agents/rules/orchestration-error-handling.md +5 -15
  16. package/.agents/rules/security-baseline.md +7 -13
  17. package/.agents/rules/shell-conventions.md +4 -13
  18. package/.agents/rules/test-seams.md +2 -2
  19. package/.agents/rules/testing-standards.md +7 -17
  20. package/.agents/schemas/agentrc.schema.json +21 -0
  21. package/.agents/scripts/audit-to-stories.js +51 -0
  22. package/.agents/scripts/lib/audit-to-stories/dedupe-against-github.js +120 -55
  23. package/.agents/scripts/lib/config-settings-schema.js +32 -0
  24. package/.agents/scripts/lib/findings/semantic-issue-search.js +43 -5
  25. package/.agents/scripts/lib/observability/terse-result.js +114 -0
  26. package/.agents/scripts/lib/orchestration/complexity-gate.js +207 -0
  27. package/.agents/scripts/lib/orchestration/plan-context.js +3 -0
  28. package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js +221 -8
  29. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +55 -14
  30. package/.agents/scripts/lib/orchestration/story-close/emit-blocked.js +9 -3
  31. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +4 -1
  32. package/.agents/scripts/lib/orchestration/task-body-validator.js +13 -40
  33. package/.agents/scripts/lib/story-body/body-format-lints.js +215 -0
  34. package/.agents/scripts/lib/story-body/story-body.js +18 -2
  35. package/.agents/scripts/lib/templates/decomposer-prompts.js +16 -0
  36. package/.agents/scripts/providers/github/issues.js +54 -7
  37. package/.agents/scripts/providers/github/search-budget.js +124 -0
  38. package/.agents/scripts/providers/github/search-query.js +71 -0
  39. package/.agents/scripts/single-story-confirm-merge.js +14 -5
  40. package/.agents/scripts/single-story-init.js +19 -3
  41. package/.agents/scripts/sync-branch-from-base.js +9 -3
  42. package/.agents/skills/core/api-and-interface-design/SKILL.md +23 -297
  43. package/.agents/skills/core/api-and-interface-design/reference.md +76 -0
  44. package/.agents/skills/core/browser-testing-with-devtools/SKILL.md +20 -327
  45. package/.agents/skills/core/browser-testing-with-devtools/reference.md +74 -0
  46. package/.agents/skills/core/code-review-and-quality/reference.md +16 -398
  47. package/.agents/skills/core/debugging-and-error-recovery/reference.md +14 -281
  48. package/.agents/skills/core/documentation-and-adrs/reference.md +42 -338
  49. package/.agents/skills/core/git-workflow-and-versioning/SKILL.md +28 -326
  50. package/.agents/skills/core/idea-refinement/SKILL.md +67 -193
  51. package/.agents/skills/core/security-and-hardening/SKILL.md +15 -31
  52. package/.agents/skills/core/security-and-hardening/reference.md +15 -273
  53. package/.agents/skills/skills.index.json +5 -5
  54. package/.agents/skills/stack/qa/gherkin-authoring/SKILL.md +16 -222
  55. package/.agents/skills/stack/qa/gherkin-authoring/reference.md +157 -0
  56. package/.agents/skills/stack/qa/playwright/SKILL.md +0 -29
  57. package/.agents/skills/stack/qa/qa-explore-driving/SKILL.md +19 -23
  58. package/.agents/skills/stack/qa/qa-harness/SKILL.md +35 -53
  59. package/.agents/skills/stack/qa/vitest/SKILL.md +0 -29
  60. package/.agents/workflows/audit-accessibility.md +34 -108
  61. package/.agents/workflows/audit-architecture.md +35 -123
  62. package/.agents/workflows/audit-clean-code.md +19 -78
  63. package/.agents/workflows/audit-data-model.md +32 -100
  64. package/.agents/workflows/audit-dependencies.md +47 -111
  65. package/.agents/workflows/audit-devops.md +16 -83
  66. package/.agents/workflows/audit-documentation.md +46 -93
  67. package/.agents/workflows/audit-navigability.md +26 -80
  68. package/.agents/workflows/audit-performance.md +40 -106
  69. package/.agents/workflows/audit-privacy.md +17 -80
  70. package/.agents/workflows/audit-quality.md +35 -99
  71. package/.agents/workflows/audit-security.md +20 -78
  72. package/.agents/workflows/audit-seo.md +20 -98
  73. package/.agents/workflows/audit-sre.md +20 -88
  74. package/.agents/workflows/audit-to-stories.md +1 -8
  75. package/.agents/workflows/audit-ux-ui.md +17 -80
  76. package/.agents/workflows/deliver.md +54 -9
  77. package/.agents/workflows/git-cleanup.md +50 -275
  78. package/.agents/workflows/helpers/audit-lens-core.md +230 -0
  79. package/.agents/workflows/helpers/code-review.md +11 -23
  80. package/.agents/workflows/helpers/deliver-story-reference.md +114 -17
  81. package/.agents/workflows/helpers/deliver-story.md +36 -186
  82. package/.agents/workflows/helpers/qa-core.md +174 -0
  83. package/.agents/workflows/helpers/qa-run-scenario-reference.md +35 -0
  84. package/.agents/workflows/helpers/qa-run-scenario.md +11 -25
  85. package/.agents/workflows/helpers/worktree-lifecycle.md +6 -67
  86. package/.agents/workflows/mandrel-update.md +7 -13
  87. package/.agents/workflows/plan.md +44 -17
  88. package/.agents/workflows/qa-assist.md +140 -269
  89. package/.agents/workflows/qa-explore.md +125 -316
  90. package/.agents/workflows/qa-run.md +180 -380
  91. package/docs/CHANGELOG.md +30 -0
  92. package/package.json +1 -1
  93. package/.agents/workflows/helpers/audit-dual-path.md +0 -59
  94. package/.agents/workflows/helpers/audit-self-check.md +0 -70
  95. package/.agents/workflows/helpers/audit-severity-scale.md +0 -19
@@ -4,59 +4,35 @@ description: Audit performance by measuring first — profile hot paths, I/O, me
4
4
 
5
5
  # Performance & Bottleneck Audit
6
6
 
7
- ## Role
8
-
9
- Performance Engineer & Systems Architect
10
-
11
- ## Context & Objective
12
-
13
- Find where a system is slow, wasteful, or unsafe under concurrency and prove
14
- it with numbers, not opinions. This lens has three standing commitments that
15
- separate it from a prose read-through:
16
-
17
- 1. **Measure before you judge.** A performance claim that is not backed by a
18
- profile, a timing, or a byte count is a hypothesis, not a finding. Step 0
19
- times the repo's own suite and entry points and produces the evidence every
20
- finding must cite.
21
- 2. **Adapt to the repo profile.** A CLI/tooling repo has no bundle and no Core
22
- Web Vitals; a frontend app does. Step 1 detects the target profile and
23
- activates only the dimensions that apply, declaring the rest inapplicable
24
- rather than fabricating findings for a surface that does not exist.
25
- 3. **Interleaving correctness is a performance concern.** The most expensive
26
- defects this repo has shipped were not slow loops — they were races
27
- (check-then-act on a lease, non-atomic checkout mutation under concurrent
28
- close, shared-cache poisoning). Step 2 treats interleaving & partial-failure
29
- correctness as a first-class dimension, statically and repo-observably.
30
-
31
- ## Scope (Story / plan-run mode)
32
-
33
- When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
34
- following block is populated with the Story (or plan-run) change-set file list.
35
- Otherwise — for any manual `/audit-<dimension>` invocation — the block
36
- renders the literal substitution token and you MUST treat it as **no
37
- scope filter — run the lens codebase-wide** exactly as you would have
38
- before this section existed.
7
+ You are a Performance Engineer & Systems Architect finding where a system is
8
+ slow, wasteful, or unsafe under concurrency — and proving it with numbers, not
9
+ opinions. Three standing commitments separate this lens from a prose
10
+ read-through: **measure before you judge** (a claim with no profile/timing/byte
11
+ count is a hypothesis, not a finding); **adapt to the repo profile** (activate
12
+ only the dimensions that apply, declaring the rest inapplicable); and
13
+ **interleaving correctness is a performance concern** (races have been the most
14
+ expensive defects this repo shipped). The shared lens machinery read-only
15
+ constraint, scope interpretation, report envelope + finding-block skeleton,
16
+ severity scale, self-cross-check, and execution strategy — lives in
17
+ [`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
18
+ `{{auditOutputDir}}/audit-performance-results.md`. Extra finding field:
19
+ **Evidence:** [a Step 0 repro command (or quoted code path) + a `measured` or
20
+ `estimated` tag]. The report adds a **Low-Hanging Fruit** section.
21
+
22
+ ## Scope
23
+
24
+ Interpret this lens's change-set fence per the core's Scope interpretation:
39
25
 
40
26
  ```text
41
27
  {{changedFiles}}
42
28
  ```
43
29
 
44
- - If the block above contains a newline-delimited list of file paths,
45
- restrict your analysis to those files (and their direct dependencies
46
- when the lens explicitly calls for cross-file reasoning).
47
- - If the block above renders as the literal string `{{changedFiles}}`
48
- (i.e. no substitution was supplied), ignore this section entirely and
49
- proceed with the full codebase-wide scan defined in the remaining
50
- steps.
30
+ ## Execution strategy
51
31
 
52
- ## Execution strategy (dual-path)
53
-
54
- This lens runs along one of two execution paths (orchestrated dynamic-workflow
55
- or sequential single-pass). Both emit the **identical** Step 4 report contract;
56
- downstream consumers (`audit-to-stories`) are agnostic to which path produced
57
- it. See [`helpers/audit-dual-path.md`](helpers/audit-dual-path.md) for strategy
58
- selection, the forcing flags, and the read-only guarantee — read `audit-<lens>`
59
- there as this lens's name.
32
+ This is a **heavyweight lens**: dispatch it as a single `subagent_type: auditor`
33
+ call, or fan its resource dimensions out per-dimension across parallel `auditor`
34
+ subagents (parallel-tooling Rule 3) and merge under the self-cross-check.
35
+ Sequential inline execution is the fallback (see the core's Execution strategy).
60
36
 
61
37
  > **Measurement is non-mutating, not forbidden.** This lens is read-only with
62
38
  > respect to source, but it MUST be allowed to *run* measurements. The
@@ -64,11 +40,11 @@ there as this lens's name.
64
40
  > **non-mutating command allowlist** (profilers, timers, bundle-stat and
65
41
  > file-size probes — never a command that writes source, installs, or mutates
66
42
  > git/labels). See the allowlist in
67
- > [`.claude/workflows/audit-performance.workflow.js`](../../.claude/workflows/audit-performance.workflow.js).
43
+ > [`../../.claude/workflows/audit-performance.workflow.js`](../../.claude/workflows/audit-performance.workflow.js).
68
44
 
69
45
  ## Step 0: Measure before you judge (mandatory)
70
46
 
71
- Produce evidence first; every finding in Step 4 carries an **Evidence** field
47
+ Produce evidence first; every finding in the report carries an **Evidence** field
72
48
  that cites a repro command and tags itself `measured` or `estimated`. Run the
73
49
  measurements that apply to the repo (Step 1 tells you which), preferring the
74
50
  repo's own scripts over invented ones.
@@ -180,9 +156,8 @@ dimension (per Step 1) against measured evidence from Step 0.
180
156
 
181
157
  ## Step 3: Severity rubric (performance-anchored)
182
158
 
183
- Grade every finding on the shared
184
- [`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md),
185
- anchored to performance/correctness cost rather than gut feel:
159
+ Grade every finding on the shared severity scale, anchored to
160
+ performance/correctness cost rather than gut feel:
186
161
 
187
162
  - Grade **Critical** for a guaranteed data-loss or corruption path under normal
188
163
  concurrency (e.g. a lost-update TOCTOU on persisted state), or a hang/outage
@@ -198,67 +173,26 @@ anchored to performance/correctness cost rather than gut feel:
198
173
  Latency thresholds, when a user-facing route is in scope, follow the CWV bands
199
174
  in the payload/bundle dimension (LCP ≤2.5s good / ≤4.0s needs-improvement).
200
175
 
201
- ## Step 4: Output Requirements
202
-
203
- Generate and save a highly structured Markdown audit report to
204
- `{{auditOutputDir}}/audit-performance-results.md`, using the exact template
205
- below.
206
-
207
- ```markdown
208
- # Performance Audit Report
176
+ ## Constraint (lens-specific carve-out)
209
177
 
210
- ## Executive Summary
178
+ This lens is read-only **with respect to source**: it does not edit, create, or
179
+ delete application code, dependencies, or configuration. It **does** run
180
+ non-mutating measurements (Step 0) and writes exactly two artifacts — the report
181
+ and `perf-baseline.json`.
211
182
 
212
- [Overview of performance posture vs the Step 0 measurements. State the repo
213
- profile detected (Step 1) and which dimensions were inapplicable. State the
214
- baseline trend verdict (first-run / improved / unchanged / regressed) and the
215
- `perf-baseline.json` path. Close with the self-cross-check `kept k / dropped d`
216
- line.]
183
+ The **interleaving** dimension leans on the self-cross-check hardest: drop every
184
+ claimed race that lacks a concrete losing interleaving over a repo-observable
185
+ shared-state path.
217
186
 
218
- ## Detailed Findings
187
+ ## Report additions
219
188
 
220
- [For every bottleneck or correctness defect identified, use the following
221
- strict structure. Lead each title with the primary file it lives in:]
189
+ Beyond the shared skeleton (Executive Summary + Detailed Findings from the
190
+ core), this lens's report carries its own title and a Low-Hanging Fruit section:
222
191
 
223
- ### `path/to/primary-file.ext` — [Short title of the finding]
224
-
225
- - **Dimension:** [CPU & algorithmic | I/O | Memory & leaks | Payload & bundle | Interleaving & partial-failure]
226
- - **Impact:** [Critical | High | Medium | Low]
227
- - **Location:** `path/to/primary-file.ext:line`
228
- - **Evidence:** [A repro command from Step 0 (or a quoted code path) and a
229
- `measured` or `estimated` tag — e.g. "`measured`: `hyperfine 'npm test'` →
230
- regressed 8.1s → 11.4s (+40%) vs perf-baseline.json"]
231
- - **Current State:** [Technical explanation of where and why the bottleneck or
232
- race occurs]
233
- - **Recommendation & Rationale:** [Specific optimization/fix tactic and the
234
- expected gain or the interleaving it closes]
235
- - **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. a benchmark below the target threshold, a re-run of this lens showing the baseline no longer regressed, or a test exercising the losing interleaving]
236
- - **Agent Prompt:**
237
- `[A copy-pasteable, highly specific prompt to execute this fix independently]`
192
+ ```markdown
193
+ # Performance Audit Report
238
194
 
239
195
  ## Low-Hanging Fruit
240
196
 
241
197
  - [List 3 quick changes that provide immediate performance gains.]
242
198
  ```
243
-
244
- ## Constraint
245
-
246
- This is a **read-only** audit **with respect to source**: it does not edit,
247
- create, or delete application code, dependencies, or configuration. It **does**
248
- run non-mutating measurements (Step 0) and writes exactly two artifacts — the
249
- report and `perf-baseline.json`. Note: this lens supersedes the retired
250
- `audit-lighthouse` lens by folding its measured Core-Web-Vitals material (the
251
- per-route score baseline and median-of-3 protocol) into the web branch of the
252
- payload/bundle dimension.
253
-
254
- ## Self-cross-check (mandatory — filter false positives before you finalize)
255
-
256
- Before you write the report artifact from the previous step, run the shared
257
- adversarial self-cross-check over your Detailed Findings — see
258
- [`helpers/audit-self-check.md`](helpers/audit-self-check.md). It defines the
259
- per-finding evidence bar, the exclusion list, and the final re-open-and-drop
260
- pass whose `kept <k> / dropped <d>` counts you record in the Executive
261
- Summary, so the sequential single-pass path filters unverified findings just as
262
- the orchestrated path's adversarial reviewer does. The **interleaving**
263
- dimension leans on this pass hardest: drop every claimed race that lacks a
264
- concrete losing interleaving over a repo-observable shared-state path.
@@ -4,41 +4,32 @@ description: Audit logs, telemetry, and persistence paths for PII leakage and re
4
4
 
5
5
  # Privacy and PII Data Audit
6
6
 
7
- ## Role
7
+ You are a Data Privacy Officer & Security Engineer finding accidental logging,
8
+ insecure storage, or unnecessary collection of PII, and checking GDPR/CCPA
9
+ compliance. The shared lens machinery — read-only constraint, scope
10
+ interpretation, report envelope + finding-block skeleton, severity scale,
11
+ self-cross-check, and execution strategy — lives in
12
+ [`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
13
+ `{{auditOutputDir}}/audit-privacy-results.md`. This lens labels the severity
14
+ axis **Impact** and uses dimension values `Leaky Log | Insecure Storage | Data
15
+ Over-collection`; its report adds a **Privacy Scorecard** section (Data
16
+ Encryption / Logging Safety / Minimization: Pass/Fail/Partial).
8
17
 
9
- Data Privacy Officer & Security Engineer
18
+ ## Scope
10
19
 
11
- ## Context & Objective
12
-
13
- You are conducting a privacy audit to identify potential mishandling of
14
- Personally Identifiable Information (PII) and ensure compliance with data
15
- protection standards (GDPR, CCPA). Your goal is to find accidental logging,
16
- insecure storage, or unnecessary collection of sensitive data.
17
-
18
- ## Scope (Story / plan-run mode)
19
-
20
- When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
21
- following block is populated with the Story (or plan-run) change-set file list.
22
- Otherwise — for any manual `/audit-<dimension>` invocation — the block
23
- renders the literal substitution token and you MUST treat it as **no
24
- scope filter — run the lens codebase-wide** exactly as you would have
25
- before this section existed.
20
+ Interpret this lens's change-set fence per the core's Scope interpretation:
26
21
 
27
22
  ```text
28
23
  {{changedFiles}}
29
24
  ```
30
25
 
31
- - If the block above contains a newline-delimited list of file paths,
32
- restrict your analysis to those files (and their direct dependencies
33
- when the lens explicitly calls for cross-file reasoning).
34
- - If the block above renders as the literal string `{{changedFiles}}`
35
- (i.e. no substitution was supplied), ignore this section entirely and
36
- proceed with the full codebase-wide scan defined in the remaining
37
- steps.
26
+ ## Execution strategy
38
27
 
39
- ## Step 1: Sink-First Detection
28
+ Run this lens as a single `subagent_type: auditor` dispatch returning the report
29
+ path + Executive Summary; sequential inline execution is the fallback (see the
30
+ core's Execution strategy).
40
31
 
41
- > Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scan below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
32
+ ## Step 1: Sink-First Detection
42
33
 
43
34
  A PII leak is a **source → sink** flow: sensitive data reaching an egress point.
44
35
  Enumerate the **sinks** first, then trace which ones receive PII. Report only
@@ -86,57 +77,3 @@ Evaluate the codebase against these privacy pillars:
86
77
  in plain text?
87
78
  5. **Consent & Retention:** Check for logic related to data deletion (Right to
88
79
  be Forgotten) and consent management.
89
-
90
- ## Step 3: Output Requirements
91
-
92
- Generate and save a highly structured Markdown audit report to
93
- `{{auditOutputDir}}/audit-privacy-results.md`, using the exact template below.
94
-
95
- > Grade every finding's severity on the shared
96
- > [`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md).
97
-
98
- ```markdown
99
- # Privacy & PII Audit Report
100
-
101
- ## Executive Summary
102
-
103
- [Overview of the privacy posture and critical risks identified.]
104
-
105
- ## Privacy Scorecard
106
-
107
- - **Data Encryption:** [Pass/Fail/Partial]
108
- - **Logging Safety:** [Pass/Fail/Partial]
109
- - **Minimization:** [Pass/Fail/Partial]
110
-
111
- ## Detailed Findings
112
-
113
- [For every gap identified, use the following strict structure. Lead each title
114
- with the primary file the finding lives in:]
115
-
116
- ### `path/to/primary-file.ext` — [Short title of the issue]
117
-
118
- - **Dimension:** [Leaky Log | Insecure Storage | Data Over-collection]
119
- - **Impact:** [Critical | High | Medium | Low]
120
- - **Location:** `path/to/primary-file.ext:line`
121
- - **Current State:** [The specific file/line/module and why it is problematic]
122
- - **Recommendation & Rationale:** [How to remediate and why it's necessary for
123
- compliance]
124
- - **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. a grep for the leaky log that now returns empty, or a re-run of this lens]
125
- - **Agent Prompt:**
126
- `[A copy-pasteable, highly specific prompt to execute this remediation independently]`
127
- ```
128
-
129
- ## Constraint
130
-
131
- This is a **read-only** audit. Do not modify any code. Focus on identifying
132
- risks and providing clear remediation steps.
133
-
134
- ## Self-cross-check (mandatory — filter false positives before you finalize)
135
-
136
- Before you write the report artifact from the previous step, run the shared
137
- adversarial self-cross-check over your Detailed Findings — see
138
- [`helpers/audit-self-check.md`](helpers/audit-self-check.md). It defines the
139
- per-finding evidence bar, the exclusion list, and the final re-open-and-drop
140
- pass whose `kept <k> / dropped <d>` counts you record in the Executive
141
- Summary, so the sequential single-pass path filters unverified findings just as
142
- the orchestrated path's adversarial reviewer does.
@@ -4,55 +4,31 @@ description: Audit test coverage gaps, flaky tests, missing assertions, and test
4
4
 
5
5
  # Testing & Quality Assurance Audit
6
6
 
7
- ## Role
8
-
9
- Principal SDET (Software Development Engineer in Test) & Quality Architect
10
-
11
- ## Context & Objective
12
-
13
- You are performing a comprehensive, read-only audit of this repository's testing
14
- infrastructure, test coverage, and overall quality assurance practices. Your
15
- goal is to identify testing gaps, flaky tests, inefficient mocking strategies,
16
- and opportunities to improve test execution speed and reliability without making
17
- any immediate changes. Additionally, you must evaluate the implemented tests
18
- against the Story under audit and the current codebase to ensure all quality
19
- requirements are met and correctly documented.
20
-
21
- **Note on Testing Responsibilities**: When evaluating test maturity, note the
22
- established standard: Software Engineers (SWEs) must provide comprehensive unit
23
- and integration test coverage alongside their feature implementations. The QA
24
- Engineering function focuses on End-to-End (E2E) testing, complex system
25
- integrations, and test environment stability.
26
-
27
- ## Scope (Story / plan-run mode)
28
-
29
- When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
30
- following block is populated with the Story (or plan-run) change-set file list.
31
- Otherwise — for any manual `/audit-<dimension>` invocation — the block
32
- renders the literal substitution token and you MUST treat it as **no
33
- scope filter — run the lens codebase-wide** exactly as you would have
34
- before this section existed.
7
+ You are a Principal SDET & Quality Architect auditing the repository's testing
8
+ infrastructure, coverage, flaky tests, mocking strategy, and test-pyramid
9
+ balance and, in Story-scoped mode, evaluating the implemented tests against
10
+ the Story under audit. The shared lens machinery — read-only constraint, scope
11
+ interpretation, report envelope + finding-block skeleton, severity scale,
12
+ self-cross-check, and execution strategy — lives in
13
+ [`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
14
+ `{{auditOutputDir}}/audit-quality-results.md`. Each finding carries a
15
+ **Category:** (`Flakiness | Coverage | Performance | Mocking | Test Plans`); the
16
+ report adds a **Test Strategy Assessment** table (Unit / Integration / E2E /
17
+ Test Plans: Healthy / Needs Work / Missing).
18
+
19
+ ## Scope
20
+
21
+ Interpret this lens's change-set fence per the core's Scope interpretation:
35
22
 
36
23
  ```text
37
24
  {{changedFiles}}
38
25
  ```
39
26
 
40
- - If the block above contains a newline-delimited list of file paths,
41
- restrict your analysis to those files (and their direct dependencies
42
- when the lens explicitly calls for cross-file reasoning).
43
- - If the block above renders as the literal string `{{changedFiles}}`
44
- (i.e. no substitution was supplied), ignore this section entirely and
45
- proceed with the full codebase-wide scan defined in the remaining
46
- steps.
27
+ ## Execution strategy
47
28
 
48
- ## Execution strategy (dual-path)
49
-
50
- This lens runs along one of two execution paths (orchestrated dynamic-workflow
51
- or sequential single-pass). Both emit the **identical** Step 3 report contract;
52
- downstream consumers (`audit-to-stories`) are agnostic to which path produced
53
- it. See [`helpers/audit-dual-path.md`](helpers/audit-dual-path.md) for strategy
54
- selection, the forcing flags, and the read-only guarantee — read `audit-<lens>`
55
- there as this lens's name.
29
+ Run this lens as a single `subagent_type: auditor` dispatch returning the report
30
+ path + Executive Summary; sequential inline execution is the fallback (see the
31
+ core's Execution strategy).
56
32
 
57
33
  ## Step 0 - Mode split + tool-first artifact read (mandatory)
58
34
 
@@ -60,13 +36,13 @@ there as this lens's name.
60
36
  do not share a Step 0 — a codebase-wide run must not try to read a Story it was
61
37
  never given.
62
38
 
63
- - **Story-scoped mode** (the `## Scope` block above is populated with a change
64
- set): read the Story under audit — its `## Goal`, inline `acceptance[]` /
39
+ - **Story-scoped mode** (the change-set fence is populated with a change set):
40
+ read the Story under audit — its `## Goal`, inline `acceptance[]` /
65
41
  `verify[]`, and folded `## Spec` — to identify the target features, and scope
66
42
  the audit to the change set and its direct dependencies.
67
- - **Codebase-wide mode** (the `## Scope` block renders the literal
68
- `{{changedFiles}}` token): there is **no Story** — do not look for one. Audit
69
- the whole test surface, ranked (below).
43
+ - **Codebase-wide mode** (the fence renders the literal `{{changedFiles}}`
44
+ token): there is **no Story** — do not look for one. Audit the whole test
45
+ surface, ranked (below).
70
46
 
71
47
  **Read the committed test-quality artifacts as evidence** (both modes). This
72
48
  lens grounds every coverage/quality claim in the metrics the delivery gates
@@ -96,8 +72,6 @@ the Constraint) — it is not "running the suite".
96
72
 
97
73
  ## Step 1: Context Gathering (Read-Only Scan)
98
74
 
99
- > Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scan below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
100
-
101
75
  Before generating the report, silently scan the workspace for testing-related
102
76
  files. Pay special attention to:
103
77
 
@@ -134,22 +108,23 @@ Evaluate the gathered context against the following test quality dimensions:
134
108
  Verify that the implementation found in the codebase correctly matches the
135
109
  architectural requirements and highlight any inconsistencies or gaps.
136
110
 
137
- ## Step 3: Output Requirements
111
+ ## Constraint (lens-specific carve-out)
112
+
113
+ Do NOT **run** the test suite (do not invoke `npm test`, a coverage run, or a
114
+ mutation run — those mutate state and cost minutes). Reading the **committed**
115
+ coverage / CRAP / mutation artifacts under `baselines/` is explicitly permitted
116
+ and required (Step 0): citing an already-computed metric is read-only analysis,
117
+ not a suite run.
138
118
 
139
- Generate and save a highly structured Markdown audit report to
140
- `{{auditOutputDir}}/audit-quality-results.md`, using the exact template below.
119
+ ## Report additions
141
120
 
142
- > Grade every finding's severity on the shared
143
- > [`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md).
121
+ Beyond the shared skeleton (Executive Summary + Detailed Findings from the
122
+ core), this lens's report carries its own title and a Test Strategy Assessment
123
+ table:
144
124
 
145
125
  ```markdown
146
126
  # Testing & Quality Assurance Audit
147
127
 
148
- ## Executive Summary
149
-
150
- [Provide a brief overview of the current test suite health, highlighting the
151
- primary vulnerabilities, coverage gaps, and areas causing developer friction.]
152
-
153
128
  ## Test Strategy Assessment
154
129
 
155
130
  | Layer | Status | Notes |
@@ -158,43 +133,4 @@ primary vulnerabilities, coverage gaps, and areas causing developer friction.]
158
133
  | Integration Testing | [Healthy / Needs Work / Missing] | [Brief reason] |
159
134
  | E2E Testing | [Healthy / Needs Work / Missing] | [Brief reason] |
160
135
  | Test Plans | [Healthy / Needs Work / Missing] | [Brief reason] |
161
-
162
- ## Detailed Findings
163
-
164
- [For every gap identified, use the following strict structure. Lead each title
165
- with the primary file the finding lives in:]
166
-
167
- ### `path/to/primary-file.ext` — [Short title of the issue]
168
-
169
- - **Category:** [Flakiness | Coverage | Performance | Mocking | Test Plans]
170
- - **Impact:** [Critical | High | Medium | Low]
171
- - **Location:** `path/to/primary-file.ext:line`
172
- - **Current State:** [How the tests are currently written and why it's
173
- problematic]
174
- - **Recommendation & Rationale:** [The specific testing pattern or refactor
175
- strategy to fix the issue]
176
- - **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. the new test failing before / passing after the fix, a coverage re-check, or a re-run of this lens]
177
- - **Agent Prompt:**
178
- `[A copy-pasteable, highly specific prompt to execute this fix independently]`
179
136
  ```
180
-
181
- ---
182
-
183
- ## Constraint
184
-
185
- Do NOT execute any code modifications, edit files, create branches, or **run**
186
- the test suite (do not invoke `npm test`, a coverage run, or a mutation run —
187
- those mutate state and cost minutes). Reading the **committed** coverage / CRAP
188
- / mutation artifacts under `baselines/` is explicitly permitted and required
189
- (Step 0): citing an already-computed metric is read-only analysis, not a suite
190
- run. Output the report and stop.
191
-
192
- ## Self-cross-check (mandatory — filter false positives before you finalize)
193
-
194
- Before you write the report artifact from the previous step, run the shared
195
- adversarial self-cross-check over your Detailed Findings — see
196
- [`helpers/audit-self-check.md`](helpers/audit-self-check.md). It defines the
197
- per-finding evidence bar, the exclusion list, and the final re-open-and-drop
198
- pass whose `kept <k> / dropped <d>` counts you record in the Executive
199
- Summary, so the sequential single-pass path filters unverified findings just as
200
- the orchestrated path's adversarial reviewer does.
@@ -5,45 +5,30 @@ command: false
5
5
 
6
6
  # Security & Vulnerability Audit
7
7
 
8
- ## Role
8
+ You are a Cybersecurity Architect & Penetration Tester conducting a
9
+ comprehensive security review (OWASP Top 10, insecure configs, attack vectors).
10
+ The shared lens machinery — read-only constraint, scope interpretation, report
11
+ envelope + finding-block skeleton, severity scale, self-cross-check, and
12
+ execution strategy — lives in
13
+ [`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
14
+ `{{auditOutputDir}}/audit-security-results.md`. Extra finding fields: **CWE
15
+ ID:** and **Baseline MUST:** (the violated `security-baseline.md` MUST). The
16
+ report adds a **Defensive Recommendations** section (3–5 headers/configs/
17
+ libraries to harden the app).
9
18
 
10
- Cybersecurity Architect & Penetration Tester
19
+ ## Scope
11
20
 
12
- ## Context & Objective
13
-
14
- Conduct a comprehensive security review of the codebase. Your goal is to
15
- identify common vulnerabilities (OWASP Top 10), insecure configurations, and
16
- potential attack vectors.
17
-
18
- ## Scope (Story / plan-run mode)
19
-
20
- When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
21
- following block is populated with the Story (or plan-run) change-set file list.
22
- Otherwise — for any manual `/audit-<dimension>` invocation — the block
23
- renders the literal substitution token and you MUST treat it as **no
24
- scope filter — run the lens codebase-wide** exactly as you would have
25
- before this section existed.
21
+ Interpret this lens's change-set fence per the core's Scope interpretation:
26
22
 
27
23
  ```text
28
24
  {{changedFiles}}
29
25
  ```
30
26
 
31
- - If the block above contains a newline-delimited list of file paths,
32
- restrict your analysis to those files (and their direct dependencies
33
- when the lens explicitly calls for cross-file reasoning).
34
- - If the block above renders as the literal string `{{changedFiles}}`
35
- (i.e. no substitution was supplied), ignore this section entirely and
36
- proceed with the full codebase-wide scan defined in the remaining
37
- steps.
38
-
39
- ## Execution strategy (dual-path)
27
+ ## Execution strategy
40
28
 
41
- This lens runs along one of two execution paths (orchestrated dynamic-workflow
42
- or sequential single-pass). Both emit the **identical** Step 3 report contract;
43
- downstream consumers (`audit-to-stories`) are agnostic to which path produced
44
- it. See [`helpers/audit-dual-path.md`](helpers/audit-dual-path.md) for strategy
45
- selection, the forcing flags, and the read-only guarantee — read `audit-<lens>`
46
- there as this lens's name.
29
+ Run this lens as a single `subagent_type: auditor` dispatch returning the report
30
+ path + Executive Summary; sequential inline execution is the fallback (see the
31
+ core's Execution strategy).
47
32
 
48
33
  ## Rubric — `rules/security-baseline.md` is the contract
49
34
 
@@ -59,8 +44,6 @@ baseline is silent — is out of scope for this lens.
59
44
 
60
45
  ## Step 1: Detection Battery (Tool-First, Read-Only)
61
46
 
62
- > Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scan below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
63
-
64
47
  Ground every finding in tool output, not vibes. Run the ladder below; each rung
65
48
  is **presence-gated** — when a scanner is absent, fall through to the next rung
66
49
  and note the missing tool as a `Security Misconfiguration` finding (recommend
@@ -122,58 +105,17 @@ CWE where one applies):
122
105
  5. **Vulnerable Components:** Are outdated libraries introducing risks? —
123
106
  _Dependency Hygiene_.
124
107
 
125
- ## Step 3: Output Requirements
126
-
127
- Generate and save a highly structured Markdown audit report to
128
- `{{auditOutputDir}}/audit-security-results.md`, using the exact template below.
108
+ ## Report additions
129
109
 
130
- > Grade every finding's severity on the shared
131
- > [`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md).
110
+ Beyond the shared skeleton (Executive Summary + Detailed Findings from the
111
+ core), this lens's report carries its own title and a Defensive Recommendations
112
+ section, and each finding adds the CWE ID / Baseline MUST fields:
132
113
 
133
114
  ```markdown
134
115
  # Security Audit Report
135
116
 
136
- ## Executive Summary
137
-
138
- [Overview of the risk profile (Critical/High/Medium/Low) and overarching
139
- security posture.]
140
-
141
- ## Detailed Findings
142
-
143
- [For every vulnerability identified, use the following strict structure. Lead
144
- each title with the primary file the vulnerability lives in:]
145
-
146
- ### `path/to/primary-file.ext` — [Short title of the vulnerability]
147
-
148
- - **Dimension:** [e.g., Injection | Broken Access Control]
149
- - **Severity:** [Critical | High | Medium | Low]
150
- - **CWE ID:** [e.g., CWE-89 for SQL Injection]
151
- - **Baseline MUST:** [the violated `security-baseline.md` MUST — e.g. "Secrets Management: fallback secrets MUST NOT be committed"]
152
- - **Location:** `path/to/primary-file.ext:line`
153
- - **Current State:** [Technical explanation of the flaw and its location]
154
- - **Recommendation & Rationale:** [Step-by-step fix and defensive hardening
155
- strategy]
156
- - **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. the exploit no longer reproducing, an added regression test, or a re-run of this lens]
157
- - **Agent Prompt:**
158
- `[A copy-pasteable, highly specific prompt to execute this remediation independently]`
159
-
160
117
  ## Defensive Recommendations
161
118
 
162
119
  - [List 3-5 security headers, configurations, or libraries to implement to
163
120
  harden the app.]
164
121
  ```
165
-
166
- ## Constraint
167
-
168
- This is a **read-only** audit. Your priority is accuracy and clear impact
169
- assessment. Do not attempt to exploit the system or modify code.
170
-
171
- ## Self-cross-check (mandatory — filter false positives before you finalize)
172
-
173
- Before you write the report artifact from the previous step, run the shared
174
- adversarial self-cross-check over your Detailed Findings — see
175
- [`helpers/audit-self-check.md`](helpers/audit-self-check.md). It defines the
176
- per-finding evidence bar, the exclusion list, and the final re-open-and-drop
177
- pass whose `kept <k> / dropped <d>` counts you record in the Executive
178
- Summary, so the sequential single-pass path filters unverified findings just as
179
- the orchestrated path's adversarial reviewer does.