mandrel 2.93.0 → 2.95.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 (130) hide show
  1. package/.agents/docs/configuration.md +8 -3
  2. package/.agents/runtime-deps.json +6 -6
  3. package/.agents/schemas/lifecycle/merge.unlanded.schema.json +2 -1
  4. package/.agents/schemas/story-deliver-terminal.schema.json +1 -0
  5. package/.agents/scripts/agents-bootstrap-github.js +1 -1
  6. package/.agents/scripts/board-backfill.js +1 -1
  7. package/.agents/scripts/boot-sweep.js +1 -1
  8. package/.agents/scripts/check-arch-cycles.js +69 -41
  9. package/.agents/scripts/check-doc-links.js +5 -7
  10. package/.agents/scripts/check-gherkin-corpus.js +2 -11
  11. package/.agents/scripts/clean-temp.js +1 -1
  12. package/.agents/scripts/cleanup-repo-test-temp.js +1 -1
  13. package/.agents/scripts/diagnose-friction.js +1 -1
  14. package/.agents/scripts/generate-lens-checklists.js +4 -4
  15. package/.agents/scripts/generate-skills-index.js +3 -2
  16. package/.agents/scripts/generate-workflows-doc.js +2 -1
  17. package/.agents/scripts/lib/audit-baselines/read.js +2 -1
  18. package/.agents/scripts/lib/audit-exceptions/adapters/tool-config.js +13 -3
  19. package/.agents/scripts/lib/audit-exceptions/globs.js +12 -1
  20. package/.agents/scripts/lib/audit-exceptions/probe.js +24 -2
  21. package/.agents/scripts/lib/audit-exceptions/read.js +2 -2
  22. package/.agents/scripts/lib/audit-to-stories/group-findings.js +77 -67
  23. package/.agents/scripts/lib/baselines/components.js +21 -19
  24. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -8
  25. package/.agents/scripts/lib/baselines/kinds/maintainability.js +2 -3
  26. package/.agents/scripts/lib/baselines/preview-gates.js +2 -2
  27. package/.agents/scripts/lib/baselines/refresh-service.js +4 -7
  28. package/.agents/scripts/lib/baselines/writer.js +2 -7
  29. package/.agents/scripts/lib/bdd-runner-detect.js +2 -2
  30. package/.agents/scripts/lib/bdd-step-index.js +3 -7
  31. package/.agents/scripts/lib/bootstrap/baseline-merge-driver.js +11 -7
  32. package/.agents/scripts/lib/bootstrap/install-ledger.js +19 -4
  33. package/.agents/scripts/lib/bootstrap/json-io.js +14 -0
  34. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +20 -44
  35. package/.agents/scripts/lib/bootstrap/quality-bootstrap.js +38 -54
  36. package/.agents/scripts/lib/branch-name-guard.js +2 -3
  37. package/.agents/scripts/lib/claude/agents-projection.js +1 -12
  38. package/.agents/scripts/lib/codex/agents-projection.js +2 -5
  39. package/.agents/scripts/lib/codex/skills-projection.js +4 -12
  40. package/.agents/scripts/lib/config/defaults.js +2 -1
  41. package/.agents/scripts/lib/config/qa.js +4 -5
  42. package/.agents/scripts/lib/config-schema.js +1 -8
  43. package/.agents/scripts/lib/config-settings-schema.js +0 -3
  44. package/.agents/scripts/lib/coverage-baseline.js +2 -3
  45. package/.agents/scripts/lib/coverage-utils.js +2 -1
  46. package/.agents/scripts/lib/cpu-pool.js +0 -1
  47. package/.agents/scripts/lib/cyclomatic-scope.js +2 -1
  48. package/.agents/scripts/lib/doc-tiers.js +2 -1
  49. package/.agents/scripts/lib/duplicate-search.js +52 -18
  50. package/.agents/scripts/lib/feedback-loop/prior-feedback-fetcher.js +47 -20
  51. package/.agents/scripts/lib/gh-exec.js +115 -25
  52. package/.agents/scripts/lib/gh-pr-rest.js +371 -0
  53. package/.agents/scripts/lib/git/sync-from-base.js +1 -1
  54. package/.agents/scripts/lib/import-graph.js +13 -28
  55. package/.agents/scripts/lib/json-utils.js +11 -0
  56. package/.agents/scripts/lib/label-constants.js +7 -1
  57. package/.agents/scripts/lib/maintainability-utils.js +14 -22
  58. package/.agents/scripts/lib/observability/runtime-friction.js +37 -1
  59. package/.agents/scripts/lib/orchestration/board-graphql-latch.js +75 -0
  60. package/.agents/scripts/lib/orchestration/check-baselines/phases/parse-args.js +25 -1
  61. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +82 -41
  62. package/.agents/scripts/lib/orchestration/code-review.js +1 -6
  63. package/.agents/scripts/lib/orchestration/column-sync.js +23 -21
  64. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  65. package/.agents/scripts/lib/orchestration/git-cleanup/phases/fast-forward.js +7 -14
  66. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js +2 -21
  67. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +11 -20
  68. package/.agents/scripts/lib/orchestration/git-cleanup/phases/phase-drivers.js +65 -86
  69. package/.agents/scripts/lib/orchestration/git-cleanup/phases/prompts.js +2 -2
  70. package/.agents/scripts/lib/orchestration/git-cleanup/phases/stashes.js +15 -6
  71. package/.agents/scripts/lib/orchestration/lifecycle/emit-merge-unlanded.js +5 -2
  72. package/.agents/scripts/lib/orchestration/merge-block-class.js +48 -47
  73. package/.agents/scripts/lib/orchestration/merge-queue.js +49 -4
  74. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +20 -1
  75. package/.agents/scripts/lib/orchestration/project-meta-resolver.js +2 -2
  76. package/.agents/scripts/lib/orchestration/required-checks.js +72 -12
  77. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +2 -3
  78. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +4 -2
  79. package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js +132 -58
  80. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +92 -9
  81. package/.agents/scripts/lib/orchestration/single-story-close/phases/graphql-preflight.js +41 -18
  82. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -2
  83. package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +3 -3
  84. package/.agents/scripts/lib/orchestration/story-handoff.js +18 -5
  85. package/.agents/scripts/lib/orchestration/ticketing/transition.js +18 -22
  86. package/.agents/scripts/lib/runtime-deps/dep-resolution.js +19 -5
  87. package/.agents/scripts/lib/runtime-deps/scan-imports.js +4 -10
  88. package/.agents/scripts/lib/skills/parse-skill.js +2 -2
  89. package/.agents/scripts/lib/skills/walk-skill-files.js +7 -23
  90. package/.agents/scripts/lib/story-body/story-body.js +4 -14
  91. package/.agents/scripts/lib/util/atomic-write.js +14 -3
  92. package/.agents/scripts/lib/util/regex.js +4 -0
  93. package/.agents/scripts/notify.js +1 -1
  94. package/.agents/scripts/plan-context.js +1 -1
  95. package/.agents/scripts/plan-critics.js +3 -11
  96. package/.agents/scripts/providers/github/auth.js +0 -4
  97. package/.agents/scripts/providers/github/board-add.js +3 -3
  98. package/.agents/scripts/providers/github/compose.js +2 -0
  99. package/.agents/scripts/providers/github/errors.js +41 -0
  100. package/.agents/scripts/providers/github/project-board.js +0 -1
  101. package/.agents/scripts/providers/github/sub-issues-rest.js +55 -0
  102. package/.agents/scripts/providers/github/sub-issues.js +9 -1
  103. package/.agents/scripts/providers/github/tickets.js +0 -2
  104. package/.agents/scripts/resync-status-column.js +1 -1
  105. package/.agents/scripts/run-tests.js +1 -1
  106. package/.agents/scripts/single-story-confirm-merge.js +2 -0
  107. package/.agents/scripts/test-wrapper.js +1 -1
  108. package/.agents/scripts/update-ticket-state.js +4 -3
  109. package/.agents/scripts/validate-skills.js +2 -1
  110. package/.agents/skills/core/gates-and-baselines/reference.md +1 -0
  111. package/.agents/workflows/audit-baselines.md +21 -9
  112. package/.agents/workflows/clean-git.md +1 -1
  113. package/.agents/workflows/helpers/audit-lens-core.md +1 -1
  114. package/.agents/workflows/helpers/code-quality-guardrails.md +3 -3
  115. package/README.md +1 -1
  116. package/docs/CHANGELOG.md +46 -0
  117. package/lib/cli/claude-code-version.js +13 -7
  118. package/lib/cli/doctor-checks/llm-review.js +12 -5
  119. package/lib/cli/doctor-checks/merge-driver.js +10 -6
  120. package/lib/cli/doctor-checks/project-access.js +21 -8
  121. package/lib/cli/doctor-checks/read-json.js +2 -15
  122. package/lib/cli/doctor-checks/spawn.js +29 -9
  123. package/lib/cli/doctor-checks/test-credit-path.js +2 -1
  124. package/lib/cli/doctor-checks/toolchain.js +16 -12
  125. package/lib/cli/doctor.js +31 -8
  126. package/lib/cli/registry.js +7 -10
  127. package/lib/cli/sync.js +46 -10
  128. package/lib/cli/uninstall.js +259 -175
  129. package/lib/cli/update.js +3 -3
  130. package/package.json +23 -20
