mandrel 2.95.0 → 2.96.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/audit-checklists/red-team.md +20 -0
- package/.agents/docs/workflows.md +3 -1
- package/.agents/schemas/audit-rules.json +16 -0
- package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
- package/.agents/scripts/lint-issue-body.js +65 -10
- package/.agents/workflows/audit-red-team.md +191 -0
- package/.agents/workflows/audit-security.md +4 -1
- package/.agents/workflows/mandrel-leverage.md +199 -0
- package/.agents/workflows/mandrel-plan.md +3 -1
- package/docs/CHANGELOG.md +14 -0
- package/package.json +1 -1
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
<!-- GENERATED FILE — do not edit by hand.
|
|
2
|
+
Source of truth: .agents/workflows/audit-red-team.md
|
|
3
|
+
Regenerate: node .agents/scripts/generate-lens-checklists.js
|
|
4
|
+
Drift is gated by: npm run docs:check
|
|
5
|
+
-->
|
|
6
|
+
|
|
7
|
+
# Red-Team Audit — authoring checklist
|
|
8
|
+
|
|
9
|
+
> Audit the project as a goal-directed adversary — attack paths that chain two or more crossings, abuse of intended features, agent exposure to hostile repository or inbound content, hostile operations and operator hazards — graded under a reproduced-or-reasoned evidence bar. A d…
|
|
10
|
+
|
|
11
|
+
Self-check your change against this lens's concerns before you ship:
|
|
12
|
+
|
|
13
|
+
- [ ] Promises.
|
|
14
|
+
- [ ] Adversaries.
|
|
15
|
+
- [ ] Agent-facing surfaces.
|
|
16
|
+
- [ ] Attack Path
|
|
17
|
+
- [ ] Abuse & Misuse
|
|
18
|
+
- [ ] Agent Exposure
|
|
19
|
+
- [ ] Hostile Operations
|
|
20
|
+
- [ ] Operator Hazard
|
|
@@ -51,7 +51,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
|
|
|
51
51
|
fails when it drifts from the on-disk workflow set. To change a command’s
|
|
52
52
|
description, edit the workflow file’s front-matter and regenerate.
|
|
53
53
|
|
|
54
|
-
## Commands (
|
|
54
|
+
## Commands (35)
|
|
55
55
|
|
|
56
56
|
| Command | Description |
|
|
57
57
|
| --- | --- |
|
|
@@ -71,6 +71,7 @@ description, edit the workflow file’s front-matter and regenerate.
|
|
|
71
71
|
| `/audit-performance` | Audit performance by measuring first — profile hot paths, I/O, memory, and payload against the repo's own numbers — and audit interleaving/partial-failure correctness (TOCTOU, unawaited promises, non-atomic writes) as a first-class dimension. |
|
|
72
72
|
| `/audit-privacy` | Audit logs, telemetry, and persistence paths for PII leakage and retention violations; surface secrets exposure and consent gaps. |
|
|
73
73
|
| `/audit-quality` | Audit test coverage gaps, flaky tests, missing assertions, and test-pyramid balance; recommend a remediation batch. |
|
|
74
|
+
| `/audit-red-team` | Audit the project as a goal-directed adversary — attack paths that chain two or more crossings, abuse of intended features, agent exposure to hostile repository or inbound content, hostile operations and operator hazards — graded under a reproduced-or-reasoned evidence bar. A deliberately-global lens that runs on any project. |
|
|
74
75
|
| `/audit-security` | Audit dependency CVEs, input-validation gaps, secrets handling, auth boundaries, and the trust-boundary attack classes the baseline is silent on (business logic, SSRF/traversal, deserialization, crypto misuse, feature abuse, LLM tool-binding); emit a structured High/Medium/Low findings report. |
|
|
75
76
|
| `/audit-seo` | Audit SEO fundamentals and Generative Engine Optimization signals (meta, structured data, crawlability); only relevant for web targets. |
|
|
76
77
|
| `/audit-sre` | "Audit production-readiness for a release candidate: SLOs, observability, runbooks, error budgets, and rollback paths." |
|
|
@@ -81,6 +82,7 @@ description, edit the workflow file’s front-matter and regenerate.
|
|
|
81
82
|
| `/clean-worktrees` | Reclaim disk from dead worktrees: list every worktree of this project as a removal candidate (closed Story, merged branch, orphaned directory, detached HEAD) or as kept with a reason, then remove candidates only on `--execute`. |
|
|
82
83
|
| `/git-deliver` | Single ad-hoc delivery command for working-tree changes. Detects the git setup and escalates to the right terminal step — commit only, commit + push, or commit + push + open a PR with native auto-merge — picking the default from observable state and letting flags pin any level explicitly. Replaces the retired git-commit-all, git-push, and git-pr-all trio. |
|
|
83
84
|
| `/mandrel-deliver` | Unified delivery entry point. Takes Story ids or a plain-language prompt, derives which path the work belongs on, and lands it via the single deliver-story engine — story-<id> → PR → main. |
|
|
85
|
+
| `/mandrel-leverage` | Evidence-cited leverage review — draft five to twelve bets on how the project could be ~10x more useful, reliable or valuable, refute most of them with two maker-blind skeptics each, write the survivors, downgrades and refutations to temp/leverage/<run-id>/bets.md, and hand each survivor to /mandrel-plan behind a HITL gate. |
|
|
84
86
|
| `/mandrel-plan` | Unified planning entry point. Interrogate → author → persist. Emits one Story by default; splits into N>1 only under the default-single split policy. |
|
|
85
87
|
| `/mandrel-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the stabilized quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the dependency bump the CLI's closing report describes. |
|
|
86
88
|
| `/memory-consolidate` | Attended consolidation pass over this project's agent memory pool — merge duplicates, verify claims against the current tree, prune with operator confirmation, rewrite the index, and stamp the pool with the date and entry count the /mandrel-plan advisory measures its next nudge against. |
|
|
@@ -434,6 +434,22 @@
|
|
|
434
434
|
},
|
|
435
435
|
"scope": "global",
|
|
436
436
|
"substitutionKeys": []
|
|
437
|
+
},
|
|
438
|
+
"audit-red-team": {
|
|
439
|
+
"triggers": {
|
|
440
|
+
"gates": ["gate3"],
|
|
441
|
+
"keywords": [
|
|
442
|
+
"red team",
|
|
443
|
+
"red-team",
|
|
444
|
+
"adversarial",
|
|
445
|
+
"threat model",
|
|
446
|
+
"attack path",
|
|
447
|
+
"abuse case",
|
|
448
|
+
"blast radius"
|
|
449
|
+
]
|
|
450
|
+
},
|
|
451
|
+
"scope": "global",
|
|
452
|
+
"substitutionKeys": []
|
|
437
453
|
}
|
|
438
454
|
},
|
|
439
455
|
"sensitivePaths": {
|
|
@@ -21,6 +21,30 @@ const REQUIRED_SECTIONS = [
|
|
|
21
21
|
{ field: 'verify', label: 'Verify' },
|
|
22
22
|
];
|
|
23
23
|
|
|
24
|
+
/** The closed set of section names a comment may print. */
|
|
25
|
+
const SECTION_LABELS = new Map([
|
|
26
|
+
['goal', 'Goal'],
|
|
27
|
+
['acceptance', 'Acceptance'],
|
|
28
|
+
['verify', 'Verify'],
|
|
29
|
+
['changes', 'Changes'],
|
|
30
|
+
['references', 'References'],
|
|
31
|
+
['spec', 'Spec'],
|
|
32
|
+
['context', 'Context'],
|
|
33
|
+
['slicing', 'Slicing'],
|
|
34
|
+
['non_goals', 'Non-Goals'],
|
|
35
|
+
]);
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Fixed-vocabulary problem line for a parse failure. `err.message` and
|
|
39
|
+
* `err.raw` echo issue text, so they go to the run log, never the comment.
|
|
40
|
+
*/
|
|
41
|
+
function parseFailureProblem(err) {
|
|
42
|
+
const label = SECTION_LABELS.get(err.field);
|
|
43
|
+
return label
|
|
44
|
+
? `The \`## ${label}\` section could not be parsed into the canonical schema.`
|
|
45
|
+
: 'An unrecognised section could not be parsed into the canonical schema.';
|
|
46
|
+
}
|
|
47
|
+
|
|
24
48
|
/**
|
|
25
49
|
* Issue Forms render a skipped field as `_No response_`; treat it as absent.
|
|
26
50
|
* @param {string} body
|
|
@@ -39,6 +63,7 @@ function stripNoResponseSentinel(body) {
|
|
|
39
63
|
* @property {string[]} problems
|
|
40
64
|
* @property {string[]} warnings
|
|
41
65
|
* @property {boolean} parseFailed
|
|
66
|
+
* @property {string|null} parseError - Full parser message; run log only.
|
|
42
67
|
*/
|
|
43
68
|
|
|
44
69
|
/**
|
|
@@ -54,6 +79,7 @@ export function evaluateIssueBody(body) {
|
|
|
54
79
|
problems: ['The issue body is empty.'],
|
|
55
80
|
warnings: [],
|
|
56
81
|
parseFailed: true,
|
|
82
|
+
parseError: null,
|
|
57
83
|
};
|
|
58
84
|
}
|
|
59
85
|
|
|
@@ -66,11 +92,10 @@ export function evaluateIssueBody(body) {
|
|
|
66
92
|
if (err instanceof StoryBodyParseError) {
|
|
67
93
|
return {
|
|
68
94
|
conformant: false,
|
|
69
|
-
problems: [
|
|
70
|
-
`The body could not be parsed into the canonical schema: ${err.message}`,
|
|
71
|
-
],
|
|
95
|
+
problems: [parseFailureProblem(err)],
|
|
72
96
|
warnings: [],
|
|
73
97
|
parseFailed: true,
|
|
98
|
+
parseError: err.message,
|
|
74
99
|
};
|
|
75
100
|
}
|
|
76
101
|
throw err;
|
|
@@ -103,10 +128,13 @@ export function evaluateIssueBody(body) {
|
|
|
103
128
|
problems,
|
|
104
129
|
warnings: result.warnings,
|
|
105
130
|
parseFailed: false,
|
|
131
|
+
parseError: null,
|
|
106
132
|
};
|
|
107
133
|
}
|
|
108
134
|
|
|
109
135
|
/**
|
|
136
|
+
* Built only from fixed strings and the fixed-vocabulary `problems`; warning
|
|
137
|
+
* text echoes issue content, so only the count is shown.
|
|
110
138
|
* @param {ConformanceVerdict} verdict
|
|
111
139
|
* @returns {string}
|
|
112
140
|
*/
|
|
@@ -127,11 +155,8 @@ export function renderConformanceComment(verdict) {
|
|
|
127
155
|
if (verdict.warnings.length > 0) {
|
|
128
156
|
lines.push(
|
|
129
157
|
'',
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
...verdict.warnings.map((w) => `- ${w}`),
|
|
133
|
-
'',
|
|
134
|
-
'</details>',
|
|
158
|
+
`The parser also raised ${verdict.warnings.length} non-blocking ` +
|
|
159
|
+
'warning(s); see the workflow run log for the details.',
|
|
135
160
|
);
|
|
136
161
|
}
|
|
137
162
|
return lines.join('\n');
|
|
@@ -159,6 +184,34 @@ export function isStoryTicket(labelNames) {
|
|
|
159
184
|
return Array.isArray(labelNames) && labelNames.includes('type::story');
|
|
160
185
|
}
|
|
161
186
|
|
|
187
|
+
/**
|
|
188
|
+
* The bot-authored marker comment to update, or `null`. A human-authored
|
|
189
|
+
* marker is ignored so an issue author cannot hijack or suppress the lint.
|
|
190
|
+
*/
|
|
191
|
+
function findMarkerCommentId(ghFn, repoPath, issue) {
|
|
192
|
+
const out = ghFn([
|
|
193
|
+
'api',
|
|
194
|
+
`repos/${repoPath}/issues/${issue}/comments`,
|
|
195
|
+
'--paginate',
|
|
196
|
+
'--jq',
|
|
197
|
+
'.[] | {id, login: .user.login, body}',
|
|
198
|
+
]);
|
|
199
|
+
const comments = out.split('\n').filter((line) => line.trim() !== '');
|
|
200
|
+
return comments.map((line) => JSON.parse(line)).find(isBotMarker)?.id ?? null;
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
const isBotMarker = (c) =>
|
|
204
|
+
c.body?.startsWith(LINT_COMMENT_MARKER) && c.login?.endsWith('[bot]');
|
|
205
|
+
|
|
206
|
+
function upsertArgs(id, issue, repo, comment) {
|
|
207
|
+
if (id === null) {
|
|
208
|
+
const repoArgs = repo ? ['--repo', repo] : [];
|
|
209
|
+
return ['issue', 'comment', String(issue), ...repoArgs, '--body', comment];
|
|
210
|
+
}
|
|
211
|
+
const path = `repos/${repo ?? '{owner}/{repo}'}/issues/comments/${id}`;
|
|
212
|
+
return ['api', '-X', 'PATCH', path, '-f', `body=${comment}`];
|
|
213
|
+
}
|
|
214
|
+
|
|
162
215
|
/**
|
|
163
216
|
* @param {{
|
|
164
217
|
* issue: string|number,
|
|
@@ -201,6 +254,8 @@ export function runLintIssueBody({
|
|
|
201
254
|
issue: Number(issue),
|
|
202
255
|
conformant: verdict.conformant,
|
|
203
256
|
problems: verdict.problems,
|
|
257
|
+
warnings: verdict.warnings,
|
|
258
|
+
parseError: verdict.parseError,
|
|
204
259
|
})}\n`,
|
|
205
260
|
);
|
|
206
261
|
|
|
@@ -211,8 +266,8 @@ export function runLintIssueBody({
|
|
|
211
266
|
};
|
|
212
267
|
}
|
|
213
268
|
|
|
214
|
-
const
|
|
215
|
-
ghFn(
|
|
269
|
+
const id = findMarkerCommentId(ghFn, repo ?? '{owner}/{repo}', issue);
|
|
270
|
+
ghFn(upsertArgs(id, issue, repo, renderConformanceComment(verdict)));
|
|
216
271
|
return { conformant: false, problems: verdict.problems };
|
|
217
272
|
}
|
|
218
273
|
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: >-
|
|
3
|
+
Audit the project as a goal-directed adversary — attack paths that chain two
|
|
4
|
+
or more crossings, abuse of intended features, agent exposure to hostile
|
|
5
|
+
repository or inbound content, hostile operations and operator hazards —
|
|
6
|
+
graded under a reproduced-or-reasoned evidence bar. A deliberately-global
|
|
7
|
+
lens that runs on any project.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Red-Team Audit
|
|
11
|
+
|
|
12
|
+
You are a Red-Team Lead playing a **goal-directed adversary** against this
|
|
13
|
+
project. The per-dimension lenses each grade one crossing at a time; you ask
|
|
14
|
+
what an attacker _wants_, then chain the crossings that get them there. You
|
|
15
|
+
also own one surface no other lens audits: the paths by which hostile
|
|
16
|
+
repository-resident or inbound content can steer the **coding agents** that
|
|
17
|
+
operate on this repository.
|
|
18
|
+
|
|
19
|
+
The shared lens machinery lives in
|
|
20
|
+
[`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
|
|
21
|
+
`{{auditResultsDir}}/audit-red-team-results.md`. Dimension values:
|
|
22
|
+
`Attack Path | Abuse & Misuse | Agent Exposure | Hostile Operations |
|
|
23
|
+
Operator Hazard`. Extra finding fields: **Adversary:**, **Path:**,
|
|
24
|
+
**Evidence:** and **Reproduction:** (see Report additions). The report adds a
|
|
25
|
+
mandatory **Adversary Model** section.
|
|
26
|
+
|
|
27
|
+
## Whole-project scope (global lens)
|
|
28
|
+
|
|
29
|
+
An attack path spans files no change set names: the entry point an adversary
|
|
30
|
+
reaches is rarely the file whose weakness completes the chain. Narrowing to the
|
|
31
|
+
change set would blind this lens to its primary finding class, so it **always
|
|
32
|
+
evaluates the whole project**, and it applies to any project (it declares no
|
|
33
|
+
`target`).
|
|
34
|
+
|
|
35
|
+
Accordingly this lens declares `"scope": "global"` in
|
|
36
|
+
[`audit-rules.json`](../schemas/audit-rules.json) — the single source of truth
|
|
37
|
+
`resolveLensTier` in
|
|
38
|
+
[`lib/audit-suite/selector.js`](../scripts/lib/audit-suite/selector.js) reads —
|
|
39
|
+
and joins only the opt-in run-closeout roster (`gate3`); it never runs at Story
|
|
40
|
+
close or on a file pattern.
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
{{changedFiles}}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
- For this lens, **ignore** the `{{changedFiles}}` block above as a filter even
|
|
47
|
+
when it is populated: the project is evaluated whole. The block is rendered
|
|
48
|
+
only for envelope-shape parity with the scoped lenses. Do use it, when
|
|
49
|
+
populated, as a **prioritization hint** — a chain that runs through a changed
|
|
50
|
+
file is the first one to walk — never as a limit on what is audited or
|
|
51
|
+
reported.
|
|
52
|
+
|
|
53
|
+
## Execution strategy
|
|
54
|
+
|
|
55
|
+
Run this lens as one `subagent_type: auditor` dispatch per the core's
|
|
56
|
+
Execution strategy. Fan out per dimension only when the operator's invocation
|
|
57
|
+
asks for it.
|
|
58
|
+
|
|
59
|
+
## Step 0: Adversary model
|
|
60
|
+
|
|
61
|
+
Before hunting, write down what you are attacking. Every finding is graded
|
|
62
|
+
against this model, and the report carries it as the `## Adversary Model`
|
|
63
|
+
section:
|
|
64
|
+
|
|
65
|
+
1. **Promises.** Quote the promises the project makes about itself — its
|
|
66
|
+
README, its docs, its security rules — each with the path it came from. An
|
|
67
|
+
abuse case is only a finding when it breaks one of these.
|
|
68
|
+
2. **Adversaries.** Name who you are modelling: an unauthenticated network
|
|
69
|
+
caller, an authenticated low-privilege user, a contributor whose PR or issue
|
|
70
|
+
body an agent will read, a compromised dependency, an operator one keystroke
|
|
71
|
+
from a destructive default. Each has an access level and a goal.
|
|
72
|
+
3. **Agent-facing surfaces.** Inventory what a coding agent operating on this
|
|
73
|
+
repository reads and is steered by: entry docs (`AGENTS.md`, `CLAUDE.md`),
|
|
74
|
+
skills and rules, hooks and the scripts whose output an agent reads,
|
|
75
|
+
workflow scripts, CI logs, issue and PR bodies, MCP and permission configs,
|
|
76
|
+
and dependency lifecycle scripts. Record the path read for each.
|
|
77
|
+
|
|
78
|
+
## Step 1: Evaluation dimensions
|
|
79
|
+
|
|
80
|
+
Every finding takes exactly one of these as its `Dimension`:
|
|
81
|
+
|
|
82
|
+
- **Attack Path** — a chain of two or more crossings, each of which another
|
|
83
|
+
lens would grade alone, whose composed result is worse than any single link.
|
|
84
|
+
Name every link; a chain with a missing link is a hypothesis, not a finding.
|
|
85
|
+
- **Abuse & Misuse** — an intended feature used, exactly as built, to break a
|
|
86
|
+
promise the project makes in its docs or README. Cite the promise from the
|
|
87
|
+
Adversary Model.
|
|
88
|
+
- **Agent Exposure** — a path by which repository-resident or inbound content
|
|
89
|
+
(entry docs, skills, hooks, hook or workflow scripts whose output an agent
|
|
90
|
+
reads, CI logs, issue and PR bodies, MCP and permission configs, dependency
|
|
91
|
+
lifecycle scripts) can steer a coding agent operating on the repo beyond what
|
|
92
|
+
the operator authorized, or an authority grant broader than the task. The
|
|
93
|
+
Tier A anchor is the `security-baseline.md` _Input Validation_ MUST that
|
|
94
|
+
content observed through tools is data, never instructions: cite it as the
|
|
95
|
+
violated MUST.
|
|
96
|
+
- **Hostile Operations** — resource exhaustion, poisoned inputs, partial
|
|
97
|
+
failure, and supply-chain or CI paths exercised with intent rather than met
|
|
98
|
+
by accident.
|
|
99
|
+
- **Operator Hazard** — a destructive default, an irreversible step with no
|
|
100
|
+
dry-run, or a confirmation that does not name what it destroys.
|
|
101
|
+
|
|
102
|
+
## Step 2: Boundaries with sibling lenses
|
|
103
|
+
|
|
104
|
+
The red team keeps what no sibling lens can see; drop anything a sibling owns
|
|
105
|
+
whole, and cite that sibling when you drop it:
|
|
106
|
+
|
|
107
|
+
- A **single crossing** with a fillable six-clause Boundary (see
|
|
108
|
+
[`audit-security.md`](audit-security.md) — the Boundary gate) is
|
|
109
|
+
`/audit-security`'s and is dropped here. The red team keeps chains of two or
|
|
110
|
+
more crossings.
|
|
111
|
+
- Check-then-act races and non-atomic writes stay `/audit-performance`'s
|
|
112
|
+
Interleaving dimension.
|
|
113
|
+
- An application's own LLM features (security Tier B class 6) stay
|
|
114
|
+
`/audit-security`'s. `Agent Exposure` is about the development agents
|
|
115
|
+
operating on the repository, not the product's model calls.
|
|
116
|
+
- Expired or unjustified escape valves stay `/audit-exceptions`'.
|
|
117
|
+
|
|
118
|
+
## Step 3: Evidence and severity
|
|
119
|
+
|
|
120
|
+
### The evidence cap
|
|
121
|
+
|
|
122
|
+
Every finding carries `Evidence: reproduced` or `Evidence: reasoned`. **A
|
|
123
|
+
reasoned finding grades no higher than Medium**, whatever its modelled result.
|
|
124
|
+
**High and Critical require Evidence: reproduced.** Critical additionally
|
|
125
|
+
requires the demonstrated result to be code execution, loss of a data store, a
|
|
126
|
+
leaked secret, or control of an account the adversary picks.
|
|
127
|
+
|
|
128
|
+
Otherwise grade on the shared scale with the anchors of `/audit-security`
|
|
129
|
+
Step 3: a crash is not code execution, and self-impact is not privilege gain.
|
|
130
|
+
When you cannot name the concrete damage, grade lower than instinct suggests.
|
|
131
|
+
|
|
132
|
+
### The reproduction carve-out
|
|
133
|
+
|
|
134
|
+
This refines the shared read-only constraint for this lens only. A
|
|
135
|
+
reproduction is a command run against the project's own CLIs, tests or scripts
|
|
136
|
+
with crafted input, **whose every write lands under
|
|
137
|
+
`{{auditOutputDir}}/red-team/`** (on a manual run,
|
|
138
|
+
`<project.paths.tempRoot>/audits/red-team/`). A reproduction:
|
|
139
|
+
|
|
140
|
+
- never installs anything;
|
|
141
|
+
- never mutates git state, labels or tracked files;
|
|
142
|
+
- never opens a network connection to a deployed environment;
|
|
143
|
+
- never runs a payload whose effect it cannot bound in advance.
|
|
144
|
+
|
|
145
|
+
There is no runtime pass against `qa.environments`. A path that can only be
|
|
146
|
+
demonstrated against a live target stays `reasoned`, and the evidence cap
|
|
147
|
+
grades it accordingly.
|
|
148
|
+
|
|
149
|
+
## Constraint (lens-specific carve-out)
|
|
150
|
+
|
|
151
|
+
Read-only over the repository, except the reproduction carve-out above and the
|
|
152
|
+
report artifact. Recording an attack path is the deliverable; closing it is a
|
|
153
|
+
separate pass.
|
|
154
|
+
|
|
155
|
+
## Report additions
|
|
156
|
+
|
|
157
|
+
Beyond the core's shared skeleton, this lens adds its title, the mandatory
|
|
158
|
+
Adversary Model section before the findings, an `Evidence split` line in the
|
|
159
|
+
Executive Summary, and four finding fields. Write `_No findings._` under a
|
|
160
|
+
section rather than omitting it:
|
|
161
|
+
|
|
162
|
+
```markdown
|
|
163
|
+
# Red-Team Audit Report
|
|
164
|
+
|
|
165
|
+
## Executive Summary
|
|
166
|
+
|
|
167
|
+
[Headline read.]
|
|
168
|
+
|
|
169
|
+
Self-cross-check: kept <k> / dropped <d>.
|
|
170
|
+
Severity tally: Critical <n> / High <n> / Medium <n> / Low <n>
|
|
171
|
+
Evidence split: reproduced <n> / reasoned <n>
|
|
172
|
+
|
|
173
|
+
## Adversary Model
|
|
174
|
+
|
|
175
|
+
- Promises: [quoted promise — `path`]
|
|
176
|
+
- Adversaries: [who, with what access, wanting what]
|
|
177
|
+
- Agent-facing surfaces: [surface — `path` read]
|
|
178
|
+
|
|
179
|
+
## Detailed Findings
|
|
180
|
+
|
|
181
|
+
### `path/to/primary-file.ext` — [Short title of the issue]
|
|
182
|
+
|
|
183
|
+
- **Dimension:** [Attack Path | Abuse & Misuse | Agent Exposure | Hostile Operations | Operator Hazard]
|
|
184
|
+
- **Severity:** [Critical | High | Medium | Low | Info — capped at Medium when reasoned]
|
|
185
|
+
- **Adversary:** [who, with what access, wanting what]
|
|
186
|
+
- **Path:** [preconditions → step (`path:line`) → … → result → blast radius, one line per step]
|
|
187
|
+
- **Evidence:** [reproduced | reasoned]
|
|
188
|
+
- **Reproduction:** [reproduced: the exact command run and the output line that shows the result | reasoned: none]
|
|
189
|
+
- [Location, Current State, Recommendation & Rationale, Acceptance signal —
|
|
190
|
+
per the core skeleton]
|
|
191
|
+
```
|
|
@@ -119,7 +119,10 @@ for an undetected ecosystem is inapplicable and never a finding.
|
|
|
119
119
|
### Tier B — trust-boundary classes (cite a CWE)
|
|
120
120
|
|
|
121
121
|
Each class names the sibling lens owning adjacent territory; when the only
|
|
122
|
-
defect is the sibling's, cite that lens and drop the finding here.
|
|
122
|
+
defect is the sibling's, cite that lens and drop the finding here. Chains of two
|
|
123
|
+
or more crossings, and agent exposure (hostile repository or inbound content
|
|
124
|
+
steering the development agents that operate on the repo), are
|
|
125
|
+
`/audit-red-team`'s.
|
|
123
126
|
|
|
124
127
|
1. **Business logic & state machines:** steps skipped, reordered or replayed;
|
|
125
128
|
partial failure leaving step 1 applied; numeric coercion (negative, zero,
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Evidence-cited leverage review — draft five to twelve bets on how the project could be ~10x more useful, reliable or valuable, refute most of them with two maker-blind skeptics each, write the survivors, downgrades and refutations to temp/leverage/<run-id>/bets.md, and hand each survivor to /mandrel-plan behind a HITL gate.
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# /mandrel-leverage
|
|
6
|
+
|
|
7
|
+
Ask "how could this be 10x more useful, reliable or valuable" and make the
|
|
8
|
+
answer **survive its own refutation** before any of it becomes a Story. The
|
|
9
|
+
run gathers evidence (Phase 0), drafts bets that cite it (Phase 1), puts every
|
|
10
|
+
bet in front of two independent skeptics (Phase 2), writes one bets document
|
|
11
|
+
(Phase 3), and offers each survivor to the operator as a plan seed (Phase 4).
|
|
12
|
+
|
|
13
|
+
It is a front-end to [`/mandrel-plan`](mandrel-plan.md) in the same sense
|
|
14
|
+
[`/qa-assist`](qa-assist.md) and [`/audit-to-stories`](audit-to-stories.md)
|
|
15
|
+
are: it produces a seed and chains into plan. It **never persists an issue,
|
|
16
|
+
never mutates a label, and never starts delivery** — filing is
|
|
17
|
+
`/mandrel-plan`'s, behind the hand-off gate. Audits find defects against a
|
|
18
|
+
standard; this workflow prices upside, so a bet that does not clear the bar is
|
|
19
|
+
recorded as refuted, not filed as a finding.
|
|
20
|
+
|
|
21
|
+
## Slash Command
|
|
22
|
+
|
|
23
|
+
```text
|
|
24
|
+
/mandrel-leverage [<focus>] [--bar <multiplier>] [--evidence <path> ...]
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### Arguments
|
|
28
|
+
|
|
29
|
+
| Name | Required | Shape / Example | Notes |
|
|
30
|
+
| ------------ | -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
31
|
+
| `<focus>` | no | `"per-Story token cost"` | Narrows the question to one axis or subsystem. Omitted, the run is `general`. |
|
|
32
|
+
| `--bar` | no | `--bar 5` | The multiplier a bet must clear to survive. Default `10` — the name's promise. |
|
|
33
|
+
| `--evidence` | no | `--evidence temp/cost.md` | Repeatable. Operator-supplied files (a cost report, a usage export, user feedback) added to the evidence set. |
|
|
34
|
+
|
|
35
|
+
`<run-id>` is `<YYYYMMDD>-<focus-slug>`, or `<YYYYMMDD>-general` with no focus.
|
|
36
|
+
Every artifact the run writes lives under `temp/leverage/<run-id>/`.
|
|
37
|
+
|
|
38
|
+
## Phase gates (HITL)
|
|
39
|
+
|
|
40
|
+
Gating is **light within a phase and firm at the boundary**, mirroring
|
|
41
|
+
[`/qa-assist`](qa-assist.md) § Phase gates. Phases 0–3 read, draft, dispatch
|
|
42
|
+
and write the local bets document without ceremony. **Every write that leaves
|
|
43
|
+
the local bets document is operator-confirmed individually**: each seed write
|
|
44
|
+
and each `/mandrel-plan` invocation is asked about and waited on, one at a
|
|
45
|
+
time. The plan → deliver hard stop is preserved.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Phase 0 — Evidence intake (read-only)
|
|
50
|
+
|
|
51
|
+
Goal: fix the evidence set before any bet is drafted. Read, and list in the
|
|
52
|
+
bets document's `## Evidence set` with paths:
|
|
53
|
+
|
|
54
|
+
1. **The docs digest set** (`project.docsContextFiles`): the roadmap's
|
|
55
|
+
Someday items, the decisions log's Accepted and Rejected entries, and the
|
|
56
|
+
architecture overview. Read digest-first and pull sections on demand.
|
|
57
|
+
2. **The committed quality baselines** (the `baselines/` tree, when present)
|
|
58
|
+
as hotspot evidence — where complexity, churn and coverage debt sit.
|
|
59
|
+
3. **Friction signals.** Every `signals.ndjson` stream under the temp root —
|
|
60
|
+
per-run `temp/run-<id>/signals.ndjson` and standalone
|
|
61
|
+
`temp/standalone/stories/story-<sid>/signals.ndjson` — rolled up by `kind`
|
|
62
|
+
and `category` (record shape:
|
|
63
|
+
[`signal-event.schema.json`](../schemas/signal-event.schema.json); where
|
|
64
|
+
the records come from:
|
|
65
|
+
[`execution-reference.md` § Friction telemetry](../docs/execution-reference.md#friction-telemetry)).
|
|
66
|
+
4. **Every `--evidence` file** the operator passed.
|
|
67
|
+
5. **Prior runs.** The `## Refuted` and `## Downgraded` sections of every
|
|
68
|
+
prior `temp/leverage/*/bets.md`. A prior refuted bet is **carried forward
|
|
69
|
+
as refuted unless new evidence names what changed**; never re-litigate a
|
|
70
|
+
refutation silently. A re-proposed bet cites the prior run and the new
|
|
71
|
+
evidence that reopens it.
|
|
72
|
+
|
|
73
|
+
Phase 0 writes nothing but the run directory.
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Phase 1 — Diverge
|
|
78
|
+
|
|
79
|
+
Goal: draft **between five and twelve bets**, each one block:
|
|
80
|
+
|
|
81
|
+
- **slug** — kebab-case, unique within the run.
|
|
82
|
+
- **axis** — `useful` (to users), `reliable`, or `valuable`.
|
|
83
|
+
- **claim** — a multiplier on a named, measurable quantity
|
|
84
|
+
(e.g. "10x fewer operator interventions per delivered Story").
|
|
85
|
+
- **mechanism** — one paragraph: why the change moves that quantity.
|
|
86
|
+
- **evidence** — citations as `path:line` or a signal roll-up figure;
|
|
87
|
+
**every bet carries at least one `path:line` or signal citation**. A bet
|
|
88
|
+
with no citation is not drafted.
|
|
89
|
+
- **must be true** — what would have to hold for the multiplier to
|
|
90
|
+
materialize.
|
|
91
|
+
- **cost** — a rough size in Stories.
|
|
92
|
+
|
|
93
|
+
A `<focus>` narrows the drafting; it does not lower the citation bar.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Phase 2 — Skeptics (maker-blind)
|
|
98
|
+
|
|
99
|
+
Goal: refute what does not hold. This is the load-bearing invariant.
|
|
100
|
+
|
|
101
|
+
**Dispatch.** For every bet, dispatch **two independent
|
|
102
|
+
`subagent_type: general-purpose` skeptics in one turn**, all bets' skeptics
|
|
103
|
+
together. Each skeptic is handed **only the bet block and the evidence
|
|
104
|
+
paths** — never the drafting reasoning, never the other skeptic's verdict,
|
|
105
|
+
never a prior verdict. A skeptic that reads the maker's case grades the case,
|
|
106
|
+
not the bet; the same reasoning as
|
|
107
|
+
[`plan-critic.md` § Maker-blind](../agents/plan-critic.md). The `plan-critic`
|
|
108
|
+
role is a pre-mortem over an authored plan draft, a different charter — do not
|
|
109
|
+
dispatch it here.
|
|
110
|
+
|
|
111
|
+
**Skeptic charter** (paste it into each dispatch):
|
|
112
|
+
|
|
113
|
+
> Assume this bet shipped and the multiplier did not materialize. Name the
|
|
114
|
+
> most likely reason, with the evidence that supports it — read the cited
|
|
115
|
+
> paths yourself. Then credit the multiplier the evidence actually supports.
|
|
116
|
+
> Return one verdict block:
|
|
117
|
+
>
|
|
118
|
+
> - `verdict` — `holds` | `downgraded` | `refuted`
|
|
119
|
+
> - `credited` — a number (the multiplier you credit)
|
|
120
|
+
> - `reason` — one paragraph with `path:line` citations
|
|
121
|
+
> - `missing-evidence` — what evidence would change your verdict
|
|
122
|
+
|
|
123
|
+
**Scoring.** With `bar` the `--bar` value (default `10`):
|
|
124
|
+
|
|
125
|
+
- **survivor** — both skeptics credit at least the bar.
|
|
126
|
+
- **downgraded** — both credit at least 3, but one is below the bar.
|
|
127
|
+
- **refuted** — anything else.
|
|
128
|
+
|
|
129
|
+
**The caller never overrides a verdict.** It may re-draft a bet once with new
|
|
130
|
+
evidence and re-dispatch two fresh skeptics; the second pair's verdicts are
|
|
131
|
+
final.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Phase 3 — Converge
|
|
136
|
+
|
|
137
|
+
Goal: write the one artifact, `temp/leverage/<run-id>/bets.md`, with these
|
|
138
|
+
sections in order:
|
|
139
|
+
|
|
140
|
+
- `## Evidence set` — every path read in Phase 0, plus the signal roll-up.
|
|
141
|
+
- `## Survivors` — ranked by the **lower** credited multiplier; each bet
|
|
142
|
+
block with both verdicts.
|
|
143
|
+
- `## Downgraded` — each bet block with both verdicts.
|
|
144
|
+
- `## Refuted` — every refuted bet with its refuting reason, kept so the next
|
|
145
|
+
run inherits it.
|
|
146
|
+
- `## Missing evidence` — the union of what the skeptics asked for: the
|
|
147
|
+
run's instrumentation backlog.
|
|
148
|
+
|
|
149
|
+
`bets.md` and the per-survivor seeds are the only files a run writes; nothing
|
|
150
|
+
lands under `docs/`.
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## Phase 4 — Hand-off (HITL-gated)
|
|
155
|
+
|
|
156
|
+
Goal: turn survivors into plan seeds only where the operator says so.
|
|
157
|
+
|
|
158
|
+
1. **Offer each survivor, one at a time**, with the host's question idiom:
|
|
159
|
+
**file as a plan seed**, **defer**, or **drop**. Show the bet block and both
|
|
160
|
+
verdicts.
|
|
161
|
+
2. **On file**, confirm the seed write, then write
|
|
162
|
+
`temp/leverage/<run-id>/seed-<slug>.md` carrying the bet, both verdicts and
|
|
163
|
+
the evidence paths.
|
|
164
|
+
3. **Confirm the plan invocation**, then chain into the planning entrypoint:
|
|
165
|
+
|
|
166
|
+
```text
|
|
167
|
+
/mandrel-plan --seed-file temp/leverage/<run-id>/seed-<slug>.md
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
`/mandrel-plan` owns interrogation, authoring and persistence from there.
|
|
171
|
+
4. **No survivor** → the run ends at the bets document, and its
|
|
172
|
+
`## Missing evidence` section is the recommendation.
|
|
173
|
+
|
|
174
|
+
Every seed write and every `/mandrel-plan` invocation is confirmed
|
|
175
|
+
individually; one approval never covers the next survivor.
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Constraints
|
|
180
|
+
|
|
181
|
+
- **Read-only outside `temp/leverage/`.** The workflow never persists an
|
|
182
|
+
issue, never mutates a label, and never starts delivery.
|
|
183
|
+
- **Citations or nothing.** No bet is drafted, and no skeptic verdict is
|
|
184
|
+
scored, without a `path:line` or signal citation.
|
|
185
|
+
- **Maker-blind skeptics.** Bet block and evidence paths only; the caller
|
|
186
|
+
never overrides a verdict.
|
|
187
|
+
- **Refutations persist.** A prior refuted bet stays refuted unless new
|
|
188
|
+
evidence names what changed.
|
|
189
|
+
- **No project-specific refutations ship.** An operator may seed a first
|
|
190
|
+
run's `## Refuted` by hand from an earlier review.
|
|
191
|
+
|
|
192
|
+
## See also
|
|
193
|
+
|
|
194
|
+
- [`/mandrel-plan`](mandrel-plan.md) — the planning pipeline Phase 4 chains
|
|
195
|
+
into; the plan → deliver hard stop is preserved across the handoff.
|
|
196
|
+
- [`/qa-assist`](qa-assist.md) — the precedent for light-within, firm-at-boundary
|
|
197
|
+
gating and the confirmed `/mandrel-plan` handoff.
|
|
198
|
+
- [`/audit-to-stories`](audit-to-stories.md) — the precedent for chaining
|
|
199
|
+
`/mandrel-plan --seed-file`.
|
|
@@ -172,4 +172,6 @@ source id ([ref](helpers/plan-reference.md)).
|
|
|
172
172
|
## See also
|
|
173
173
|
|
|
174
174
|
[`/mandrel-deliver`](mandrel-deliver.md), [`/audit-to-stories`](audit-to-stories.md),
|
|
175
|
-
[
|
|
175
|
+
[`/mandrel-leverage`](mandrel-leverage.md) (evidence-cited bets that chain in
|
|
176
|
+
as seeds), [`helpers/plan-reference.md`](helpers/plan-reference.md) (on-demand
|
|
177
|
+
detail).
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,20 @@ All notable changes to this project will be documented in this file.
|
|
|
15
15
|
-->
|
|
16
16
|
<!-- markdownlint-disable-file MD004 MD012 MD037 -->
|
|
17
17
|
|
|
18
|
+
## [2.96.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.95.0...mandrel-v2.96.0) (2026-10-21)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* add /audit-red-team: a global adversarial lens that reports attack paths, abuse cases and agent exposure with a reproduced-or-reasoned evidence bar ([#5838](https://github.com/dsj1984/mandrel/issues/5838)) ([#5841](https://github.com/dsj1984/mandrel/issues/5841)) ([36bc0fb](https://github.com/dsj1984/mandrel/commit/36bc0fb34dea12c389f892c42f170026f5dfcd88))
|
|
24
|
+
* add /mandrel-leverage, a leverage review with maker-blind skeptics (refs [#5839](https://github.com/dsj1984/mandrel/issues/5839)) ([#5840](https://github.com/dsj1984/mandrel/issues/5840)) ([146310f](https://github.com/dsj1984/mandrel/commit/146310f9477d4753ca441f19bdde0c708263a1eb))
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
### Fixed
|
|
28
|
+
|
|
29
|
+
* harden this repo's Claude Code settings and record why Bash and Write stay broad (refs [#5844](https://github.com/dsj1984/mandrel/issues/5844)) ([#5846](https://github.com/dsj1984/mandrel/issues/5846)) ([f56c028](https://github.com/dsj1984/mandrel/commit/f56c02861e91370c7cee89ab745c99e3706bcc6f))
|
|
30
|
+
* stop the issue-body conformance comment from echoing issue text as the Actions bot, and update one marker comment instead of posting a new one per edit ([#5843](https://github.com/dsj1984/mandrel/issues/5843)) ([#5845](https://github.com/dsj1984/mandrel/issues/5845)) ([bd6cbe7](https://github.com/dsj1984/mandrel/commit/bd6cbe70651408b5311be0629dc641db8953b80e))
|
|
31
|
+
|
|
18
32
|
## [2.95.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.94.0...mandrel-v2.95.0) (2026-10-21)
|
|
19
33
|
|
|
20
34
|
|
package/package.json
CHANGED