mandrel 2.111.0 → 2.112.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 (178) hide show
  1. package/.agents/agents/acceptance-critic.md +14 -0
  2. package/.agents/agents/auditor.md +14 -0
  3. package/.agents/agents/plan-critic.md +5 -0
  4. package/.agents/agents/story-worker.md +4 -1
  5. package/.agents/docs/agentrc-reference.json +22 -10
  6. package/.agents/docs/configuration.md +351 -37
  7. package/.agents/docs/execution-reference.md +11 -0
  8. package/.agents/rules/git-conventions-reference.md +7 -0
  9. package/.agents/schemas/agentrc.schema.json +174 -14
  10. package/.agents/schemas/baselines/baseline-envelope.schema.json +16 -4
  11. package/.agents/schemas/baselines/bundle-size.schema.json +1 -0
  12. package/.agents/schemas/baselines/coverage.schema.json +1 -0
  13. package/.agents/schemas/baselines/crap.schema.json +37 -10
  14. package/.agents/schemas/baselines/duplication.schema.json +1 -0
  15. package/.agents/schemas/baselines/maintainability.schema.json +1 -0
  16. package/.agents/schemas/baselines/mutation.schema.json +1 -0
  17. package/.agents/schemas/crap-report.schema.json +6 -5
  18. package/.agents/schemas/story-deliver-terminal.schema.json +41 -2
  19. package/.agents/schemas/story-progress.schema.json +1 -1
  20. package/.agents/schemas/validation-evidence.schema.json +2 -2
  21. package/.agents/scripts/boot-sweep.js +41 -3
  22. package/.agents/scripts/coverage-capture.js +37 -3
  23. package/.agents/scripts/coverage-ratchet.js +106 -0
  24. package/.agents/scripts/evidence-gate.js +84 -21
  25. package/.agents/scripts/lib/audit-baselines/read.js +8 -1
  26. package/.agents/scripts/lib/audit-baselines/trend.js +2 -1
  27. package/.agents/scripts/lib/baseline-loader.js +4 -2
  28. package/.agents/scripts/lib/baselines/codec.js +57 -0
  29. package/.agents/scripts/lib/baselines/crap-preview-incremental.js +8 -3
  30. package/.agents/scripts/lib/baselines/crap-preview-scan.js +10 -16
  31. package/.agents/scripts/lib/baselines/crap-updater-cli.js +4 -13
  32. package/.agents/scripts/lib/baselines/kernel.js +19 -1
  33. package/.agents/scripts/lib/baselines/kinds/_crap-codec.js +171 -0
  34. package/.agents/scripts/lib/baselines/kinds/_crap-read.js +56 -16
  35. package/.agents/scripts/lib/baselines/kinds/_shared-metric.js +0 -59
  36. package/.agents/scripts/lib/baselines/kinds/crap.js +283 -319
  37. package/.agents/scripts/lib/baselines/preview-gates.js +29 -10
  38. package/.agents/scripts/lib/baselines/reader.js +36 -9
  39. package/.agents/scripts/lib/baselines/refresh-service.js +79 -18
  40. package/.agents/scripts/lib/baselines/seat-missing.js +173 -7
  41. package/.agents/scripts/lib/baselines/writer.js +36 -21
  42. package/.agents/scripts/lib/changed-files.js +70 -6
  43. package/.agents/scripts/lib/child-exec.js +10 -0
  44. package/.agents/scripts/lib/claude/agents-projection.js +5 -5
  45. package/.agents/scripts/lib/close-lock-events.js +8 -3
  46. package/.agents/scripts/lib/close-validation/ci-deferral.js +40 -0
  47. package/.agents/scripts/lib/close-validation/gates.js +111 -35
  48. package/.agents/scripts/lib/close-validation/process.js +16 -7
  49. package/.agents/scripts/lib/close-validation/projections/crap.js +43 -10
  50. package/.agents/scripts/lib/close-validation/runner.js +55 -23
  51. package/.agents/scripts/lib/close-validation/skip-branch-test.js +144 -0
  52. package/.agents/scripts/lib/close-validation/test-delta.js +33 -8
  53. package/.agents/scripts/lib/codex/agents-projection.js +6 -0
  54. package/.agents/scripts/lib/config/agentrc-overlay.js +9 -5
  55. package/.agents/scripts/lib/config/explain.js +5 -2
  56. package/.agents/scripts/lib/config/gates/coverage.schema.js +45 -1
  57. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  58. package/.agents/scripts/lib/config/git-roots.js +38 -4
  59. package/.agents/scripts/lib/config/handoff.js +24 -0
  60. package/.agents/scripts/lib/config/quality.js +26 -13
  61. package/.agents/scripts/lib/config/worktree-isolation.js +2 -5
  62. package/.agents/scripts/lib/config-resolver.js +22 -2
  63. package/.agents/scripts/lib/config-settings-schema-delivery.js +87 -4
  64. package/.agents/scripts/lib/config-settings-schema-quality.js +36 -1
  65. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  66. package/.agents/scripts/lib/coverage-capture-affected.js +1 -0
  67. package/.agents/scripts/lib/coverage-capture-delta.js +164 -32
  68. package/.agents/scripts/lib/coverage-capture-own-fix.js +232 -0
  69. package/.agents/scripts/lib/coverage-capture-usage.js +2 -2
  70. package/.agents/scripts/lib/coverage-capture.js +15 -0
  71. package/.agents/scripts/lib/coverage-deferral.js +96 -0
  72. package/.agents/scripts/lib/coverage-ratchet.js +187 -0
  73. package/.agents/scripts/lib/crap-baseline-join.js +5 -5
  74. package/.agents/scripts/lib/crap-engine.js +3 -3
  75. package/.agents/scripts/lib/crap-method-identity.js +104 -48
  76. package/.agents/scripts/lib/escomplex-anchor.js +135 -0
  77. package/.agents/scripts/lib/escomplex-kernel.js +30 -1
  78. package/.agents/scripts/lib/failure-rows.js +121 -0
  79. package/.agents/scripts/lib/full-suite-lock.js +44 -4
  80. package/.agents/scripts/lib/full-suite-queue.js +89 -13
  81. package/.agents/scripts/lib/generated/agentrc-validator.js +8 -2
  82. package/.agents/scripts/lib/gh-env.js +3 -6
  83. package/.agents/scripts/lib/gh-pr-rest.js +1 -0
  84. package/.agents/scripts/lib/git/base-sync-probe.js +182 -0
  85. package/.agents/scripts/lib/git-branch-lifecycle.js +9 -0
  86. package/.agents/scripts/lib/observability/close-telemetry.js +37 -2
  87. package/.agents/scripts/lib/observability/handoff-telemetry.js +170 -0
  88. package/.agents/scripts/lib/observability/review-dispositions.js +23 -6
  89. package/.agents/scripts/lib/observability/runtime-friction.js +17 -4
  90. package/.agents/scripts/lib/observability/source-classifier.js +3 -0
  91. package/.agents/scripts/lib/observability/story-outcome.js +393 -0
  92. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +2 -1
  93. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +19 -1
  94. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +84 -0
  95. package/.agents/scripts/lib/orchestration/check-baselines/phases/pipeline.js +14 -5
  96. package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js +3 -2
  97. package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js +26 -6
  98. package/.agents/scripts/lib/orchestration/code-review.js +223 -19
  99. package/.agents/scripts/lib/orchestration/handoff-gates.js +129 -62
  100. package/.agents/scripts/lib/orchestration/handoff-rescore.js +169 -0
  101. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +45 -0
  102. package/.agents/scripts/lib/orchestration/preflight-lanes.js +208 -0
  103. package/.agents/scripts/lib/orchestration/review-base-ref.js +40 -17
  104. package/.agents/scripts/lib/orchestration/review-deposit.js +38 -12
  105. package/.agents/scripts/lib/orchestration/review-depth.js +21 -0
  106. package/.agents/scripts/lib/orchestration/review-history.js +124 -20
  107. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +23 -8
  108. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +82 -39
  109. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +64 -11
  110. package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js +98 -3
  111. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +6 -2
  112. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +55 -8
  113. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +1 -0
  114. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +42 -15
  115. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  116. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +10 -1
  117. package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js +10 -0
  118. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +7 -4
  119. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +15 -3
  120. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +59 -2
  121. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +6 -0
  122. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +15 -4
  123. package/.agents/scripts/lib/orchestration/single-story-close/phases/land-review-record.js +213 -0
  124. package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +9 -12
  125. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +26 -12
  126. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +51 -26
  127. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +3 -2
  128. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +50 -17
  129. package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js +59 -11
  130. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +1 -0
  131. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-block.js +31 -13
  132. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +29 -6
  133. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js +10 -12
  134. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +19 -4
  135. package/.agents/scripts/lib/orchestration/single-story-close/result.js +30 -13
  136. package/.agents/scripts/lib/orchestration/single-story-close/review-overlap.js +73 -39
  137. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +11 -3
  138. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +3 -2
  139. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +20 -8
  140. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +7 -0
  141. package/.agents/scripts/lib/orchestration/story-handoff.js +774 -196
  142. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  143. package/.agents/scripts/lib/pr-body-lines.js +32 -0
  144. package/.agents/scripts/lib/single-story/ci-ratchet-gate.js +140 -0
  145. package/.agents/scripts/lib/single-story/confirm-and-land.js +17 -7
  146. package/.agents/scripts/lib/single-story/confirm-merge.js +12 -3
  147. package/.agents/scripts/lib/single-story-sweep/report-stalled-executing.js +202 -0
  148. package/.agents/scripts/lib/standalone-ratchets.js +37 -0
  149. package/.agents/scripts/lib/suite-admission.js +20 -8
  150. package/.agents/scripts/lib/suite-sizing.js +146 -0
  151. package/.agents/scripts/lib/workspace-provisioner.js +2 -2
  152. package/.agents/scripts/merge-baseline.js +14 -3
  153. package/.agents/scripts/providers/github/comments.js +19 -3
  154. package/.agents/scripts/providers/github.js +1 -0
  155. package/.agents/scripts/review-dispositions-report.js +1 -1
  156. package/.agents/scripts/role-scope-guard.js +267 -0
  157. package/.agents/scripts/single-story-close.js +4 -4
  158. package/.agents/scripts/single-story-confirm-merge.js +31 -5
  159. package/.agents/scripts/single-story-init.js +24 -4
  160. package/.agents/scripts/story-handoff.js +3 -3
  161. package/.agents/scripts/story-outcomes-report.js +231 -0
  162. package/.agents/scripts/story-review-compute.js +9 -5
  163. package/.agents/scripts/update-coverage-baseline.js +12 -2
  164. package/.agents/scripts/update-crap-baseline.js +9 -1
  165. package/.agents/workflows/helpers/code-review.md +63 -9
  166. package/.agents/workflows/helpers/deliver-digest.md +53 -54
  167. package/.agents/workflows/helpers/deliver-reference.md +233 -67
  168. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  169. package/.agents/workflows/helpers/deliver-story.md +7 -2
  170. package/.agents/workflows/helpers/parallel-tooling.md +29 -0
  171. package/docs/CHANGELOG.md +46 -0
  172. package/lib/cli/doctor-checks/coverage-ratchet.js +54 -0
  173. package/lib/cli/doctor-checks/effective-agentrc.js +23 -0
  174. package/lib/cli/doctor-checks/llm-review.js +2 -11
  175. package/lib/cli/doctor-checks/sync-parity.js +5 -1
  176. package/lib/cli/doctor-checks/test-credit-path.js +7 -2
  177. package/lib/cli/registry.js +5 -0
  178. package/package.json +1 -1