@@ -3,17 +3,28 @@ import path from 'node:path';
3
3
 
4
4
  /**
5
5
  * Tmp-then-rename via a pid-scoped sibling; reaps the tmp and rethrows on
6
- * failure.
6
+ * failure. A string is written as UTF-8; a Buffer is written byte-for-byte.
7
7
  *
8
8
  * @param {string} target
9
- * @param {string} contents
9
+ * @param {string | Buffer} contents
10
10
  * @param {{ fsImpl?: typeof fs }} [opts]
11
11
  */
12
12
  export function writeFileAtomic(target, contents, { fsImpl = fs } = {}) {
13
+ replaceAtomic(target, fsImpl, (tmp) =>
14
+ fsImpl.writeFileSync(tmp, contents, 'utf8'),
15
+ );
16
+ }
17
+
18
+ /** {@link writeFileAtomic} for a copy; keeps `source`'s mode bits. */
19
+ export function copyFileAtomic(source, target, { fsImpl = fs } = {}) {
20
+ replaceAtomic(target, fsImpl, (tmp) => fsImpl.copyFileSync(source, tmp));
21
+ }
22
+
23
+ function replaceAtomic(target, fsImpl, fill) {
13
24
  const tmp = `${target}.${process.pid}.tmp`;
14
25
  try {
15
26
  fsImpl.mkdirSync(path.dirname(target), { recursive: true });
16
- fsImpl.writeFileSync(tmp, contents, 'utf8');
27
+ fill(tmp);
17
28
  fsImpl.renameSync(tmp, target);
18
29
  } catch (err) {
19
30
  reapTmp(fsImpl, tmp);
@@ -0,0 +1,4 @@
1
+ /** Escape every RegExp metacharacter in `text` so it matches literally. */
2
+ export function escapeRegExp(text) {
3
+ return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
4
+ }
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- /* node:coverage ignore file */
2
+ /* node:coverage ignore file -- live comment/webhook CLI */
3
3
 
4
4
  /**
5
5
  * notify.js — dispatch a notification to two independently gated channels:
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- /* node:coverage ignore file */
2
+ /* node:coverage ignore file -- CLI shell over tested libs */
3
3
 
4
4
  /**
5
5
  * plan-context.js — build the `/mandrel-plan` authoring-context envelope from
@@ -16,6 +16,7 @@ import { parseArgs } from 'node:util';
16
16
 
17
17
  import { runAsCli } from './lib/cli-utils.js';
18
18
  import { resolveConfig } from './lib/config-resolver.js';
19
+ import { readJsonOrNull } from './lib/json-utils.js';
19
20
  import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
20
21
  import { evaluatePlanCritics } from './lib/orchestration/plan-critics-evaluate.js';
21
22
  import { appendCriticSkip } from './lib/orchestration/plan-metrics.js';
@@ -46,15 +47,6 @@ function collectPackageIdentity(names, pkg) {
46
47
  }
47
48
  }
48
49
 
49
- /** Best-effort JSON read: a missing or malformed file yields `null`. */
50
- async function readJsonIfPresent(filePath) {
51
- try {
52
- return JSON.parse(await readFile(filePath, 'utf8'));
53
- } catch {
54
- return null;
55
- }
56
- }
57
-
58
50
  function workspacePatterns(pkg) {
59
51
  const ws = pkg?.workspaces;
60
52
  if (Array.isArray(ws)) return ws;
@@ -102,7 +94,7 @@ async function resolveWorkspaceManifestPaths(rootDir, patterns) {
102
94
  * @returns {Promise<string[]>}
103
95
  */
104
96
  export async function collectRepoPackages({ rootDir = process.cwd() } = {}) {
105
- const root = await readJsonIfPresent(path.join(rootDir, 'package.json'));
97
+ const root = readJsonOrNull(path.join(rootDir, 'package.json'));
106
98
  if (!root) return [];
107
99
  const names = new Set();
108
100
  collectPackageIdentity(names, root);
@@ -111,7 +103,7 @@ export async function collectRepoPackages({ rootDir = process.cwd() } = {}) {
111
103
  workspacePatterns(root),
112
104
  );
113
105
  for (const wsPath of wsPaths) {
114
- const pkg = await readJsonIfPresent(wsPath);
106
+ const pkg = readJsonOrNull(wsPath);
115
107
  if (pkg) collectPackageIdentity(names, pkg);
116
108
  }
117
109
  return [...names];
@@ -17,23 +17,19 @@ export function __setExecSyncForTests(fn) {
17
17
  execSyncHolder.impl = fn ?? defaultExecSync;
18
18
  }
19
19
 
20
- /* node:coverage ignore next */
21
20
  export function readGhCliToken() {
22
21
  return runGhAuthToken(execSyncHolder.impl);
23
22
  }
24
23
 
25
- /* node:coverage ignore next */
26
24
  function readEnvToken() {
27
25
  return process.env.GITHUB_TOKEN || process.env.GH_TOKEN || null;
28
26
  }
29
27
 
30
- /* node:coverage ignore next */
31
28
  function memoizeEnvToken(token) {
32
29
  process.env.GITHUB_TOKEN = token;
33
30
  process.env[TOKEN_SOURCE_ENV] = 'gh-cli';
34
31
  }
35
32
 
36
- /* node:coverage ignore next */
37
33
  export function resolveToken() {
38
34
  const envToken = readEnvToken();
39
35
  if (envToken) return envToken;
@@ -4,11 +4,11 @@
4
4
  * be enabled via API. Never throws (issue creation survives a board failure)
5
5
  * and is idempotent (the mutation returns an existing item). A token without
6
6
  * the `project` scope reports `reason: 'insufficient-scope'` and trips the
7
- * warn-once latch rather than warning per issue.
7
+ * warn-once latch rather than warning per issue (`graphql-blocked` likewise).
8
8
  */
9
9
 
10
10
  import { Logger } from '../../lib/Logger.js';
11
- import { boardScopeFailure } from '../../lib/orchestration/board-access-latch.js';
11
+ import { boardAccessFailure } from '../../lib/orchestration/board-graphql-latch.js';
12
12
 
13
13
  /**
14
14
  * No project number → no-op without network.
@@ -38,7 +38,7 @@ export async function addIssueToBoard({
38
38
  await addItemToProject(nodeId);
39
39
  return { added: true };
40
40
  } catch (err) {
41
- const scopeFailure = boardScopeFailure(err);
41
+ const scopeFailure = boardAccessFailure(err);
42
42
  if (scopeFailure) return { added: false, ...scopeFailure };
43
43
  warnAddFailure(err, issueNumber, nodeId);
44
44
  return { added: false, reason: 'error' };
@@ -12,6 +12,7 @@ import { MergeMethodsGateway } from './merge-methods.js';
12
12
  import { ProjectBoardGateway } from './project-board.js';
13
13
  import * as projects from './projects-v2-graphql.js';
14
14
  import { SubIssueGateway } from './sub-issues.js';
15
+ import { createSubIssueRestFallback } from './sub-issues-rest.js';
15
16
  import { TicketGateway } from './tickets.js';
16
17
 
17
18
  /** Mutates `provider` in place. */
@@ -33,6 +34,7 @@ export function composeGateways(provider) {
33
34
  ghGraphql: (q, v, o) => p.graphql(q, v, o),
34
35
  cache: p._cache,
35
36
  classifyGithubError,
37
+ restFallback: createSubIssueRestFallback({ ...ghDeps, cache: p._cache }),
36
38
  });
37
39
  p.comments = new CommentGateway({
38
40
  ...ghDeps,
@@ -147,6 +147,47 @@ export function classifyGithubError(err) {
147
147
  return 'permanent';
148
148
  }
149
149
 
150
+ // The cloud proxy's own wording, so an ordinary 403 never matches.
151
+ const GRAPHQL_BLOCKED_RE =
152
+ /GitHub GraphQL is not available from Claude Code sessions/i;
153
+ const PROXY_SCOPE_REFUSAL_RE =
154
+ /is not enabled for this session|sessions are bound to their configured repositories/i;
155
+
156
+ const CAUSE_DEPTH = 3;
157
+
158
+ /**
159
+ * @param {unknown} err
160
+ * @returns {string}
161
+ */
162
+ function failureText(err) {
163
+ const parts = [];
164
+ let cur = err;
165
+ for (let depth = 0; cur && depth < CAUSE_DEPTH; depth++) {
166
+ parts.push(
167
+ stderrText(cur),
168
+ typeof cur.message === 'string' ? cur.message : '',
169
+ );
170
+ cur = cur.cause;
171
+ }
172
+ return parts.join(' ');
173
+ }
174
+
175
+ /**
176
+ * @param {unknown} err
177
+ * @returns {boolean}
178
+ */
179
+ export function isGraphqlBlocked(err) {
180
+ return GRAPHQL_BLOCKED_RE.test(failureText(err));
181
+ }
182
+
183
+ /**
184
+ * @param {unknown} err
185
+ * @returns {boolean}
186
+ */
187
+ export function isProxyScopeRefusal(err) {
188
+ return PROXY_SCOPE_REFUSAL_RE.test(failureText(err));
189
+ }
190
+
150
191
  export const TRANSIENT_RETRY_DEFAULTS = Object.freeze({
151
192
  maxAttempts: 6,
152
193
  baseDelayMs: 500,
@@ -21,7 +21,6 @@ export class ProjectBoardGateway {
21
21
  return projects.ensureStatusField(this._ctx, optionNames);
22
22
  }
23
23
 
24
- /* node:coverage ignore next */
25
24
  async ensureProjectFields(fieldDefs) {
26
25
  return projects.ensureProjectFields(this._ctx, fieldDefs);
27
26
  }
@@ -0,0 +1,55 @@
1
+ /** GitHub Provider — REST sub-issues once a session's proxy refuses GraphQL. */
2
+
3
+ import { Logger } from '../../lib/Logger.js';
4
+ import { isGraphqlBlocked } from './errors.js';
5
+ import { issueToTicket } from './mappers.js';
6
+ import { paginateRest } from './request-helpers.js';
7
+
8
+ const PAGE_CAP = 50;
9
+ const PAGE_SIZE = 100;
10
+
11
+ const PROCESS_LATCH = { blocked: false };
12
+
13
+ /**
14
+ * @typedef {{
15
+ * latched: (parentId: number) => Promise<number[]> | null,
16
+ * onError: (err: unknown, parentId: number) => Promise<number[]> | null,
17
+ * }} SubIssueRestFallback
18
+ */
19
+
20
+ /**
21
+ * @param {{ gh: object, owner: string, repo: string, cache?: object }} deps
22
+ * @param {{ blocked: boolean }} [latch]
23
+ * @returns {SubIssueRestFallback}
24
+ */
25
+ export function createSubIssueRestFallback(deps, latch = PROCESS_LATCH) {
26
+ const list = (parentId) => listSubIssuesViaRest({ ...deps, parentId });
27
+ return {
28
+ latched: (parentId) => (latch.blocked ? list(parentId) : null),
29
+ onError(err, parentId) {
30
+ if (!isGraphqlBlocked(err)) return null;
31
+ if (!latch.blocked) {
32
+ Logger.warn(
33
+ '[GitHubProvider] GitHub GraphQL is refused in this session (Claude Code cloud proxy); ' +
34
+ 'reading sub-issues over REST for the rest of the run',
35
+ );
36
+ }
37
+ latch.blocked = true;
38
+ return list(parentId);
39
+ },
40
+ };
41
+ }
42
+
43
+ async function listSubIssuesViaRest({ gh, owner, repo, parentId, cache }) {
44
+ const rows = await paginateRest(
45
+ gh,
46
+ `/repos/${owner}/${repo}/issues/${parentId}/sub_issues`,
47
+ {
48
+ pageCap: PAGE_CAP,
49
+ perPage: PAGE_SIZE,
50
+ label: `getNativeSubIssues(rest) parent=#${parentId}`,
51
+ },
52
+ );
53
+ for (const row of rows) cache?.primeIfAbsent?.(issueToTicket(row));
54
+ return rows.map((row) => row.number);
55
+ }
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * GitHub Provider — SubIssueGateway: the read side of native Sub-Issues (the
3
3
  * GraphQL `subIssues` field, paginated into child numbers). Holds no
4
- * transport state; every call goes through the parent's `ghGraphql` hook.
4
+ * transport state; every call goes through the parent's `ghGraphql` hook
5
+ * (or `restFallback` once GraphQL is refused).
5
6
  */
6
7
 
7
8
  import { describeGhFailure } from '../../lib/gh-exec.js';
@@ -23,20 +24,25 @@ export class SubIssueGateway {
23
24
  * ghGraphql: (query: string, variables?: object, opts?: object) => Promise<object>,
24
25
  * cache?: { primeIfAbsent: (ticket: object) => void },
25
26
  * classifyGithubError?: (err: unknown) => string,
27
+ * restFallback?: object | null,
26
28
  * }} deps
27
29
  */
28
30
  constructor({
29
31
  ghGraphql,
30
32
  cache,
31
33
  classifyGithubError = defaultClassifyGithubError,
34
+ restFallback = null,
32
35
  } = {}) {
33
36
  this._ghGraphql = ghGraphql;
37
+ this._restFallback = restFallback;
34
38
  this._cache = cache;
35
39
  this._classify = classifyGithubError;
36
40
  }
37
41
 
38
42
  /** Primes the ticket cache; `[]` when the feature is disabled. */
39
43
  async getNativeSubIssues(parentNodeId, parentId) {
44
+ const latched = this._restFallback?.latched(parentId);
45
+ if (latched) return latched;
40
46
  const childIds = [];
41
47
  let cursor = null;
42
48
  try {
@@ -72,6 +78,8 @@ export class SubIssueGateway {
72
78
  }
73
79
  }
74
80
  } catch (err) {
81
+ const rest = this._restFallback?.onError(err, parentId);
82
+ if (rest) return rest;
75
83
  const category = this._classify(err);
76
84
  if (category === 'feature-disabled') {
77
85
  Logger.warn(
@@ -180,7 +180,6 @@ export class TicketGateway {
180
180
  return tickets;
181
181
  }
182
182
 
183
- /* node:coverage ignore next */
184
183
  async getTicketDependencies(ticketId) {
185
184
  const ticket = await this.getTicket(ticketId);
186
185
  return {
@@ -363,7 +362,6 @@ export class TicketGateway {
363
362
  * @field-manifest PATCH /repos/{owner}/{repo}/issues/{n}:
364
363
  * title, body, assignees, state, state_reason, labels
365
364
  */
366
- /* node:coverage ignore next */
367
365
  async updateTicket(ticketId, mutations) {
368
366
  await this._addAssignees(ticketId, mutations.addAssignees);
369
367
  const patch = {};
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- /* node:coverage ignore file */
2
+ /* node:coverage ignore file -- CLI entrypoint convention, see docs/decisions.md */
3
3
 
4
4
  /**
5
5
  * resync-status-column.js — re-assert a ticket's Projects v2 Status after
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- /* node:coverage ignore file */
2
+ /* node:coverage ignore file -- the suite driver itself */
3
3
 
4
4
  /**
5
5
  * Cross-platform driver for `npm test`. Cleanup runs in-process so reserved
@@ -303,6 +303,8 @@ async function resumeMergeWait(ctx) {
303
303
  cwd: ctx.cwd,
304
304
  resolveWorktree: lazyWaitWorktree(ctx),
305
305
  closeArmed: evidence.armed,
306
+ // `rest-merge-on-green` tells the wait it owns the merge.
307
+ autoMergeReason: evidence.reason,
306
308
  storyId,
307
309
  storyBranch,
308
310
  baseBranch,
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- /* node:coverage ignore file */
2
+ /* node:coverage ignore file -- pretest shell over tested runPreflight */
3
3
 
4
4
  /**
5
5
  * `pretest` preflight: runs the self-healing checks (scope `npm-test`) so the
@@ -56,15 +56,16 @@ function parseTicketStateArgs(argv) {
56
56
  }
57
57
 
58
58
  /**
59
- * @param {{ argv?: string[], provider?: object, transition?: typeof transitionTicketState }} [opts]
59
+ * @param {{ argv?: string[], provider?: object, transition?: typeof transitionTicketState, config?: object }} [opts]
60
60
  */
61
61
  export async function runUpdateTicketState({
62
62
  argv = process.argv.slice(2),
63
63
  provider,
64
64
  transition = transitionTicketState,
65
+ config = resolveConfig(),
65
66
  } = {}) {
66
67
  const { ticketId, state, removeLabel } = parseTicketStateArgs(argv);
67
- const ticketing = provider ?? createProvider(resolveConfig());
68
+ const ticketing = provider ?? createProvider(config);
68
69
 
69
70
  // Label-only mutation path — no state transition. Callers that just
70
71
  // need to drop a single label without flipping the agent::* state.
@@ -81,7 +82,7 @@ export async function runUpdateTicketState({
81
82
 
82
83
  Logger.info(`[State-Sync] Transitioning ticket #${ticketId} to ${state}...`);
83
84
  // No explicit cascade: `transitionTicketState` already runs it.
84
- await transition(ticketing, ticketId, state);
85
+ await transition(ticketing, ticketId, state, { config });
85
86
 
86
87
  // Optional secondary label removal alongside the state transition
87
88
  // (e.g. clear `status::blocked` when transitioning back to ready).
@@ -27,6 +27,7 @@ import {
27
27
  PAYLOAD_SKILLS_SEGMENTS,
28
28
  } from './lib/skills/walk-skill-files.js';
29
29
  import { createAjv } from './lib/util/ajv.js';
30
+ import { toPosix } from './lib/util/paths.js';
30
31
 
31
32
  const MIN_CAPSULE_BULLETS = 5;
32
33
  const MAX_CAPSULE_BULLETS = 12;
@@ -156,7 +157,7 @@ function validateOne(absPath, repoRoot, validateFrontmatter, indexPaths) {
156
157
  }
157
158
 
158
159
  function rel(absPath, repoRoot) {
159
- return path.relative(repoRoot, absPath).split(path.sep).join('/');
160
+ return toPosix(path.relative(repoRoot, absPath));
160
161
  }
161
162
 
162
163
  /**
@@ -42,6 +42,7 @@ flagged a signed-off API-surface change. If the underlying change is an
42
42
  | Duplication | `npm run duplication:update` | `npm run duplication:reanchor` |
43
43
  | Dead-exports | `npm run dead-exports:update` (regenerates both passes; never hand-edit the JSON) | same — no scope flag applies |
44
44
  | Cyclomatic | `npm run cyclomatic:update` | same — no scope flag applies |
45
+ | Arch cycles | `npm run arch:update` | same — no scope flag applies |
45
46
  | Context budget | `node .agents/scripts/check-context-budget.js --update` | same — no scope flag applies |
46
47
 
47
48
  ## Procedure
@@ -219,19 +219,31 @@ runs and the ratchet never moves. So **every Hotspot Cluster and Tightening
219
219
  Headroom finding's Recommendation MUST** end the remediation with the ratchet
220
220
  tightened and gate-enforced:
221
221
 
222
- 1. Lower the floor under `delivery.quality.gates` in `.agentrc.json` to the
223
- newly measured level, **or** delete the burnt-down rows from that kind's
224
- file under `baselines/`.
225
- 2. Carry `node .agents/scripts/check-baselines.js --gate <kind>` in the
226
- remediation Story's `verify[]`, so the tightened floor is enforced by the
227
- gate that already exists at that Story's delivery time rather than by prose
228
- nobody runs.
222
+ 1. For a `gate` kind (its `surface` in `gateSurface[]`), lower the floor
223
+ under `delivery.quality.gates` in `.agentrc.json` to the newly measured
224
+ level, **or** delete the burnt-down rows from that kind's file under
225
+ `baselines/`. A `ratchet` kind has no floor: its shrunken baseline is the
226
+ tightening, banked at close (`arch-cycles` alone needs its checker's
227
+ `--update`).
228
+ 2. Carry each kind's checker in the remediation Story's `verify[]`, so the
229
+ tightened ratchet is enforced by the gate that already exists at that
230
+ Story's delivery time rather than by prose nobody runs. A `gate` kind uses
231
+ `node .agents/scripts/check-baselines.js --gate <kind>`; that command
232
+ rejects a `ratchet` kind with exit 3, so a ratchet uses its own checker:
233
+
234
+ | Ratchet kind | Checker |
235
+ | --- | --- |
236
+ | `arch-cycles` | `node .agents/scripts/check-arch-cycles.js` |
237
+ | `context-budget` | `node .agents/scripts/check-context-budget.js` |
238
+ | `cyclomatic` | `node .agents/scripts/check-cyclomatic.js` |
239
+ | `dead-exports` | `node .agents/scripts/check-dead-exports.js` |
240
+ | `dead-exports-production` | `node .agents/scripts/check-dead-exports.js --production` |
229
241
 
230
242
  Use these two Recommendation templates verbatim, substituting the envelope's own
231
- values for the angle-bracketed slots:
243
+ values for the angle-bracketed slots (`<checker>` is item 2's command per kind):
232
244
 
233
245
  - **Hotspot Cluster template:**
234
- `Burn down the measured debt in <hotspots.path>, an outlier across <gateKinds>. Refactor and add tests until its rows leave that kind's file under baselines/, then regenerate that baseline with the matching update-*-baseline script in a commit whose subject carries the baseline-refresh: tag. Finish by TIGHTENING the ratchet in the same Story — lower the kind's floor under delivery.quality.gates in .agentrc.json to the new measured level, or delete the burnt-down rows — and carry node .agents/scripts/check-baselines.js --gate <kind> in this Story's verify[] so the tightened floor is enforced at delivery.`
246
+ `Burn down the measured debt in <hotspots.path>, an outlier across <gateKinds>. Refactor and add tests until its rows leave each kind's file under baselines/, then regenerate a gate kind's baseline with the matching update-*-baseline script in a commit whose subject carries the baseline-refresh: tag. Finish by TIGHTENING the ratchet in the same Story — lower each gate kind's floor under delivery.quality.gates in .agentrc.json to the new measured level, or delete the burnt-down rows — and carry each kind's <checker> in this Story's verify[] so the tightened ratchet is enforced at delivery.`
235
247
  - **Tightening Headroom template:**
236
248
  `The <kind> gate's <axis> floor sits at <floor> while the measured rollup is <measured> (headroom <headroom>, direction <direction>), and that kind's trend is flat or improving. Tighten it: set that axis under delivery.quality.gates in .agentrc.json to the measured level so no slack remains for the next change to re-spend, and carry node .agents/scripts/check-baselines.js --gate <kind> in this Story's verify[] so the new floor is enforced. Regenerate no baseline in this Story — the floor edit is the whole change.`
237
249
 
@@ -34,7 +34,7 @@ flags: `node .agents/scripts/clean-git.js --help`.
34
34
 
35
35
  | Phase | What it does | Safety contract |
36
36
  | --- | --- | --- |
37
- | **fast-forward-main** | `git fetch origin <base>` then `git merge --ff-only origin/<base>`. | Skipped silently on a dirty tree or a non-fast-forward; otherwise prompts `Fast-forward main by N commit(s)?`. Checks out `<base>` first when HEAD is elsewhere and does **not** restore the prior branch. |
37
+ | **fast-forward-main** | `git fetch origin <base>` then `git merge --ff-only origin/<base>`. | Skipped silently on a dirty tree or a non-fast-forward; otherwise prompts `Fast-forward main by N commit(s)?`. Checks out `<base>` first when HEAD is elsewhere, then restores the prior branch after the merge, even a failed one (best-effort: a failed restore warns and leaves HEAD on `<base>`). |
38
38
  | **prune-remotes** | `git fetch --prune origin` to drop `refs/remotes/origin/*` GitHub already deleted. | Prompts before pruning. Runs as its own phase regardless of `--remote`. |
39
39
  | **branches** | Reaps merged local branches (squash-aware: merged-PR, git-ancestry, and content-equivalence signals), removing an attached worktree first. Also enumerates **remote-only** merged branches. | Prints the candidate list, then prompts `Reap N merged branch(es)?`. `--remote` is required **on top of** `--execute` to delete any `origin/<branch>`. `content-merged` candidates carry a weaker-signal warning, and under `--yes` their **remote** ref is withheld unless `--include-content-merged` is passed (their local ref still goes — it is recoverable from the remote). |
40
40
  | **stashes** | Lists every stash and triages it. | Interactive: `drop / keep / quit` per entry (default `keep`). Under `--yes` / `--json`, drops require an explicit `--drop-stashes <ref>` allowlist (repeatable) — there is no "drop all". |
@@ -27,7 +27,7 @@ refines this shared constraint for that lens only.
27
27
 
28
28
  **Deliberate shortcuts are decisions.** In every lens, a `shortcut:` comment
29
29
  that names a ceiling and a trigger
30
- ([convention](code-quality-guardrails.md#deliberate-shortcuts)) is a decision,
30
+ (convention: `code-quality-guardrails.md` § Deliberate shortcuts) is a decision,
31
31
  not a finding, unless the lens can show the ceiling is already crossed at the
32
32
  expected load. A marker with no trigger, or one whose trigger has fired, is
33
33
  `/audit-exceptions`' finding, not the reading lens's.
@@ -13,7 +13,7 @@ read the same numbers from here so a "high cyclomatic complexity" finding in
13
13
 
14
14
  ## At-keyboard verification
15
15
 
16
- Run [`npm run quality:preview`](../../../package.json) before committing
16
+ Run `npm run quality:preview` before committing
17
17
  on any Story that touches production source. The preview runs
18
18
  `quality-preview.js`, which scopes the diff to `HEAD` by default (the
19
19
  alias passes no `--changed-since`; the script defaults to `HEAD`) and
@@ -63,7 +63,7 @@ No structural check enforces the pairing — it is a review-time rule
63
63
  ## Maintainability-Index drop refactor rule
64
64
 
65
65
  Per-file Maintainability Index (MI) is tracked in
66
- [`baselines/maintainability.json`](../../../baselines/maintainability.json).
66
+ `baselines/maintainability.json`.
67
67
  A commit that drops a file's MI by more than the configured
68
68
  `delivery.quality.gates.maintainability.tolerance` (default `0.5` points)
69
69
  requires a refactor in the same Story — not a baseline bump. `tolerance` is
@@ -108,7 +108,7 @@ Every judging surface reads the marker the same way:
108
108
  - **Rot**: a ceiling with no trigger. Nothing will ever say when to fix it.
109
109
  - **Fired**: the date has passed or the issue has closed. Fix it now.
110
110
 
111
- [`/audit-exceptions`](../audit-exceptions.md) lists every marker with its
111
+ `/audit-exceptions` lists every marker with its
112
112
  verdict.
113
113
 
114
114
  ## When a number changes
package/README.md CHANGED
@@ -90,7 +90,7 @@ separate, planned pass.
90
90
 
91
91
  | Area | Lenses |
92
92
  | ---- | ------ |
93
- | Code & design | `architecture`, `clean-code`, `adrs`, `data-model`, `documentation`, `exceptions` |
93
+ | Code & design | `architecture`, `clean-code`, `adrs`, `data-model`, `documentation`, `exceptions`, `lean` |
94
94
  | Quality & ops | `quality`, `baselines`, `performance`, `devops`, `sre`, `dependencies` |
95
95
  | Security & privacy | `security`, `privacy` |
96
96
  | Product & UX | `ux-ui`, `accessibility`, `mobile`, `navigability`, `seo` |
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,52 @@ 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.95.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.94.0...mandrel-v2.95.0) (2026-10-21)
19
+
20
+
21
+ ### Added
22
+
23
+ * observe invalid agent:: state transitions instead of leaving the transition table unwired ([#5805](https://github.com/dsj1984/mandrel/issues/5805)) ([#5821](https://github.com/dsj1984/mandrel/issues/5821)) ([68bb4c1](https://github.com/dsj1984/mandrel/commit/68bb4c122c99f96bcb70b0b10a1d40ca1f72885f))
24
+ * tighten the quality floors after the burn-down, refresh stale baselines, and stop check-baselines ignoring unknown gate kinds ([#5817](https://github.com/dsj1984/mandrel/issues/5817)) ([#5833](https://github.com/dsj1984/mandrel/issues/5833)) ([37705a7](https://github.com/dsj1984/mandrel/commit/37705a7ac6a44a1d1df080273c708b958d532246))
25
+
26
+
27
+ ### Fixed
28
+
29
+ * address the post-v2.94.0 review: accept js-yaml 4 at consumer roots, observe every agent:: transition, and close error-path regressions ([#5836](https://github.com/dsj1984/mandrel/issues/5836)) ([5e0c216](https://github.com/dsj1984/mandrel/commit/5e0c216e7b79b084427b20f565db59eada73ec12))
30
+ * clear the dev-only npm advisories and refresh dependencies: markdownlint-cli2 0.24 with js-yaml 5, jscpd 4.3, minor batch, c8 12, chokidar 6 ([#5815](https://github.com/dsj1984/mandrel/issues/5815)) ([#5831](https://github.com/dsj1984/mandrel/issues/5831)) ([aba9345](https://github.com/dsj1984/mandrel/commit/aba93456869d150f256bbb1694de1fc9db1d326e))
31
+ * **deps:** clear the markdown-it GHSA-gfr2-rv44-r23c advisory (refs [#5799](https://github.com/dsj1984/mandrel/issues/5799)) ([#5800](https://github.com/dsj1984/mandrel/issues/5800)) ([9f5ccd1](https://github.com/dsj1984/mandrel/commit/9f5ccd1d31977fcb19bc630ff8d769d37e7f2baa))
32
+ * fix [#5804](https://github.com/dsj1984/mandrel/issues/5804): gh-exec.js ends child.stdin with no 'error' listener, so a g… ([#5819](https://github.com/dsj1984/mandrel/issues/5819)) ([#5820](https://github.com/dsj1984/mandrel/issues/5820)) ([86a1ffb](https://github.com/dsj1984/mandrel/commit/86a1ffb9f9a95775ae1e7b25ad00fdd006871ed0))
33
+ * justify or remove the dead and unexplained exceptions: GitHub auth coverage ignores, knip/biome/prettier exemptions, eslint comments ([#5812](https://github.com/dsj1984/mandrel/issues/5812)) ([#5828](https://github.com/dsj1984/mandrel/issues/5828)) ([66213b9](https://github.com/dsj1984/mandrel/commit/66213b98f6e4ae8a79978926cc5a3691c8c779de))
34
+ * plan-persist --dry-run prints 'Rewrote #&lt;id&gt; in place; it is agent::rea… ([#5802](https://github.com/dsj1984/mandrel/issues/5802)) ([#5803](https://github.com/dsj1984/mandrel/issues/5803)) ([d39f797](https://github.com/dsj1984/mandrel/commit/d39f7970198f7a6487c53d53638ba58487e7a085))
35
+ * stop interactive /clean-git from dropping every stash: await the stash decision and drop only on an explicit 'drop' ([#5834](https://github.com/dsj1984/mandrel/issues/5834)) ([#5835](https://github.com/dsj1984/mandrel/issues/5835)) ([9c8c890](https://github.com/dsj1984/mandrel/commit/9c8c8909d31feb9ea684e9378969c5c67fc568d6))
36
+ * write sync output and orchestration state files atomically, and make mandrel sync skip unchanged files ([#5813](https://github.com/dsj1984/mandrel/issues/5813)) ([#5829](https://github.com/dsj1984/mandrel/issues/5829)) ([9760a2f](https://github.com/dsj1984/mandrel/commit/9760a2f056351a9c078a98d15e2d822160b8acd8))
37
+
38
+
39
+ ### Performance
40
+
41
+ * run mandrel doctor checks concurrently, dedupe claude --version, and probe the user rung first for user-owned boards ([#5814](https://github.com/dsj1984/mandrel/issues/5814)) ([#5830](https://github.com/dsj1984/mandrel/issues/5830)) ([a699bc0](https://github.com/dsj1984/mandrel/commit/a699bc001c10067deef5ee5ae275a5113688daaf))
42
+
43
+
44
+ ### Changed
45
+
46
+ * adopt the shared helpers the tree re-implements: toPosix, walkFiles, isObject, parseGateArgv, escapeRegExp ([#5816](https://github.com/dsj1984/mandrel/issues/5816)) ([#5832](https://github.com/dsj1984/mandrel/issues/5832)) ([ae332d3](https://github.com/dsj1984/mandrel/commit/ae332d364f2c53c46be7b4037a7e57beb3e8747b))
47
+ * burn down the bootstrap hotspots and collapse their duplicated JSON readers ([#5807](https://github.com/dsj1984/mandrel/issues/5807)) ([#5825](https://github.com/dsj1984/mandrel/issues/5825)) ([f07f470](https://github.com/dsj1984/mandrel/commit/f07f470862aaf131b5f5e0b8e924418225f12074))
48
+ * burn down the lib/cli/uninstall.js CRAP and cyclomatic hotspot ([#5808](https://github.com/dsj1984/mandrel/issues/5808)) ([#5822](https://github.com/dsj1984/mandrel/issues/5822)) ([883d16a](https://github.com/dsj1984/mandrel/commit/883d16a6aaafedeca3fc81fc93f52db44c6be589))
49
+ * burn down the remaining single-file hotspots: baselines/components, merge-block-class, group-findings, config-schema ([#5810](https://github.com/dsj1984/mandrel/issues/5810)) ([#5826](https://github.com/dsj1984/mandrel/issues/5826)) ([39136ff](https://github.com/dsj1984/mandrel/commit/39136ffeafc94c78b219ebcb40c5b116daa4f820))
50
+ * test the git-cleanup phase drivers and probes, and remove their pass-through forwarders ([#5809](https://github.com/dsj1984/mandrel/issues/5809)) ([#5824](https://github.com/dsj1984/mandrel/issues/5824)) ([b97880b](https://github.com/dsj1984/mandrel/commit/b97880b212bf942a52b77e0ecfebb6d2c442d945))
51
+
52
+ ## [2.94.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.93.0...mandrel-v2.94.0) (2026-10-20)
53
+
54
+
55
+ ### Added
56
+
57
+ * close, merge and confirm a Story over repo-scoped REST when GitHub GraphQL is blocked ([#5793](https://github.com/dsj1984/mandrel/issues/5793)) ([#5796](https://github.com/dsj1984/mandrel/issues/5796)) ([e2cd9ff](https://github.com/dsj1984/mandrel/commit/e2cd9ff1feaac25434674f919d4e8663c5ef6cfb))
58
+
59
+
60
+ ### Fixed
61
+
62
+ * plan-side GitHub reads work over REST in cloud sessions, and blocked GraphQL warns once, not once per item ([#5794](https://github.com/dsj1984/mandrel/issues/5794)) ([#5795](https://github.com/dsj1984/mandrel/issues/5795)) ([d1a4280](https://github.com/dsj1984/mandrel/commit/d1a42802497b82b523ab4c1878114c7e775eb3b6))
63
+
18
64
  ## [2.93.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.92.0...mandrel-v2.93.0) (2026-10-19)
19
65
 
20
66
 
@@ -5,8 +5,8 @@
5
5
  * framework never hydrates, so the check fails. A missing `claude` binary,
6
6
  * unparseable output, or a project still carrying CLAUDE.md skips with
7
7
  * `ok: true` so headless/CI hosts are never blocked. The `claude --version`
8
- * spawn is injected by the registry (fixed argv, never user input); with no
9
- * runner the check skips.
8
+ * spawn goes through the injected `runner` (fixed argv, never user input);
9
+ * with neither `runner` nor `runClaude` the check skips.
10
10
  *
11
11
  * @module cli/claude-code-version
12
12
  */
@@ -33,15 +33,21 @@ export function parseClaudeVersion(text) {
33
33
  * projectRoot?: string,
34
34
  * cwd?: () => string,
35
35
  * existsSync?: (p: string) => boolean,
36
- * runClaude?: () => { status: number|null, stdout: string, error?: NodeJS.ErrnoException },
36
+ * runner?: (cmd: string, args: string[], opts?: object) => unknown,
37
+ * runClaude?: () => { status: number|null, stdout: string, error?: NodeJS.ErrnoException } | Promise<{ status: number|null, stdout: string, error?: NodeJS.ErrnoException }>,
37
38
  * }} [opts]
38
- * @returns {{ ok: boolean, detail: string, remedy?: string }}
39
+ * @returns {Promise<{ ok: boolean, detail: string, remedy?: string }>}
39
40
  */
40
- export function runClaudeCodeVersion({
41
+ export async function runClaudeCodeVersion({
41
42
  projectRoot,
42
43
  cwd = () => process.cwd(),
43
44
  existsSync = fs.existsSync,
44
- runClaude = () => ({ status: null, stdout: '', error: new Error('none') }),
45
+ runner = () => ({ status: null, stdout: '', error: new Error('none') }),
46
+ runClaude = () =>
47
+ runner('claude', ['--version'], {
48
+ shell: process.platform === 'win32',
49
+ timeout: 10_000,
50
+ }),
45
51
  } = {}) {
46
52
  const root = projectRoot ?? cwd();
47
53
  if (existsSync(path.join(root, 'CLAUDE.md'))) {
@@ -50,7 +56,7 @@ export function runClaudeCodeVersion({
50
56
  if (!existsSync(path.join(root, 'AGENTS.md'))) {
51
57
  return { ok: true, detail: 'skipped: no AGENTS.md' };
52
58
  }
53
- const r = runClaude();
59
+ const r = await runClaude();
54
60
  if (r.error || r.status !== 0) {
55
61
  return { ok: true, detail: 'skipped: claude not found on PATH' };
56
62
  }