mandrel 2.80.0 → 2.81.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 (36) hide show
  1. package/.agents/audit-checklists/security.md +15 -1
  2. package/.agents/docs/agentrc-reference.json +1 -0
  3. package/.agents/docs/configuration.md +3 -2
  4. package/.agents/docs/execution-reference.md +25 -5
  5. package/.agents/docs/workflows.md +1 -1
  6. package/.agents/schemas/agentrc.schema.json +12 -2
  7. package/.agents/schemas/audit-rules.json +10 -1
  8. package/.agents/scripts/deliver-run.js +43 -8
  9. package/.agents/scripts/lib/baselines/duplication-scanner.js +7 -1
  10. package/.agents/scripts/lib/baselines/refresh-service.js +6 -0
  11. package/.agents/scripts/lib/cli-args.js +16 -2
  12. package/.agents/scripts/lib/config/gates/duplication.schema.js +10 -2
  13. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  14. package/.agents/scripts/lib/observability/close-telemetry.js +17 -2
  15. package/.agents/scripts/lib/orchestration/complexity-gate.js +58 -11
  16. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +51 -6
  17. package/.agents/scripts/lib/orchestration/plan-persist/source-rewrite.js +177 -0
  18. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +174 -43
  19. package/.agents/scripts/lib/orchestration/plan-persist/supersede-ops.js +57 -15
  20. package/.agents/scripts/lib/orchestration/resolve-stories.js +12 -3
  21. package/.agents/scripts/lib/orchestration/resume-effort.js +121 -0
  22. package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js +13 -2
  23. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +10 -2
  24. package/.agents/scripts/lib/orchestration/ticketing/reads.js +3 -0
  25. package/.agents/scripts/plan-persist.js +20 -6
  26. package/.agents/scripts/providers/github/tickets.js +2 -1
  27. package/.agents/scripts/resolve-stories.js +8 -2
  28. package/.agents/scripts/single-story-close.js +11 -3
  29. package/.agents/workflows/audit-security.md +136 -49
  30. package/.agents/workflows/helpers/deliver-reference.md +7 -2
  31. package/.agents/workflows/helpers/deliver-story.md +5 -3
  32. package/.agents/workflows/helpers/plan-reference.md +42 -2
  33. package/.agents/workflows/mandrel-deliver.md +9 -4
  34. package/.agents/workflows/mandrel-plan.md +7 -1
  35. package/docs/CHANGELOG.md +16 -0
  36. package/package.json +2 -1