@@ -0,0 +1,146 @@
1
+ /**
2
+ * suite-sizing.js — size a declared workload before it reserves: run its
3
+ * `sizeCommand` (no shell, async, 60 s bound), read the slice's test-file
4
+ * count from the last stdout line, and pick the first tier that covers it.
5
+ * Every failure books the entry's full declared weight.
6
+ */
7
+ import { execFileCaptureAsync } from './child-exec.js';
8
+
9
+ const SIZE_TIMEOUT_MS = 60_000;
10
+
11
+ const LOCK_TAG = '[full-suite-lock]';
12
+
13
+ const COUNT_RE = /^\d+$/;
14
+
15
+ /**
16
+ * @param {{ command: string, cwd?: string, env?: Record<string, string|undefined>,
17
+ * timeoutMs?: number }} opts
18
+ * @returns {Promise<{ count: number }|{ reason: string }>}
19
+ */
20
+ export async function runSizeCommand({
21
+ command,
22
+ cwd,
23
+ env,
24
+ timeoutMs = SIZE_TIMEOUT_MS,
25
+ }) {
26
+ const [cmd, ...args] = String(command ?? '')
27
+ .split(/\s+/)
28
+ .filter(Boolean);
29
+ try {
30
+ const { stdout } = await execFileCaptureAsync(cmd, args, {
31
+ cwd,
32
+ env,
33
+ timeout: timeoutMs,
34
+ killSignal: 'SIGKILL',
35
+ });
36
+ return parseCount(stdout);
37
+ } catch (err) {
38
+ return { reason: failureReason(err, timeoutMs) };
39
+ }
40
+ }
41
+
42
+ function failureReason(err, timeoutMs) {
43
+ if (err.killed) return `timed out after ${timeoutMs}ms`;
44
+ return Number.isInteger(err.code)
45
+ ? `exited ${err.code}`
46
+ : `spawn failed: ${err.message}`;
47
+ }
48
+
49
+ function parseCount(stdout) {
50
+ const last = String(stdout)
51
+ .split(/\r?\n/)
52
+ .filter((l) => l.trim())
53
+ .at(-1)
54
+ ?.trim();
55
+ return COUNT_RE.test(last ?? '')
56
+ ? { count: Number(last) }
57
+ : { reason: 'printed no file count' };
58
+ }
59
+
60
+ /**
61
+ * The first tier (ascending `maxFiles`) covering `count`; full weight when
62
+ * none does, when sizing failed, or when the tier outweighs the entry.
63
+ *
64
+ * @param {{ weight: number, tiers: Array<{ maxFiles: number, weight: number }> }} workload
65
+ * @param {{ count?: number, reason?: string }} sized
66
+ * @returns {{ weight: number, reason: string|null }}
67
+ */
68
+ function selectTierWeight({ weight, tiers }, sized) {
69
+ if (sized.count === undefined) return { weight, reason: sized.reason };
70
+ const tier = [...tiers]
71
+ .sort((a, b) => a.maxFiles - b.maxFiles)
72
+ .find((t) => sized.count <= t.maxFiles);
73
+ if (!tier) return { weight, reason: 'no tier covers the slice' };
74
+ if (tier.weight > weight) {
75
+ return {
76
+ weight,
77
+ reason: `tier weight ${tier.weight} exceeds the declared weight`,
78
+ };
79
+ }
80
+ return { weight: tier.weight, reason: null };
81
+ }
82
+
83
+ /**
84
+ * A declared workload with tiers, re-weighted to its slice; any other
85
+ * workload unchanged.
86
+ *
87
+ * @param {object} workload
88
+ * @param {{ cwd?: string, env?: object, log: (m: string) => void,
89
+ * runSizeFn?: typeof runSizeCommand }} opts
90
+ * @returns {Promise<object>}
91
+ */
92
+ export async function sizeWorkload(
93
+ workload,
94
+ { cwd, env, log, runSizeFn = runSizeCommand },
95
+ ) {
96
+ if (workload?.kind !== 'declared' || !workload.tiers) return workload;
97
+ const sized = await runSizeFn({ command: workload.sizeCommand, cwd, env });
98
+ const pick = selectTierWeight(workload, sized);
99
+ const slice = sized.count === undefined ? 'unsized' : `${sized.count} files`;
100
+ const why = pick.reason ? `, full weight: ${pick.reason}` : '';
101
+ log(
102
+ `${LOCK_TAG} ⚖ sized \`${workload.command}\` with \`${workload.sizeCommand}\`: ${slice}${why} → weight ${pick.weight} of ${workload.weight}.`,
103
+ );
104
+ return {
105
+ ...workload,
106
+ weight: pick.weight,
107
+ declaredWeight: workload.weight,
108
+ sliceFiles: sized.count ?? null,
109
+ };
110
+ }
111
+ /** The declared-run admitted line; `null` leaves the exclusive wording. */
112
+ export function admittedLine(workload, waited, passed = 0) {
113
+ const record = admissionRecord(workload, passed > 0);
114
+ if (!record) return null;
115
+ const slice =
116
+ record.sliceFiles === null ? 'unsized' : `slice ${record.sliceFiles} files`;
117
+ const backfill =
118
+ passed > 0 ? `, backfilled past ${passed} earlier waiter(s)` : '';
119
+ return `${LOCK_TAG} ✅ admitted \`${workload.command}\` (weight ${record.weight} of declared ${record.declaredWeight}, ${slice}, waited ${waited}s${backfill}).`;
120
+ }
121
+
122
+ /**
123
+ * What a declared run was admitted at; `null` for any other workload.
124
+ *
125
+ * @returns {{ weight: number, declaredWeight: number,
126
+ * sliceFiles: number|null, backfilled: boolean }|null}
127
+ */
128
+ export function admissionRecord(workload, backfilled) {
129
+ if (workload?.kind !== 'declared') return null;
130
+ return {
131
+ weight: workload.weight,
132
+ declaredWeight: workload.declaredWeight ?? workload.weight,
133
+ sliceFiles: workload.sliceFiles ?? null,
134
+ backfilled: Boolean(backfilled),
135
+ };
136
+ }
137
+
138
+ /** The sizing and backfill fields a workload entry declares, if any. */
139
+ export function sizingFields(entry) {
140
+ return {
141
+ ...(entry.tiers
142
+ ? { tiers: entry.tiers, sizeCommand: entry.sizeCommand }
143
+ : {}),
144
+ ...(entry.backfill === true ? { backfill: true } : {}),
145
+ };
146
+ }
@@ -10,11 +10,11 @@ import path from 'node:path';
10
10
  import { NOOP_LOGGER } from './Logger.js';
11
11
 
12
12
  // Keep in sync with `WORKTREE_ISOLATION_DEFAULTS.bootstrapFiles`. Often-absent
13
- // overrides are safe: missing sources are skipped, never fatal.
13
+ // overrides are safe: missing sources are skipped, never fatal. No
14
+ // `.agentrc.local.json`: a worktree reads the main checkout's live overlay.
14
15
  export const DEFAULT_WORKSPACE_FILES = [
15
16
  '.env',
16
17
  '.mcp.json',
17
- '.agentrc.local.json',
18
18
  '.agents/instructions.local.md',
19
19
  ];
20
20
 
@@ -18,7 +18,9 @@
18
18
 
19
19
  import fs from 'node:fs';
20
20
  import path from 'node:path';
21
+ import { decodeEnvelope } from './lib/baselines/codec.js';
21
22
  import { assertEnvelope } from './lib/baselines/envelope.js';
23
+ import { renderCrapConflicts } from './lib/baselines/kinds/_crap-codec.js';
22
24
  import {
23
25
  baselineRegenerateRemedy,
24
26
  kindFromEnvelope,
@@ -82,13 +84,22 @@ export function renderConflictMarkers(text, conflicts) {
82
84
  return out;
83
85
  }
84
86
 
85
- /** Read and parse a merge input; a missing or empty side is `null`. */
87
+ /** The grouped CRAP layout keeps one line per method, so it has its own. */
88
+ function renderRowConflicts(kind, text, conflicts) {
89
+ return kind === 'crap'
90
+ ? renderCrapConflicts(text, conflicts)
91
+ : renderConflictMarkers(text, conflicts);
92
+ }
93
+
94
+ /**
95
+ * Read, parse and decode a merge input; a missing or empty side is `null`.
96
+ */
86
97
  function readSide(file) {
87
98
  if (!file || !fs.existsSync(file)) return null;
88
99
  const raw = fs.readFileSync(file, 'utf8');
89
100
  if (raw.trim() === '') return null;
90
101
  try {
91
- return JSON.parse(raw);
102
+ return decodeEnvelope(JSON.parse(raw));
92
103
  } catch {
93
104
  return undefined; // present but unparseable — caller falls back to git
94
105
  }
@@ -264,7 +275,7 @@ function markConflicts({ kind, merged, oursPath, label }) {
264
275
  text = renderStampConflict(text, envelopeConflicts);
265
276
  }
266
277
  if (rowConflicts.length > 0) {
267
- text = renderConflictMarkers(text, rowConflicts);
278
+ text = renderRowConflicts(kind, text, rowConflicts);
268
279
  }
269
280
  fs.writeFileSync(oursPath, text);
270
281
  return 1;
@@ -6,6 +6,9 @@
6
6
 
7
7
  import { paginateRest, parseApiJson } from './request-helpers.js';
8
8
 
9
+ // 50,000 comments: a wide `story-outcomes-report --since` window stays readable.
10
+ const REPO_COMMENTS_PAGE_CAP = 500;
11
+
9
12
  // Visible headers downstream consumers grep for — keep them byte-stable.
10
13
  const TYPE_BADGES = {
11
14
  progress: '🔄 **Progress**',
@@ -36,16 +39,29 @@ export class CommentGateway {
36
39
  * id, body, created_at, user
37
40
  */
38
41
  async getTicketComments(ticketId) {
42
+ return paginateRest(this._gh, `${this._issues()}/${ticketId}/comments`);
43
+ }
44
+
45
+ _issues() {
46
+ return `/repos/${this.owner}/${this.repo}/issues`;
47
+ }
48
+
49
+ /**
50
+ * @field-manifest /repos/{owner}/{repo}/issues/comments:
51
+ * id, body, issue_url, updated_at
52
+ */
53
+ async getRepoCommentsSince(since) {
39
54
  return paginateRest(
40
55
  this._gh,
41
- `/repos/${this.owner}/${this.repo}/issues/${ticketId}/comments`,
56
+ `${this._issues()}/comments?since=${encodeURIComponent(since)}`,
57
+ { pageCap: REPO_COMMENTS_PAGE_CAP },
42
58
  );
43
59
  }
44
60
 
45
61
  async deleteComment(commentId) {
46
62
  await this._gh.api({
47
63
  method: 'DELETE',
48
- endpoint: `/repos/${this.owner}/${this.repo}/issues/comments/${commentId}`,
64
+ endpoint: `${this._issues()}/comments/${commentId}`,
49
65
  });
50
66
  }
51
67
 
@@ -64,7 +80,7 @@ export class CommentGateway {
64
80
 
65
81
  const result = await this._gh.api({
66
82
  method: 'POST',
67
- endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}/comments`,
83
+ endpoint: `${this._issues()}/${ticketId}/comments`,
68
84
  body: { body },
69
85
  });
70
86
  const comment = parseApiJson(result);
@@ -101,6 +101,7 @@ const DELEGATIONS = [
101
101
  // Legacy private alias with live call sites; same target, so both agree.
102
102
  ['_getNativeSubIssues', 'subIssues.getNativeSubIssues'],
103
103
  ['getTicketComments', 'comments.getTicketComments'],
104
+ ['getRepoCommentsSince', 'comments.getRepoCommentsSince'],
104
105
  ['deleteComment', 'comments.deleteComment'],
105
106
  ['postComment', 'comments.postComment'],
106
107
  ['getBranchProtection', 'branchProtection.getBranchProtection'],
@@ -47,7 +47,7 @@ function renderTable(label, groups) {
47
47
  }
48
48
 
49
49
  /** @param {string[][]} rows @returns {string[]} space-padded columns. */
50
- function alignRows(rows) {
50
+ export function alignRows(rows) {
51
51
  const widths = [];
52
52
  for (const row of rows) {
53
53
  row.forEach((cell, i) => {
@@ -0,0 +1,267 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * PreToolUse hook for the reviewer roles (`acceptance-critic`, `auditor`).
5
+ * Reads the hook payload on stdin; exit 0 allows the call, exit 2 denies it
6
+ * with a one-line stderr reason. A write tool may only target the project's
7
+ * tempRoot (or a `.worktrees/<name>/` checkout's); a Bash command is denied
8
+ * when a segment matches a named mutation class. A deny-list, not a sandbox.
9
+ */
10
+
11
+ import fs from 'node:fs';
12
+ import path from 'node:path';
13
+ import { parseArgs } from 'node:util';
14
+
15
+ import { runAsCli } from './lib/cli-utils.js';
16
+ import { getPaths, resolveConfig } from './lib/config-resolver.js';
17
+
18
+ const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
19
+
20
+ const GIT_WRITE_VERBS = new Set(
21
+ 'add commit push checkout switch restore reset stash rebase merge cherry-pick revert tag clean rm mv apply am'.split(
22
+ ' ',
23
+ ),
24
+ );
25
+ const GIT_VALUE_OPTIONS = new Set([
26
+ '-C',
27
+ '-c',
28
+ '--git-dir',
29
+ '--work-tree',
30
+ '--namespace',
31
+ ]);
32
+ const GH_WRITE_VERBS = new Set(
33
+ 'create edit close reopen comment merge review ready lock delete'.split(' '),
34
+ );
35
+ const GH_LABEL_VERBS = new Set(['create', 'edit', 'delete']);
36
+ const INSTALL_VERBS = new Set([
37
+ 'install',
38
+ 'i',
39
+ 'add',
40
+ 'remove',
41
+ 'uninstall',
42
+ 'ci',
43
+ ]);
44
+
45
+ /** Commands that run their argv as a command, each with its valued flags. */
46
+ const WRAPPERS = new Map([
47
+ ['env', new Set(['-u'])],
48
+ ['command', new Set()],
49
+ ['nohup', new Set()],
50
+ ['time', new Set()],
51
+ ['exec', new Set()],
52
+ ['builtin', new Set()],
53
+ ['sudo', new Set(['-u', '-g', '-C'])],
54
+ ['xargs', new Set(['-n', '-I', '-L', '-P', '-d', '-s', '-E'])],
55
+ ]);
56
+
57
+ class Denied extends Error {}
58
+
59
+ /** @param {string} rule */
60
+ function deny(rule) {
61
+ throw new Denied(rule);
62
+ }
63
+
64
+ /** True when `abs` sits strictly below `root`. */
65
+ function isInside(root, abs) {
66
+ const rel = path.relative(root, abs);
67
+ return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
68
+ }
69
+
70
+ /**
71
+ * @param {string} target
72
+ * @param {{ projectDir: string, cwd: string, tempRoot: string }} ctx
73
+ */
74
+ function checkWriteTarget(target, { projectDir, cwd, tempRoot }) {
75
+ if (typeof target !== 'string' || target === '') {
76
+ deny('write target path missing');
77
+ }
78
+ const posix = target.replace(/\\/g, '/');
79
+ if (process.platform !== 'win32' && /^[A-Za-z]:\//.test(posix)) {
80
+ deny(`write target ${target} is outside ${tempRoot}/`);
81
+ }
82
+ const abs = path.resolve(cwd, posix);
83
+ if (isInside(path.resolve(projectDir, tempRoot), abs)) return;
84
+ const worktrees = path.resolve(projectDir, '.worktrees');
85
+ if (isInside(worktrees, abs)) {
86
+ const name = path.relative(worktrees, abs).split(path.sep)[0];
87
+ if (isInside(path.resolve(worktrees, name, tempRoot), abs)) return;
88
+ }
89
+ deny(`write target ${target} is outside ${tempRoot}/`);
90
+ }
91
+
92
+ /** @param {string[]} words drops leading `NAME=value` env prefixes */
93
+ function dropEnvPrefixes(words) {
94
+ while (words.length && /^[A-Za-z_]\w*=/.test(words[0])) words.shift();
95
+ }
96
+
97
+ /**
98
+ * @param {string[]} words argv whose head is a wrapper command
99
+ * @param {Set<string>} valued the wrapper's flags that take a value
100
+ */
101
+ function dropWrapper(words, valued) {
102
+ words.shift();
103
+ while (words[0]?.startsWith('-')) {
104
+ words.splice(0, valued.has(words[0]) ? 2 : 1);
105
+ }
106
+ }
107
+
108
+ /** @param {string} segment */
109
+ function rawWords(segment) {
110
+ return segment
111
+ .trim()
112
+ .replace(/^[{$]+/, '')
113
+ .split(/\s+/)
114
+ .map((w) => w.replace(/^['"]|['"]$/g, ''))
115
+ .filter(Boolean);
116
+ }
117
+
118
+ /**
119
+ * Whitespace tokens of one segment, quotes stripped, env prefixes and
120
+ * wrapper commands (`env`, `sudo`, `xargs`, …) dropped.
121
+ */
122
+ function tokens(segment) {
123
+ const words = rawWords(segment);
124
+ for (;;) {
125
+ dropEnvPrefixes(words);
126
+ if (!words.length) return words;
127
+ words[0] = path.posix.basename(words[0]);
128
+ const valued = WRAPPERS.get(words[0]);
129
+ if (!valued) return words;
130
+ dropWrapper(words, valued);
131
+ }
132
+ }
133
+
134
+ /** @param {string[]} args git argv after `git` */
135
+ function gitRule(args) {
136
+ let i = 0;
137
+ while (args[i]?.startsWith('-')) i += GIT_VALUE_OPTIONS.has(args[i]) ? 2 : 1;
138
+ const [verb, sub, ...rest] = args.slice(i);
139
+ if (GIT_WRITE_VERBS.has(verb)) return `git ${verb}`;
140
+ if (verb === 'worktree' && ['add', 'remove', 'prune'].includes(sub)) {
141
+ return `git worktree ${sub}`;
142
+ }
143
+ const branchFlags = ['-d', '-D', '-m', '-M', '--delete', '--move'];
144
+ if (verb === 'branch' && [sub, ...rest].some((a) => branchFlags.includes(a)))
145
+ return 'git branch delete/rename';
146
+ return null;
147
+ }
148
+
149
+ /** @param {string[]} args gh argv after `gh api` */
150
+ function ghApiRule(args) {
151
+ for (let i = 0; i < args.length; i += 1) {
152
+ const method = /^(?:-X|--method)=?(.*)$/.exec(args[i]);
153
+ const value = method && (method[1] || args[i + 1] || '');
154
+ if (method && value.toUpperCase() !== 'GET') return 'gh api write method';
155
+ if (/^(?:-[fF]|--field|--raw-field|--input)(?:=|$)/.test(args[i])) {
156
+ return 'gh api with request fields';
157
+ }
158
+ }
159
+ return null;
160
+ }
161
+
162
+ /** @param {string[]} args gh argv after `gh` */
163
+ function ghRule(args) {
164
+ const [group, verb] = args;
165
+ if ((group === 'issue' || group === 'pr') && GH_WRITE_VERBS.has(verb)) {
166
+ return `gh ${group} ${verb}`;
167
+ }
168
+ if (group === 'label' && GH_LABEL_VERBS.has(verb)) return `gh label ${verb}`;
169
+ return group === 'api' ? ghApiRule(args.slice(1)) : null;
170
+ }
171
+
172
+ /** @param {string} arg true when a sed/perl argv entry edits in place */
173
+ function isInPlaceFlag(arg) {
174
+ return (
175
+ /^--in-place(=|$)/.test(arg) ||
176
+ (/^-[A-Za-z]*i/.test(arg) && !/^-M/i.test(arg))
177
+ );
178
+ }
179
+
180
+ /** @param {string[]} words */
181
+ function segmentRule(words) {
182
+ const [cmd, ...args] = words;
183
+ if (cmd === 'git') return gitRule(args);
184
+ if (cmd === 'gh') return ghRule(args);
185
+ if (cmd === 'sed' || cmd === 'perl') {
186
+ return args.some(isInPlaceFlag) ? `${cmd} -i` : null;
187
+ }
188
+ if (['npm', 'pnpm', 'yarn'].includes(cmd) && INSTALL_VERBS.has(args[0])) {
189
+ return `${cmd} ${args[0]}`;
190
+ }
191
+ return null;
192
+ }
193
+
194
+ /**
195
+ * Subshells, substitutions and brace groups become segment breaks; a brace
196
+ * only as a whole word, so `{owner}` placeholders and `${VAR}` survive.
197
+ * @param {string} command
198
+ */
199
+ function flattenGroups(command) {
200
+ return command
201
+ .replace(/\$\(|[`()]/g, ';')
202
+ .replace(/(^|\s)[{}](?=\s|;|$)/g, '$1;');
203
+ }
204
+
205
+ /** @param {unknown} command */
206
+ function checkBash(command) {
207
+ if (typeof command !== 'string') deny('Bash command missing');
208
+ const flat = flattenGroups(command);
209
+ for (const segment of flat.split(/\|\||&&|(?<![&>])&(?![&>])|[;|\n]/)) {
210
+ const rule = segmentRule(tokens(segment));
211
+ if (rule) deny(`mutation class '${rule}'`);
212
+ }
213
+ }
214
+
215
+ /** @param {any} payload the parsed PreToolUse payload */
216
+ function evaluate(payload) {
217
+ const tool = payload?.tool_name;
218
+ const input = payload?.tool_input ?? {};
219
+ if (tool === 'Bash') return checkBash(input.command);
220
+ if (!WRITE_TOOLS.has(tool)) return;
221
+ const projectDir = process.env.CLAUDE_PROJECT_DIR || payload.cwd;
222
+ if (!projectDir) deny('no project directory to scope writes to');
223
+ const { tempRoot } = getPaths(
224
+ resolveConfig({ cwd: projectDir, validate: false }),
225
+ );
226
+ checkWriteTarget(input.file_path ?? input.notebook_path, {
227
+ projectDir,
228
+ cwd: payload.cwd || projectDir,
229
+ tempRoot,
230
+ });
231
+ }
232
+
233
+ /** @returns {Promise<number>} */
234
+ async function main() {
235
+ const { values } = parseArgs({ options: { role: { type: 'string' } } });
236
+ const role = values.role ?? 'unknown-role';
237
+ let tool = 'unknown-tool';
238
+ try {
239
+ let payload;
240
+ try {
241
+ payload = JSON.parse(fs.readFileSync(0, 'utf8'));
242
+ } catch {
243
+ deny('stdin is not a JSON hook payload (fail closed)');
244
+ }
245
+ tool = payload?.tool_name ?? tool;
246
+ evaluate(payload);
247
+ return 0;
248
+ } catch (err) {
249
+ const rule = err instanceof Denied ? err.message : `guard error: ${err}`;
250
+ process.stderr.write(
251
+ `role-scope-guard: ${role} ${tool} denied — ${rule}\n`,
252
+ );
253
+ return 2;
254
+ }
255
+ }
256
+
257
+ runAsCli(import.meta.url, main, {
258
+ source: 'role-scope-guard',
259
+ propagateExitCode: true,
260
+ exitCode: 2,
261
+ usage: {
262
+ invocation: 'node .agents/scripts/role-scope-guard.js --role <role>',
263
+ summary:
264
+ 'PreToolUse hook: deny reviewer-role writes outside tempRoot and Bash mutation classes (exit 2).',
265
+ flags: [['--role <role>', 'The reviewer role named in a deny reason.']],
266
+ },
267
+ });
@@ -30,7 +30,7 @@
30
30
  * at (`telemetry.workerEffort`), rendered beside it when the Story resumed
31
31
  * after a prior block.
32
32
  * `--override-review-block <reason>` is the audited escape past a code-review
33
- * CRITICAL blocker (instead of a hand-merge with no record).
33
+ * CRITICAL blocker (instead of a hand-merge that records no override).
34
34
  * `--merge-watch-mode async` is passed per close by the orchestrator, the only
35
35
  * party that knows the run has N Stories and a foreground wait is dead time.
36
36
  *
@@ -47,7 +47,7 @@ import { parseSprintArgsTolerant } from './lib/cli-args.js';
47
47
  import { runAsCli } from './lib/cli-utils.js';
48
48
  import { formatCliError } from './lib/error-redactor.js';
49
49
  import { Logger } from './lib/Logger.js';
50
- import { emitCloseTerminalSignals } from './lib/observability/close-telemetry.js';
50
+ import { emitCloseCrashSignals } from './lib/observability/story-outcome.js';
51
51
  import { resolveRunScopedConfig } from './lib/orchestration/run-scoped-config.js';
52
52
  import {
53
53
  failedTerminalFor,
@@ -103,7 +103,7 @@ async function main() {
103
103
  // Mirrors runAsCli's default error line, which this catch pre-empts.
104
104
  Logger.error(`[single-story-close] Fatal error: ${formatCliError(err)}`);
105
105
  emitTerminalEnvelope(terminal);
106
- await emitCloseTerminalSignals({ envelope: terminal });
106
+ await emitCloseCrashSignals(terminal);
107
107
  return exitCodeForTerminal(terminal);
108
108
  }
109
109
  }
@@ -140,7 +140,7 @@ runAsCli(import.meta.url, main, {
140
140
  '--override-review-block <reason>',
141
141
  // Must not spell the merge CLI invocation: `check-lifecycle-lint.js`
142
142
  // forbids that literal outside `phases/auto-merge.js`.
143
- 'Land despite a Story-scope code-review CRITICAL blocker you have reviewed and judged wrong. The reason is mandatory (≥12 chars) and is recorded on the Story, on the PR, and as a `review-block-overridden` friction signal; the terminal envelope reports `gates.codeReview: "overridden"`. Use this instead of merging the PR by hand with the GitHub CLI — a hand-merge bypasses the gate with no record at all.',
143
+ 'Land despite a Story-scope code-review CRITICAL blocker you have reviewed and judged wrong. The reason is mandatory (≥12 chars) and is recorded on the Story, on the PR, and as a `review-block-overridden` friction signal; the terminal envelope reports `gates.codeReview: "overridden"`. Use this instead of merging the PR by hand with the GitHub CLI — a hand-merge bypasses the gate with no override record, and the land then records it as unreviewed or as a merged CRITICAL.',
144
144
  ],
145
145
  [
146
146
  '--worker-tokens <n>',
@@ -26,6 +26,7 @@ import { createGh } from './lib/gh-exec.js';
26
26
  import { getStoryBranch } from './lib/git-utils.js';
27
27
  import { Logger } from './lib/Logger.js';
28
28
  import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
29
+ import { recordStoryOutcome } from './lib/observability/story-outcome.js';
29
30
  import { emitTerseResult } from './lib/observability/terse-result.js';
30
31
  import { probeCloseArtifacts } from './lib/orchestration/deliver-recover.js';
31
32
  import { MERGED_FLIP_FAILED_BLOCK_CLASS } from './lib/orchestration/lifecycle/emit-merge-flip-failed.js';
@@ -138,7 +139,7 @@ export async function resolvePrNumber({ storyBranch, gh }) {
138
139
  * The friction emit is awaited because `runAsCli` exits via `process.exit`
139
140
  * as soon as `main` resolves.
140
141
  */
141
- async function logConfirmResult(result, terminal, config) {
142
+ async function logConfirmResult(result, terminal, { config, provider }) {
142
143
  emitTerseResult({
143
144
  label: 'CONFIRM MERGE RESULT',
144
145
  result,
@@ -152,6 +153,13 @@ async function logConfirmResult(result, terminal, config) {
152
153
  });
153
154
  emitTerminalEnvelope(terminal, { config });
154
155
  await emitTerminalFriction({ envelope: terminal, tool: CLI_SOURCE, config });
156
+ await recordStoryOutcome({
157
+ envelope: terminal,
158
+ result,
159
+ config,
160
+ provider,
161
+ tool: CLI_SOURCE,
162
+ });
155
163
  return { success: terminal.status !== 'failed', result, terminal };
156
164
  }
157
165
 
@@ -176,9 +184,19 @@ function confirmBlocked(blockClass, reason, nextCommand) {
176
184
  };
177
185
  }
178
186
 
187
+ /** A red CI ratchet on a deferred PR: blocked until an operator decides. */
188
+ function ratchetBlocked(storyId, { detail }) {
189
+ return confirmBlocked(
190
+ 'checks-failed',
191
+ detail,
192
+ NEXT_COMMANDS.confirmMerge(storyId),
193
+ );
194
+ }
195
+
179
196
  /**
180
197
  * done/noop → landed; flip-failed → blocked (re-run this command);
181
- * pr-not-merged → blocked (needs a human); otherwise pending.
198
+ * pr-not-merged → blocked (needs a human); a red CI ratchet → blocked
199
+ * (`checks-failed`); otherwise pending.
182
200
  */
183
201
  function confirmOutcomeFields({ storyId, confirmation, tail }) {
184
202
  if (confirmation.action === 'done' || confirmation.action === 'noop') {
@@ -196,6 +214,9 @@ function confirmOutcomeFields({ storyId, confirmation, tail }) {
196
214
  NEXT_COMMANDS.confirmMerge(storyId),
197
215
  );
198
216
  }
217
+ if (confirmation.action === 'blocked') {
218
+ return ratchetBlocked(storyId, confirmation);
219
+ }
199
220
  if (confirmation.reason === 'pr-not-merged') {
200
221
  return confirmBlocked(
201
222
  'api-race-other',
@@ -267,7 +288,7 @@ async function confirmWithoutPr(ctx) {
267
288
  tail: null,
268
289
  elapsedSeconds: elapsedSeconds(ctx),
269
290
  }),
270
- ctx.config,
291
+ ctx,
271
292
  );
272
293
  }
273
294
 
@@ -343,7 +364,7 @@ async function resumeMergeWait(ctx) {
343
364
  tail: waitOutcome.tail ?? null,
344
365
  },
345
366
  terminal,
346
- ctx.config,
367
+ ctx,
347
368
  );
348
369
  }
349
370
 
@@ -382,7 +403,7 @@ async function probeMergeOnce(ctx) {
382
403
  return await logConfirmResult(
383
404
  { ...confirmation, standalone: true, tail },
384
405
  terminal,
385
- config,
406
+ ctx,
386
407
  );
387
408
  }
388
409
 
@@ -464,6 +485,11 @@ async function failWithEnvelope(err, phase, fullArgv) {
464
485
  );
465
486
  emitTerminalEnvelope(terminal);
466
487
  await emitTerminalFriction({ envelope: terminal, tool: CLI_SOURCE });
488
+ await recordStoryOutcome({
489
+ envelope: terminal,
490
+ cwd: args.cwd,
491
+ tool: CLI_SOURCE,
492
+ });
467
493
  return exitCodeForTerminal(terminal);
468
494
  }
469
495