@@ -56,6 +56,8 @@ const CLI_OPTIONS = {
56
56
  'source-tickets': { type: 'string' },
57
57
  'close-superseded': { type: 'boolean', default: true },
58
58
  'no-close-superseded': { type: 'boolean', default: false },
59
+ 'rewrite-source': { type: 'boolean', default: true },
60
+ 'no-rewrite-source': { type: 'boolean', default: false },
59
61
  'dry-run': { type: 'boolean', default: false },
60
62
  'force-review': { type: 'boolean', default: false },
61
63
  'epic-title': { type: 'string' },
@@ -66,7 +68,7 @@ const CLI_OPTIONS = {
66
68
  const USAGE =
67
69
  'Usage: plan-persist.js --stories <file> ' +
68
70
  '[--tech-spec <file>] [--plan-dir <dir>] [--plan-context <file>] ' +
69
- '[--source-tickets <ids>] [--no-close-superseded] ' +
71
+ '[--source-tickets <ids>] [--no-close-superseded] [--no-rewrite-source] ' +
70
72
  '[--dry-run] [--force-review] ' +
71
73
  '[--epic-title <text> --epic-goal <text> | --epic <id>]';
72
74
 
@@ -182,6 +184,17 @@ export function resolveEpicAdoptionId(values) {
182
184
  return id;
183
185
  }
184
186
 
187
+ /**
188
+ * A `--x` / `--no-x` pair: the negation always wins.
189
+ *
190
+ * @param {object} values
191
+ * @param {string} name
192
+ * @returns {boolean}
193
+ */
194
+ function negatableFlag(values, name) {
195
+ return values[`no-${name}`] !== true && values[name] !== false;
196
+ }
197
+
185
198
  /**
186
199
  * Where envelope-derived source ids meet the engine; a break here silently
187
200
  * un-wires `--tickets` superseding.
@@ -206,11 +219,8 @@ export function buildPersistOptions(values, paths, planContextEnvelope) {
206
219
  sourceTicketOrigin: source.origin,
207
220
  epic: resolveEpicRequest(values),
208
221
  adoptEpicId: resolveEpicAdoptionId(values),
209
- // `--no-close-superseded` always wins.
210
- closeSuperseded:
211
- values['no-close-superseded'] === true
212
- ? false
213
- : values['close-superseded'] !== false,
222
+ closeSuperseded: negatableFlag(values, 'close-superseded'),
223
+ rewriteSource: negatableFlag(values, 'rewrite-source'),
214
224
  };
215
225
  }
216
226
 
@@ -429,6 +439,10 @@ runAsCli(import.meta.url, main, {
429
439
  ['--source-tickets <ids>', 'Ticket ids this plan supersedes.'],
430
440
  ['--dry-run', 'Validate and report; create nothing.'],
431
441
  ['--no-close-superseded', 'Leave superseded source tickets open.'],
442
+ [
443
+ '--no-rewrite-source',
444
+ 'File a new Story for a one-for-one plan instead of rewriting its source ticket in place.',
445
+ ],
432
446
  [
433
447
  '--force-review',
434
448
  'Require the review gate even when it would be skipped.',
@@ -361,12 +361,13 @@ export class TicketGateway {
361
361
  *
362
362
  * @field-manifest POST /repos/{owner}/{repo}/issues/{n}/assignees: assignees
363
363
  * @field-manifest PATCH /repos/{owner}/{repo}/issues/{n}:
364
- * body, assignees, state, state_reason, labels
364
+ * title, body, assignees, state, state_reason, labels
365
365
  */
366
366
  /* node:coverage ignore next */
367
367
  async updateTicket(ticketId, mutations) {
368
368
  await this._addAssignees(ticketId, mutations.addAssignees);
369
369
  const patch = {};
370
+ if (mutations.title !== undefined) patch.title = mutations.title;
370
371
  if (mutations.body !== undefined) patch.body = mutations.body;
371
372
  if (mutations.assignees) patch.assignees = mutations.assignees;
372
373
  if (mutations.state !== undefined) patch.state = mutations.state;
@@ -32,6 +32,7 @@ import {
32
32
  readNativeBlockedBy,
33
33
  toStoryRecord,
34
34
  } from './lib/orchestration/resolve-stories.js';
35
+ import { resolveRunDispatchInputs } from './lib/orchestration/resume-effort.js';
35
36
  import { createProvider } from './lib/provider-factory.js';
36
37
  import { concurrentMap } from './lib/util/concurrent-map.js';
37
38
  import { paginateRest } from './providers/github/request-helpers.js';
@@ -189,12 +190,13 @@ export async function resolveForeignDone({ provider, dag, inSetIds }) {
189
190
  /**
190
191
  * @param {{ ids: string, native?: boolean, pretty?: boolean,
191
192
  * allowUnlabelled?: boolean }} args
192
- * @param {{ provider: object, config: object, stdout?: { write(s: string): void } }} deps
193
+ * @param {{ provider: object, config: object, stdout?: { write(s: string): void },
194
+ * countPriorBlocksFn?: Function }} deps
193
195
  * @returns {Promise<number>}
194
196
  */
195
197
  export async function runResolveStories(
196
198
  { ids: rawIds, native = true, pretty = false, allowUnlabelled = false },
197
- { provider, config, stdout = process.stdout },
199
+ { provider, config, stdout = process.stdout, countPriorBlocksFn },
198
200
  ) {
199
201
  const ids = parseIds(rawIds);
200
202
  const owner = config.github?.owner;
@@ -221,6 +223,10 @@ export async function runResolveStories(
221
223
  nativeEdges,
222
224
  foreignDone,
223
225
  warn: () => {},
226
+ ...(await resolveRunDispatchInputs(stories, {
227
+ config,
228
+ countFn: countPriorBlocksFn,
229
+ })),
224
230
  });
225
231
 
226
232
  stdout.write(
@@ -18,13 +18,17 @@
18
18
  * [--override-review-block <reason>]
19
19
  * [--worker-tokens <n>]
20
20
  * [--worker-model <model>]
21
+ * [--worker-effort <level>]
21
22
  *
22
23
  * `--worker-tokens <n>` is the story-worker's host-reported token total,
23
24
  * recorded best-effort in the close result's `telemetry` (absent or invalid →
24
25
  * `null` plus a warning; never a change of status or exit code).
25
26
  * `--worker-model <model>` is the dispatched story-worker's resolved model,
26
- * which deliver-run renders on a multi-Story close (`telemetry.workerModel`;
27
- * an inline close omits it and records `null`).
27
+ * which deliver-run renders on every worker-dispatched close
28
+ * (`telemetry.workerModel`; an inline close omits it and records `null`).
29
+ * `--worker-effort <level>` is the per-call effort a resumed story-worker ran
30
+ * at (`telemetry.workerEffort`), rendered beside it when the Story resumed
31
+ * after a prior block.
28
32
  * `--override-review-block <reason>` is the audited escape past a code-review
29
33
  * CRITICAL blocker (instead of a hand-merge with no record).
30
34
  * `--merge-watch-mode async` is passed per close by the orchestrator, the only
@@ -144,7 +148,11 @@ runAsCli(import.meta.url, main, {
144
148
  ],
145
149
  [
146
150
  '--worker-model <model>',
147
- 'The dispatched story-worker’s resolved model, recorded in the close result’s `telemetry.workerModel` beside `workerTokens`. deliver-run renders it on every close of a multi-Story run; an inline close omits it and records null. Best-effort: an invalid value records null with a warning and never changes the status or exit code.',
151
+ 'The dispatched story-worker’s resolved model, recorded in the close result’s `telemetry.workerModel` beside `workerTokens`. deliver-run renders it on every worker-dispatched close (a multi-Story run, or a one-Story resume); an inline close omits it and records null. Best-effort: an invalid value records null with a warning and never changes the status or exit code.',
152
+ ],
153
+ [
154
+ '--worker-effort <level>',
155
+ 'The per-call effort (low|medium|high|xhigh|max) the dispatched story-worker ran at, recorded in the close result’s `telemetry.workerEffort` beside `workerModel`. deliver-run renders it when the Story resumed after a prior block; absent, it records null. Best-effort: an invalid value records null with a warning and never changes the status or exit code.',
148
156
  ],
149
157
  ],
150
158
  notes: [
@@ -1,17 +1,22 @@
1
1
  ---
2
- description: Audit dependency CVEs, input-validation gaps, secrets handling, and auth boundaries; emit a structured High/Medium/Low findings report.
2
+ description: 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.
3
3
  ---
4
4
 
5
5
  # Security & Vulnerability Audit
6
6
 
7
- You are a Cybersecurity Architect & Penetration Tester conducting a
8
- comprehensive security review (OWASP Top 10, insecure configs, attack vectors).
9
- The shared lens machinery lives in
7
+ You are a Cybersecurity Architect conducting a comprehensive security review
8
+ (OWASP Top 10, insecure configs, attack vectors). The shared lens machinery
9
+ lives in
10
10
  [`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
11
11
  `{{auditOutputDir}}/audit-security-results.md`. Extra finding fields: **CWE
12
- ID:** and **Baseline MUST:** (the violated `security-baseline.md` MUST). The
13
- report adds a **Defensive Recommendations** section (3–5 headers/configs/
14
- libraries to harden the app).
12
+ ID:**, **Baseline MUST:** (the violated MUST, or `none — trust-boundary
13
+ class`) and **Boundary:** (Step 2's six-clause gate). The report adds a
14
+ **Defensive Recommendations** section (3–5 hardening headers/configs/
15
+ libraries, plus every hardening note Step 2 demotes).
16
+
17
+ Tier B, the Boundary gate and the anchors are adapted, in Mandrel's words,
18
+ from Cloudflare's MIT-licensed `security-audit` skill — prose rubric only;
19
+ this lens stays one read-only auditor and never runs target code.
15
20
 
16
21
  ## Scope
17
22
 
@@ -30,23 +35,21 @@ Execution strategy.
30
35
 
31
36
  This lens does **not** grade against recalled OWASP lore. The authoritative
32
37
  rubric is [`../rules/security-baseline.md`](../rules/security-baseline.md) — the
33
- project's inviolable security MUSTs (Input Validation, Authentication,
34
- Authorization, Output & Rendering, Data Leakage & Logging, Transport & Headers,
35
- Secrets Management, Dependency Hygiene). Read it first. **Every finding MUST
36
- name the specific `security-baseline.md` MUST it violates** (e.g. "violates
37
- _Secrets Management_: 'Fallback or placeholder secrets MUST NOT be committed'").
38
- A finding that cannot be tied to a baseline MUST — or to a CWE where the
39
- baseline is silent — is out of scope for this lens.
38
+ project's inviolable security MUSTs. Read it first. **Every Tier A finding
39
+ MUST name the specific MUST it violates** (e.g. "violates _Secrets
40
+ Management_: 'Fallback or placeholder secrets MUST NOT be committed'"). **A
41
+ Tier B finding cites a CWE in `CWE ID` and writes `none — trust-boundary
42
+ class` in `Baseline MUST`** — the one sanctioned use of the CWE escape hatch.
43
+ A finding that fits neither tier is out of scope for this lens.
40
44
 
41
45
  ## Step 1: Detection Battery (Tool-First, Read-Only)
42
46
 
43
- Ground every finding in tool output, not vibes. Run the ladder below; each rung
44
- is **presence-gated** and **ecosystem-gated** per the core's
45
- [Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection): when a
46
- scanner for a detected ecosystem is absent, fall through to the next rung and
47
- note the missing tool as a `Security Misconfiguration` finding (recommend
48
- adopting it); a scanner for an undetected ecosystem is inapplicable and never a
49
- finding.
47
+ Ground every finding in tool output, not vibes. Each rung is **presence-** and
48
+ **ecosystem-gated** per the core's
49
+ [Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection): a
50
+ scanner absent for a detected ecosystem falls through to the next rung and is
51
+ noted as a `Security Misconfiguration` finding (recommend adopting it); one
52
+ for an undetected ecosystem is inapplicable and never a finding.
50
53
 
51
54
  1. **Dependency CVEs, per detected ecosystem.** Never recall CVEs from memory:
52
55
 
@@ -57,17 +60,16 @@ finding.
57
60
  cargo audit --json # Rust
58
61
  ```
59
62
 
60
- Each advisory reachable in production (`--omit=dev`; for Python, the
61
- runtime requirements, not dev extras) at `high` or `critical` is a
62
- _Vulnerable Components_ finding citing the advisory id and the violated
63
- _Dependency Hygiene_ MUST.
63
+ Each advisory reachable in production (`--omit=dev`; for Python, runtime
64
+ requirements only) at `high` or `critical` is a _Vulnerable Components_
65
+ finding citing the advisory id and the _Dependency Hygiene_ MUST.
64
66
 
65
67
  **Python static analysis.** On a detected Python ecosystem also run
66
- `bandit -r <srcDir> -f json` for injection / `eval` / `subprocess(shell=True)`
67
- / weak-crypto sinks — the Python counterpart of the grep battery below.
68
+ `bandit -r <srcDir> -f json` for injection / `eval` / `shell=True` /
69
+ weak-crypto sinks — the Python counterpart of the grep battery below.
68
70
 
69
- 2. **Secret scanning (`gitleaks` / `trufflehog`), with a grep fallback.** When
70
- `gitleaks` is installed, prefer it:
71
+ 2. **Secret scanning (`gitleaks` / `trufflehog`), with a grep fallback.**
72
+ Prefer `gitleaks` when installed:
71
73
 
72
74
  ```bash
73
75
  command -v gitleaks >/dev/null 2>&1 && gitleaks detect --no-banner --redact -v || \
@@ -76,7 +78,7 @@ finding.
76
78
  ```
77
79
 
78
80
  3. **Grep battery (deterministic fallback / augmentation).** Run these
79
- regardless — they are cheap and catch what a scanner's ruleset may miss:
81
+ regardless — cheap, and they catch what a scanner's ruleset misses:
80
82
 
81
83
  ```bash
82
84
  # Hardcoded key material (violates Secrets Management)
@@ -92,41 +94,126 @@ finding.
92
94
  ```
93
95
 
94
96
  4. **Manual surface review.** Then read the surfaces the battery flags plus:
95
- input-validation edges (API endpoints, form handlers — is input validated at
96
- the boundary with a strict schema?), auth/session handling (token storage,
97
- missing ownership checks on sensitive routes), and injection sinks
98
- (`dangerouslySetInnerHTML`, raw SQL, command execution). On Python, read
99
- the route decorators (Django views / DRF `permission_classes`, Flask /
100
- FastAPI routes and `Depends` guards) for missing ownership checks.
97
+ input-validation edges (is input schema-validated at the boundary?),
98
+ auth/session handling (token storage, missing ownership checks on
99
+ sensitive routes), and injection sinks (`dangerouslySetInnerHTML`, raw
100
+ SQL, command execution). On Python, read the route decorators (Django /
101
+ DRF `permission_classes`, Flask / FastAPI `Depends` guards) for missing
102
+ ownership checks.
101
103
 
102
104
  ## Step 2: Evaluation Dimensions
103
105
 
104
- Grade each finding against the `security-baseline.md` MUST it breaks (and the
105
- CWE where one applies):
106
+ ### Tier A — baseline-anchored (cite the MUST)
106
107
 
107
108
  1. **Injection:** SQL, NoSQL, OS Command, and Cross-Site Scripting (XSS) —
108
109
  _Output & Rendering_.
109
110
  2. **Broken Access Control:** Can a user access data they don't own? —
110
111
  _Authorization_.
111
- 3. **Cryptographic Failures:** Is sensitive data (passwords, PII) hashed or
112
- encrypted using modern standards? — _Authentication_ / _Data Leakage &
113
- Logging_.
114
- 4. **Security Misconfiguration:** Are there default passwords, verbose error
115
- messages in production, or insecure headers? — _Transport & Headers_.
116
- 5. **Vulnerable Components:** Are outdated libraries introducing risks? —
112
+ 3. **Cryptographic Failures:** Is sensitive data hashed or encrypted to
113
+ modern standards? — _Authentication_ / _Data Leakage & Logging_.
114
+ 4. **Security Misconfiguration:** Default passwords, verbose production
115
+ errors, insecure headers? — _Transport & Headers_.
116
+ 5. **Vulnerable Components:** Outdated libraries introducing risk? —
117
117
  _Dependency Hygiene_.
118
118
 
119
+ ### Tier B — trust-boundary classes (cite a CWE)
120
+
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.
123
+
124
+ 1. **Business logic & state machines:** steps skipped, reordered or replayed;
125
+ partial failure leaving step 1 applied; numeric coercion (negative, zero,
126
+ overflow, string↔number); expiry and rate windows at exact instants; the
127
+ posture when config is missing, a flag is off or a migration is half
128
+ applied; stored data trusted because another path "validated it on the way
129
+ in". Check-then-act races and non-atomic writes are `/audit-performance`'s
130
+ Interleaving dimension, not this class.
131
+ 2. **Access-control depth:** whether the check that exists is the correct
132
+ one for this resource and this operation — a second path to the same
133
+ state change behind a weaker permission; a body field overriding what the permission model
134
+ restricts; authenticated-but-never-authorized endpoints; bulk, batch,
135
+ export and import paths skipping per-item checks. Shares the
136
+ _Authorization_ MUST with Tier A — merge rather than double-file.
137
+ 3. **Resource & file handling:** path traversal via symlinks, encoded
138
+ sequences or null bytes; SSRF via user-supplied fetch, webhook or callback
139
+ URLs and their redirects; unsafe deserialization; zip slip; temp files.
140
+ Install scripts and lockfile provenance are `/audit-dependencies`'s.
141
+ 4. **Cryptography & secrets misuse:** weak randomness for tokens or nonces;
142
+ timing-unsafe comparison; nonce/IV reuse; unauthenticated modes, missing
143
+ HMAC checks; error paths that fall back to no crypto. Hardcoded-secret
144
+ _presence_ is Step 1's rung and `/audit-privacy`'s — this is about _use_.
145
+ 5. **Feature abuse & data leakage:** export or backup including data above
146
+ the caller's level; import or restore bypassing validation or permissions;
147
+ search/filter/sort as an existence oracle; enumeration through differing
148
+ errors, timings or status codes; over-scoped preview tokens; cache
149
+ headers serving private content from a shared cache. PII-in-logs and
150
+ retention are `/audit-privacy`'s.
151
+ 6. **LLM & tool-binding boundaries** (ecosystem-gated: only when manifests
152
+ or imports show prompt assembly, a model API, tool/MCP definitions or
153
+ agent memory; otherwise omit silently): indirect prompt injection via
154
+ retrieved content; tool arguments reaching a downstream sink;
155
+ confused-deputy actions bound to the wrong principal; approval not bound
156
+ to the final action and resource; sub-agent or MCP trust inherited
157
+ unchecked; model output rendered or executed unsanitized.
158
+
159
+ ### The Boundary gate (every finding, both tiers)
160
+
161
+ Fill **Boundary:** as one line of six clauses: _lower-trust
162
+ principal → accepted input or action → intended control → crossed boundary →
163
+ affected principal or resource → observed or owner-observable result_. Three
164
+ rules follow:
165
+
166
+ - **An unfillable Boundary is not a finding.** A best practice that is merely
167
+ absent, with nobody and nothing concretely exposed, is a **hardening note**
168
+ under `## Defensive Recommendations`, never under `## Detailed Findings`.
169
+ - **Defense-in-depth gaps are hardening notes.** When one present layer
170
+ already prevents the crossing, a missing second layer is a note.
171
+ - **Severity never exceeds the demonstrated result.** A crash is not code
172
+ execution; self-impact is not privilege gain. A deployment fact absent from
173
+ the repo (proxy, provider, identity policy, CDN) is neither assumed present
174
+ nor absent: name it in `Current State`, grade on the demonstrated result
175
+ only, and let the self-cross-check keep or drop it on the ordinary bar.
176
+
177
+ ## Step 3: Severity anchors (security-anchored)
178
+
179
+ Grade on the shared scale, anchored to the Boundary result:
180
+
181
+ - **Critical** — no credentials needed and the result is code execution,
182
+ the whole data store, or any account the caller picks; or a leaked secret.
183
+ - **High** — an explicit control is wholly circumvented with real effect:
184
+ logging in as someone else, reading or writing another tenant's data,
185
+ persisted script that runs for other users, or RCE behind a login.
186
+ - **Medium** — a genuine crossing, but small: rare preconditions, few
187
+ affected records, or a narrow resource set.
188
+ - **Low** — internals that are not secret become visible, or the gain is
189
+ tiny for the effort.
190
+ - **Info** — real but negligible on its own; worth recording as a stepping
191
+ stone inside a larger finding.
192
+
193
+ The High/Medium line: is the control **wholly circumvented** for an action
194
+ that matters, or merely weakened? When you cannot name the concrete damage,
195
+ grade lower than instinct suggests.
196
+
119
197
  ## Report additions
120
198
 
121
- Beyond the shared skeleton (Executive Summary + Detailed Findings from the
122
- core), this lens's report carries its own title and a Defensive Recommendations
123
- section, and each finding adds the CWE ID / Baseline MUST fields:
199
+ Beyond the core's shared skeleton, this lens adds its title, a Defensive
200
+ Recommendations section and the CWE ID / Baseline MUST / Boundary fields:
124
201
 
125
202
  ```markdown
126
203
  # Security Audit Report
127
204
 
128
205
  ## Defensive Recommendations
129
206
 
130
- - [List 3-5 security headers, configurations, or libraries to implement to
131
- harden the app.]
207
+ - [3-5 headers, configs or libraries to harden the app, then every
208
+ hardening note the Boundary gate demoted.]
209
+
210
+ ### `path/to/primary-file.ext` — [Short title of the issue]
211
+
212
+ - **Dimension:** [a Tier A or Tier B dimension from Step 2]
213
+ - **Severity:** [Critical | High | Medium | Low | Info — per Step 3]
214
+ - **CWE ID:** [CWE-nnn]
215
+ - **Baseline MUST:** [the violated MUST | none — trust-boundary class]
216
+ - **Boundary:** [principal → input → control → crossed boundary → resource → result]
217
+ - [Location, Current State, Recommendation & Rationale (the smallest source
218
+ fix and why), Acceptance signal — per the core skeleton]
132
219
  ```
@@ -78,8 +78,13 @@ but not a cycle.
78
78
  unblocked it:
79
79
  `node .agents/scripts/update-ticket-state.js --ticket <id> --state agent::ready`.
80
80
  Do not poll the label yourself while waiting — the HITL pause is the operator's
81
- turn, not a slow beat. Before resuming, the operator raises session effort one
82
- step, and raises effort before switching models
81
+ turn, not a slow beat. Effort escalation on resume is automatic: the next beat's
82
+ `ready[]` entry for that Story carries `effort` (`high` after one prior block,
83
+ `xhigh` after two or more), which you pass as the Agent call's `effort`, and a
84
+ one-Story resume dispatches a worker for it. Only the inline fallback
85
+ (`delivery.routing.roleScopedAgents: false`, or a harness that cannot nest
86
+ spawns) keeps the operator step: raise session effort one step before resuming,
87
+ and raise effort before switching models
83
88
  ([effort escalation](../../docs/execution-reference.md#session-effort-and-model)).
84
89
 
85
90
  Each beat re-probes live state: it re-resolves the graph, classifies **done**
@@ -119,13 +119,15 @@ serialized against sibling Stories:
119
119
 
120
120
  ```bash
121
121
  node <main-repo>/.agents/scripts/single-story-close.js --story <storyId> --cwd <main-repo> \
122
- [--worker-tokens <n>] [--worker-model <model>]
122
+ [--worker-tokens <n>] [--worker-model <model>] [--worker-effort <level>]
123
123
  ```
124
124
 
125
125
  When the host reported a total-token figure for the story-worker's Agent
126
126
  dispatch, pass it as `--worker-tokens <n>` — close records it in its
127
- result's local `telemetry`; omit it when the host reports none. A
128
- multi-Story close command from deliver-run already carries `--worker-model`.
127
+ result's local `telemetry`; omit it when the host reports none. Every close
128
+ command deliver-run renders (a multi-Story run, or a one-Story resume) already
129
+ carries `--worker-model`, plus `--worker-effort` when the worker ran at a
130
+ resume effort.
129
131
 
130
132
  **The whole delivery tail** — gates, PR, merge wait, `agent::done` flip,
131
133
  post-land tail in one process. Never background it, never delegate it to a
@@ -554,10 +554,50 @@ Whichever channel supplies them, the supersede-map partition above still
554
554
  fail-closes: a `--tickets` run whose Stories forgot `supersedes[]` is
555
555
  **caught** (`source ticket #N is not claimed by any Story`).
556
556
 
557
+ ## Rewriting a one-for-one source in place
558
+
559
+ When a tickets-mode plan is **one-for-one** — exactly one source ticket and
560
+ exactly one drafted Story — persist rewrites that ticket instead of filing a
561
+ new Story and closing the source as its duplicate. The issue number, its
562
+ comment history and its non-`agent::*` labels survive. This is the default.
563
+ Gate #2 still asks, so the operator can choose either way:
564
+
565
+ | Choice | What persist does |
566
+ | --- | --- |
567
+ | **Rewrite #N in place** (Recommended) | No flag — the default. |
568
+ | **File a new Story and close #N** | `--no-rewrite-source` |
569
+
570
+ Under `--yes` the question is skipped and the default applies.
571
+
572
+ **The write order** keeps "`agent::ready` means fully persisted" true even
573
+ for a source that was already `agent::ready`:
574
+
575
+ 1. If the source carries no `plan-rewrite` comment, post one holding its
576
+ original title and body in a collapsed block. **First write wins** — a
577
+ later re-plan never replaces it, so the pre-plan evidence survives.
578
+ 2. One PATCH sets the new title and body (with the plan fingerprint, so a
579
+ retried persist adopts the rewritten issue instead of duplicating it),
580
+ adds the Story's labels and this run's `plan-run::` label, and removes
581
+ every `agent::*` label and any earlier run's `plan-run::` label.
582
+ 3. The `story-plan-state` comment, then the terminal `agent::ready` flip.
583
+
584
+ The supersede phase lists the rewritten id under `supersede.rewritten` and
585
+ neither comments on nor closes it; the result's `rewrite` field names the
586
+ ticket or why there was none.
587
+
588
+ **Falls back to create-and-close** with no warning for any other shape
589
+ (several sources, several Stories), under `--no-rewrite-source`, and under
590
+ `--no-close-superseded` — that flag means the remainder of the source must
591
+ stay open as itself, which a rewrite would destroy. It **falls back with a
592
+ warning** naming the reason when the source is closed, inaccessible, a
593
+ `type::epic` container, or mid-delivery (`agent::executing`,
594
+ `agent::closing`, or `agent::blocked` — a paused delivery still owns its
595
+ branch and PR).
596
+
557
597
  ## Closing superseded source tickets
558
598
 
559
- **Default on.** After the Stories exist, persist comments on each source
560
- issue naming the specific Story that claims it — plus that Story's optional
599
+ **Default on** for every source not rewritten in place (above). After the
600
+ Stories exist, persist comments on each source issue naming the specific Story that claims it — plus that Story's optional
561
601
  per-supersede `note` — and closes it with reason **`duplicate`**
562
602
  (`state_reason`): the claiming Story carries the work, and nothing has
563
603
  shipped at persist time, so `completed` would be a lie. A provider that
@@ -32,7 +32,7 @@ you read:
32
32
  | Invocation | Shape | Behavior |
33
33
  | --- | --- | --- |
34
34
  | `/mandrel-deliver` | bare | List the open `agent::ready` Stories and ask which to deliver. Deliver nothing until answered. |
35
- | `/mandrel-deliver 4712` | ids | One Story via `helpers/deliver-story.md`, **inline in this session** — no `story-worker` spawn. |
35
+ | `/mandrel-deliver 4712` | ids | One Story via `helpers/deliver-story.md`, **inline in this session** — no `story-worker` spawn. A resume of a Story that blocked before dispatches one worker instead (step 3). |
36
36
  | `/mandrel-deliver 4712 4713 …` | ids | Resolve the set, then beat `deliver-run.js` — it sequences by the discovered graph and hands back the spawns and closes. |
37
37
  | `/mandrel-deliver 4712 - 4716` | ids | A **range** — every id in the inclusive span. |
38
38
  | `/mandrel-deliver 4700` (a `type::epic`) | ids | The Epic's **open** child Stories. Mixes with Story ids. |
@@ -70,7 +70,9 @@ to an attended run.
70
70
  present the order in step 2, but do **not** thread them into step 3 — every
71
71
  beat re-resolves the graph. A one-id run comes back `dispatchMode: "inline"`
72
72
  and runs [`helpers/deliver-story.md`](helpers/deliver-story.md) in this
73
- session; step 3 is the multi-Story path. An Epic id expands to its open child
73
+ session; step 3 is the multi-Story path. A one-id run that comes back
74
+ `dispatchMode: "subagent"` is a resume of a Story that blocked before: take
75
+ step 3 with that one id, so its worker can carry the resume effort. An Epic id expands to its open child
74
76
  Stories first — **announce it**. It hard-errors (exit 1) on an id that is
75
77
  neither a Story nor an Epic, on an Epic with no open children, or on edges
76
78
  it cannot read — a missing gate would co-dispatch against an unlanded
@@ -96,8 +98,11 @@ to an attended run.
96
98
  maintained across beats by you**. Cross-run de-confliction via the assignee
97
99
  lease is automatic. Branch on the exit code:
98
100
  - **0** — spawn one `story-worker` per `ready[]` entry, **all in one turn**,
99
- each with that entry's `promptPath` file as its prompt; run each `close[]`
100
- entry's command foreground and serialized as hand-offs arrive. An empty
101
+ each with that entry's `promptPath` file as its prompt. When the entry's
102
+ `effort` is non-null, pass it as that Agent call's `effort`; when it is
103
+ `null`, omit the parameter so the worker inherits the session. Run each
104
+ `close[]` entry's command foreground and serialized as hand-offs arrive.
105
+ An empty
101
106
  `ready` with work in flight means "waiting", so beat again — **unless
102
107
  `stalledDispatch[]` is non-empty**: those ids were dispatched but still
103
108
  read `agent::ready`, which is a live init window the first beats or two
@@ -121,6 +121,11 @@ than one Story** (a split always earns operator eyes, `--force-review` or
121
121
  not), or when the operator asked to review (`--force-review`).
122
122
  Under `--yes`, auto-proceed.
123
123
 
124
+ **One-for-one (tickets mode, one source → one Story)** — ask with
125
+ AskUserQuestion: **Rewrite #N in place (Recommended)** or **File a new Story
126
+ and close #N** (`--no-rewrite-source`). Under `--yes`, rewrite
127
+ ([ref](helpers/plan-reference.md)).
128
+
124
129
  **Gate #3 — adopt, else create.** Offer the top `epicCandidates[]` Epic at
125
130
  **any N** (`--epic <id>`); else, at **N>2**, a new container (`--epic-title` /
126
131
  `--epic-goal`). Never unasked ([ref](helpers/plan-reference.md)).
@@ -151,7 +156,8 @@ Persist creates `type::story` issue(s), a **metadata-only** `plan-run::<id>`
151
156
  label, `blocked by #<id>` footers for every `depends_on` edge, and on a Gate #3
152
157
  yes links them under a `type::epic` container (adopted or new). `agent::ready`
153
158
  is the **terminal** flip after receipts land; stdout is pure JSON. Tickets mode
154
- also comments on and closes each source id ([ref](helpers/plan-reference.md)).
159
+ rewrites a one-for-one source in place, else comments on and closes each
160
+ source id ([ref](helpers/plan-reference.md)).
155
161
 
156
162
  ## Constraints
157
163
 
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,22 @@ 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.81.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.80.0...mandrel-v2.81.0) (2026-10-11)
19
+
20
+
21
+ ### Added
22
+
23
+ * /mandrel-plan rewrites a one-for-one source ticket in place instead of filing a new Story ([#5604](https://github.com/dsj1984/mandrel/issues/5604)) ([#5610](https://github.com/dsj1984/mandrel/issues/5610)) ([5e0f621](https://github.com/dsj1984/mandrel/commit/5e0f6215680ee9d9fec079a93fd51d531d59023a))
24
+ * agent cost report: per-subagent effort, model, tokens and wall time from Claude Code transcripts ([#5607](https://github.com/dsj1984/mandrel/issues/5607)) ([#5611](https://github.com/dsj1984/mandrel/issues/5611)) ([c1680ca](https://github.com/dsj1984/mandrel/commit/c1680ca12298e21a51d8000437a675fb94bd23f2))
25
+ * audit-security: trust-boundary attack classes, a Boundary candidate-gate field, and lens-specific severity anchors (adapted from Cloudflare's MIT security-audit skill) ([#5606](https://github.com/dsj1984/mandrel/issues/5606)) ([#5612](https://github.com/dsj1984/mandrel/issues/5612)) ([34dc807](https://github.com/dsj1984/mandrel/commit/34dc8077f7d2392385355519180d6f0122f27770))
26
+ * duplication gate now scans TS/TSX/JSX; re-seat via duplication:reanchor ([#5605](https://github.com/dsj1984/mandrel/issues/5605)) ([#5609](https://github.com/dsj1984/mandrel/issues/5609)) ([5f73168](https://github.com/dsj1984/mandrel/commit/5f731680c4c16aa1ba11b1d2f02032af931ea5aa))
27
+ * escalate effort per call on a blocked-Story resume instead of raising whole-session effort ([#5608](https://github.com/dsj1984/mandrel/issues/5608)) ([#5617](https://github.com/dsj1984/mandrel/issues/5617)) ([4285cdf](https://github.com/dsj1984/mandrel/commit/4285cdf55b057723f60dbe17808c23e421f645d7))
28
+
29
+
30
+ ### Fixed
31
+
32
+ * **test:** attribute temp-paths leak writes by nonce, not stream growth (refs [#5615](https://github.com/dsj1984/mandrel/issues/5615)) ([#5616](https://github.com/dsj1984/mandrel/issues/5616)) ([0f33cec](https://github.com/dsj1984/mandrel/commit/0f33cecfe4db122074d79516b2d0c70c3e92bd0f))
33
+
18
34
  ## [2.80.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.79.0...mandrel-v2.80.0) (2026-10-09)
19
35
 
20
36
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.80.0",
3
+ "version": "2.81.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",
@@ -21,6 +21,7 @@
21
21
  "test:integration": "node .agents/scripts/run-tests.js --tier integration",
22
22
  "test:e2e": "node .agents/scripts/run-tests.js --tier e2e",
23
23
  "test:profile": "node scripts/run-test-profile.js",
24
+ "report:agent-cost": "node scripts/agent-cost-report.js",
24
25
  "test:census": "SPAWN_CENSUS_OUT=\"${SPAWN_CENSUS_OUT:-temp/census.json}\" NODE_OPTIONS=\"--require $PWD/tests/fixtures/spawn-census.cjs\" node .agents/scripts/run-tests.js",
25
26
  "test:isolate": "node scripts/test-isolate.js",
26
27
  "verify": "node scripts/run-verify.js",