mandrel 2.88.0 → 2.90.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 (40) hide show
  1. package/.agents/docs/agentrc-reference.json +3 -1
  2. package/.agents/docs/configuration.md +9 -0
  3. package/.agents/schemas/agentrc.schema.json +13 -0
  4. package/.agents/scripts/board-backfill.js +253 -0
  5. package/.agents/scripts/coverage-capture.js +32 -49
  6. package/.agents/scripts/lib/audit-baselines/gate-surface.js +24 -11
  7. package/.agents/scripts/lib/audit-baselines/read.js +4 -2
  8. package/.agents/scripts/lib/audit-baselines/surface-entry.js +95 -11
  9. package/.agents/scripts/lib/baselines/crap-preview-scan.js +3 -1
  10. package/.agents/scripts/lib/baselines/crap-updater-cli.js +2 -0
  11. package/.agents/scripts/lib/baselines/kinds/crap.js +37 -16
  12. package/.agents/scripts/lib/baselines/preview-gates.js +1 -0
  13. package/.agents/scripts/lib/close-validation/gates.js +40 -9
  14. package/.agents/scripts/lib/close-validation/process.js +5 -1
  15. package/.agents/scripts/lib/config/gates/crap.schema.js +15 -0
  16. package/.agents/scripts/lib/config/quality.js +49 -1
  17. package/.agents/scripts/lib/coverage-capture-affected.js +2 -1
  18. package/.agents/scripts/lib/coverage-capture-fullscope.js +2 -2
  19. package/.agents/scripts/lib/coverage-capture-incremental.js +1 -1
  20. package/.agents/scripts/lib/coverage-capture-passes.js +143 -0
  21. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  22. package/.agents/scripts/lib/coverage-capture.js +79 -38
  23. package/.agents/scripts/lib/crap-utils.js +6 -2
  24. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  25. package/.agents/scripts/lib/maintainability-utils.js +6 -1
  26. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  27. package/.agents/scripts/lib/orchestration/board-access-latch.js +101 -0
  28. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +1 -1
  29. package/.agents/scripts/lib/orchestration/column-sync.js +107 -52
  30. package/.agents/scripts/lib/orchestration/project-meta-resolver.js +44 -17
  31. package/.agents/scripts/lib/orchestration/story-handoff.js +14 -1
  32. package/.agents/scripts/lib/orchestration/verify-credit.js +4 -1
  33. package/.agents/scripts/providers/github/board-add.js +18 -9
  34. package/.agents/scripts/providers/github/projects-v2-graphql.js +15 -3
  35. package/.agents/scripts/update-crap-baseline.js +2 -2
  36. package/.agents/workflows/audit-baselines.md +7 -2
  37. package/docs/CHANGELOG.md +26 -0
  38. package/lib/cli/doctor-checks/project-access.js +114 -0
  39. package/lib/cli/registry.js +6 -0
  40. package/package.json +1 -1
@@ -16,7 +16,12 @@ const MAINTAINABILITY_WORKER_URL = new URL(
16
16
 
17
17
  const SERIAL_THRESHOLD = POOL_SERIAL_THRESHOLD;
18
18
 
19
- const IGNORED_DIRS = new Set([
19
+ /**
20
+ * Directory names `scanDirectory` never descends into — the CRAP and
21
+ * maintainability walk. Exported so the baseline-audit lens judges a dead
22
+ * `ignoreGlobs` entry against this exact walk instead of a copy of it.
23
+ */
24
+ export const IGNORED_DIRS = new Set([
20
25
  'node_modules',
21
26
  '.git',
22
27
  'dist',
@@ -26,6 +26,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
26
26
  'audit-exceptions.js',
27
27
  'audit-labels-bootstrap.js',
28
28
  'audit-to-stories.js',
29
+ 'board-backfill.js',
29
30
  'boot-sweep.js',
30
31
  'bootstrap.js',
31
32
  'check-arch-cycles.js',
@@ -0,0 +1,101 @@
1
+ /**
2
+ * board-access-latch — the typed Projects v2 access failure and a
3
+ * warn-once-per-process latch for it. Labels stay authoritative: nothing
4
+ * here aborts a run.
5
+ */
6
+
7
+ import { isInsufficientScopes } from '../../providers/github/projects-v2-graphql.js';
8
+ import { Logger } from '../Logger.js';
9
+
10
+ const PROJECT_SCOPE = 'project';
11
+ const PROJECT_SCOPE_REMEDY = 'gh auth refresh -h github.com -s project';
12
+
13
+ /** The outcome shape a board seam reports for a scope failure. */
14
+ export const SCOPE_FAILURE = Object.freeze({
15
+ reason: 'insufficient-scope',
16
+ scope: PROJECT_SCOPE,
17
+ });
18
+
19
+ // GraphQL `FORBIDDEN`, or an explicit HTTP 401/403 from the GraphQL endpoint.
20
+ const AUTH_FAILURE_RE =
21
+ /\bFORBIDDEN\b|Bad credentials|\b(?:HTTP|GraphQL) 40[13]\b/;
22
+
23
+ /**
24
+ * The board is unreachable with this token — a missing `project` scope or an
25
+ * auth refusal, never an owner-type miss.
26
+ */
27
+ export class ProjectAccessError extends Error {
28
+ /**
29
+ * @param {string} message
30
+ * @param {{ cause?: unknown }} [opts]
31
+ */
32
+ constructor(message, { cause } = {}) {
33
+ super(message, { cause });
34
+ this.name = 'ProjectAccessError';
35
+ this.scope = PROJECT_SCOPE;
36
+ this.remedy = PROJECT_SCOPE_REMEDY;
37
+ }
38
+ }
39
+
40
+ /**
41
+ * Is `err` a token-scope / auth refusal (as opposed to a NOT_FOUND miss or a
42
+ * transient failure)? A `ProjectAccessError` always is.
43
+ *
44
+ * @param {unknown} err
45
+ * @returns {boolean}
46
+ */
47
+ export function isProjectAccessFailure(err) {
48
+ if (!err) return false;
49
+ if (err instanceof ProjectAccessError) return true;
50
+ if (isInsufficientScopes(err)) return true;
51
+ const message = typeof err.message === 'string' ? err.message : String(err);
52
+ return AUTH_FAILURE_RE.test(message);
53
+ }
54
+
55
+ /**
56
+ * Wrap a raw scope/auth error in a `ProjectAccessError` (idempotent).
57
+ *
58
+ * @param {unknown} err
59
+ * @returns {ProjectAccessError}
60
+ */
61
+ export function toProjectAccessError(err) {
62
+ if (err instanceof ProjectAccessError) return err;
63
+ const detail = err?.message ?? String(err);
64
+ return new ProjectAccessError(
65
+ `GitHub Projects v2 board is not accessible with this token (missing the "${PROJECT_SCOPE}" scope?): ${detail}`,
66
+ { cause: err },
67
+ );
68
+ }
69
+
70
+ // Sinks already warned; production shares one `Logger`, so once per process.
71
+ const warnedSinks = new WeakSet();
72
+
73
+ /**
74
+ * Record a board scope failure; the first call per process (per sink) emits
75
+ * the one warning (stderr), later calls are silent.
76
+ *
77
+ * @param {{ logger?: { warn?: Function } }} [opts]
78
+ * @returns {boolean} true when this call emitted the warning.
79
+ */
80
+ export function reportBoardScopeFailure({ logger = Logger } = {}) {
81
+ if (warnedSinks.has(logger)) return false;
82
+ warnedSinks.add(logger);
83
+ logger.warn?.(
84
+ `GitHub Projects v2 board updates are failing: the token lacks the "${PROJECT_SCOPE}" scope, so board adds and Status flips are skipped (labels still move). Run \`${PROJECT_SCOPE_REMEDY}\`, then \`node .agents/scripts/board-backfill.js\` to catch the board up.`,
85
+ );
86
+ return true;
87
+ }
88
+
89
+ /**
90
+ * Classify a board-call failure: a scope/auth refusal trips the latch and
91
+ * yields the outcome fields to report; anything else yields null.
92
+ *
93
+ * @param {unknown} err
94
+ * @param {{ logger?: { warn?: Function } }} [opts]
95
+ * @returns {{ reason: 'insufficient-scope', scope: 'project' } | null}
96
+ */
97
+ export function boardScopeFailure(err, { logger } = {}) {
98
+ if (!isProjectAccessFailure(err)) return null;
99
+ reportBoardScopeFailure({ logger });
100
+ return SCOPE_FAILURE;
101
+ }
@@ -127,8 +127,8 @@ export async function evaluateKind({
127
127
  // Rows from superseded scoring semantics pass schema but are incomparable;
128
128
  // fail closed.
129
129
  const semanticsError = checkBaselineSemantics(kind, baseline, {
130
+ ...gateBlock,
130
131
  cwd,
131
- targetDirs: gateBlock?.targetDirs,
132
132
  });
133
133
  if (semanticsError) {
134
134
  return {
@@ -2,10 +2,17 @@
2
2
  * ColumnSync — collapse an issue's `agent::*` labels onto the stock Projects
3
3
  * v2 Status options (`Todo` / `In Progress` / `Done`) and push it via
4
4
  * GraphQL. Soft no-op when no project is configured, the Status field or
5
- * option is missing, or the issue is not on the board.
5
+ * option is missing, or the issue is not on the board. A token that cannot
6
+ * reach the board (missing `project` scope) reports `{ status: 'failed',
7
+ * reason: 'insufficient-scope' }` and trips the warn-once latch instead.
6
8
  */
7
9
 
8
10
  import { AGENT_LABELS } from '../label-constants.js';
11
+ import {
12
+ isProjectAccessFailure,
13
+ reportBoardScopeFailure,
14
+ SCOPE_FAILURE,
15
+ } from './board-access-latch.js';
9
16
  import {
10
17
  invalidateProjectMetaCache,
11
18
  readProjectMetaCache,
@@ -40,6 +47,59 @@ export function columnForLabels(labels) {
40
47
  return null;
41
48
  }
42
49
 
50
+ /**
51
+ * The issue's item id on board `projectId`, or null. Walks issue →
52
+ * projectItems, not board → items: scanning board items hits a pagination
53
+ * cliff on large boards; an issue is on few boards.
54
+ */
55
+ async function getProjectItemId(provider, issueId, projectId) {
56
+ const owner = provider.owner;
57
+ const repo = provider.repo;
58
+ if (!owner || !repo) return null;
59
+ const data = await provider.graphql(
60
+ `
61
+ query($owner: String!, $repo: String!, $number: Int!) {
62
+ repository(owner: $owner, name: $repo) {
63
+ issue(number: $number) {
64
+ projectItems(first: 20) {
65
+ nodes {
66
+ id
67
+ project { id }
68
+ }
69
+ }
70
+ }
71
+ }
72
+ }`,
73
+ { owner, repo, number: issueId },
74
+ );
75
+ const nodes = data?.repository?.issue?.projectItems?.nodes ?? [];
76
+ const match = nodes.find((n) => n?.project?.id === projectId);
77
+ return match?.id ?? null;
78
+ }
79
+
80
+ /** Push one Status option onto a board item. */
81
+ async function updateStatusField(provider, meta, itemId, optionId) {
82
+ await provider.graphql(
83
+ `
84
+ mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
85
+ updateProjectV2ItemFieldValue(
86
+ input: {
87
+ projectId: $projectId,
88
+ itemId: $itemId,
89
+ fieldId: $fieldId,
90
+ value: { singleSelectOptionId: $optionId }
91
+ }
92
+ ) { projectV2Item { id } }
93
+ }`,
94
+ {
95
+ projectId: meta.projectId,
96
+ itemId,
97
+ fieldId: meta.fieldId,
98
+ optionId,
99
+ },
100
+ );
101
+ }
102
+
43
103
  export class ColumnSync {
44
104
  /**
45
105
  * @param {{
@@ -68,6 +128,8 @@ export class ColumnSync {
68
128
  this._meta = null; // lazy-cached { projectId, fieldId, options: Map<name, id> }
69
129
  // Disk-hydrated meta may be stale; a failed mutation then invalidates it.
70
130
  this._metaFromDiskCache = false;
131
+ // A scope/auth refusal seen this process; memory only, never on disk.
132
+ this._accessFailed = false;
71
133
  }
72
134
 
73
135
  /**
@@ -92,47 +154,58 @@ export class ColumnSync {
92
154
  if (!this.projectNumber) {
93
155
  return { status: 'skipped', reason: 'no-project' };
94
156
  }
157
+ try {
158
+ return await this.#setColumnOnBoard(issueId, column);
159
+ } catch (err) {
160
+ if (!isProjectAccessFailure(err)) throw err;
161
+ return this.#scopeFailure();
162
+ }
163
+ }
95
164
 
165
+ async #setColumnOnBoard(issueId, column) {
96
166
  const meta = await this.#loadMeta();
97
- if (!meta) return { status: 'skipped', reason: 'no-meta' };
167
+ if (!meta) return this.#metaMiss();
98
168
 
99
169
  const optionId = meta.options.get(column);
100
170
  if (!optionId) {
101
171
  return { status: 'skipped', reason: `no-option-${column}` };
102
172
  }
103
173
 
104
- const itemId = await this.#getProjectItemId(issueId, meta.projectId);
174
+ const itemId = await getProjectItemId(
175
+ this.provider,
176
+ issueId,
177
+ meta.projectId,
178
+ );
105
179
  if (!itemId) return { status: 'skipped', reason: 'not-on-project' };
106
180
 
107
181
  try {
108
- await this.provider.graphql(
109
- `
110
- mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
111
- updateProjectV2ItemFieldValue(
112
- input: {
113
- projectId: $projectId,
114
- itemId: $itemId,
115
- fieldId: $fieldId,
116
- value: { singleSelectOptionId: $optionId }
117
- }
118
- ) { projectV2Item { id } }
119
- }`,
120
- {
121
- projectId: meta.projectId,
122
- itemId,
123
- fieldId: meta.fieldId,
124
- optionId,
125
- },
126
- );
182
+ await updateStatusField(this.provider, meta, itemId, optionId);
127
183
  } catch (err) {
128
184
  // Likely a reconfigured board: drop cached meta so the next flip
129
- // self-heals, and re-throw for the caller's handling.
130
- this.#invalidateMetaCache();
185
+ // self-heals, and re-throw for the caller's handling. A scope refusal
186
+ // is not staleness, so the cache stays.
187
+ if (!isProjectAccessFailure(err)) this.#invalidateMetaCache();
131
188
  throw err;
132
189
  }
133
190
  return { status: 'synced', column };
134
191
  }
135
192
 
193
+ /** No meta: a latched scope refusal, or a board without a Status field. */
194
+ #metaMiss() {
195
+ if (this._accessFailed) return this.#scopeFailure();
196
+ return { status: 'skipped', reason: 'no-meta' };
197
+ }
198
+
199
+ /**
200
+ * Latch the scope failure (one warning per process) and report it to the
201
+ * caller; never throws, so the label transition still completes.
202
+ */
203
+ #scopeFailure() {
204
+ this._accessFailed = true;
205
+ reportBoardScopeFailure({ logger: this.logger });
206
+ return { status: 'failed', ...SCOPE_FAILURE };
207
+ }
208
+
136
209
  /**
137
210
  * Cache key; same owner `#loadMeta` resolves against.
138
211
  *
@@ -158,6 +231,7 @@ export class ColumnSync {
158
231
  }
159
232
 
160
233
  async #loadMeta() {
234
+ if (this._accessFailed) return null;
161
235
  if (this._meta !== null) return this._meta || null;
162
236
  // Board meta is repo-invariant; the disk cache spares each cold CLI
163
237
  // process the resolve round-trips.
@@ -208,6 +282,10 @@ export class ColumnSync {
208
282
  this._metaFromDiskCache = false;
209
283
  return this._meta;
210
284
  } catch (err) {
285
+ if (isProjectAccessFailure(err)) {
286
+ this._accessFailed = true;
287
+ return null;
288
+ }
211
289
  this.logger.warn?.(
212
290
  `[ColumnSync] could not resolve project metadata: ${err?.message ?? err}`,
213
291
  );
@@ -227,7 +305,11 @@ export class ColumnSync {
227
305
  if (!this.projectNumber) return null;
228
306
  const meta = await this.#loadMeta();
229
307
  if (!meta) return null;
230
- const itemId = await this.#getProjectItemId(issueId, meta.projectId);
308
+ const itemId = await getProjectItemId(
309
+ this.provider,
310
+ issueId,
311
+ meta.projectId,
312
+ );
231
313
  if (!itemId) return null;
232
314
  try {
233
315
  const data = await this.provider.graphql(
@@ -252,31 +334,4 @@ export class ColumnSync {
252
334
  return null;
253
335
  }
254
336
  }
255
-
256
- async #getProjectItemId(issueId, projectId) {
257
- // Walk issue → projectItems, not board → items: scanning board items
258
- // hits a pagination cliff on large boards; an issue is on few boards.
259
- const owner = this.provider.owner;
260
- const repo = this.provider.repo;
261
- if (!owner || !repo) return null;
262
- const data = await this.provider.graphql(
263
- `
264
- query($owner: String!, $repo: String!, $number: Int!) {
265
- repository(owner: $owner, name: $repo) {
266
- issue(number: $number) {
267
- projectItems(first: 20) {
268
- nodes {
269
- id
270
- project { id }
271
- }
272
- }
273
- }
274
- }
275
- }`,
276
- { owner, repo, number: issueId },
277
- );
278
- const nodes = data?.repository?.issue?.projectItems?.nodes ?? [];
279
- const match = nodes.find((n) => n?.project?.id === projectId);
280
- return match?.id ?? null;
281
- }
282
337
  }
@@ -5,6 +5,14 @@
5
5
  * `projectV2 { … }` selection body as `projectFields`.
6
6
  */
7
7
 
8
+ import {
9
+ isProjectAccessFailure,
10
+ ProjectAccessError,
11
+ toProjectAccessError,
12
+ } from './board-access-latch.js';
13
+
14
+ export { ProjectAccessError };
15
+
8
16
  /**
9
17
  * Priority order. `viewer` (the ambient identity) is last so a configured
10
18
  * owner always wins.
@@ -42,8 +50,36 @@ function buildScopedQuery(scope, projectFields) {
42
50
  }
43
51
 
44
52
  /**
45
- * The first non-null `projectV2` node down the ladder; a throwing or null
46
- * rung is a miss. With no `owner`, only `viewer` is tried.
53
+ * One rung's `projectV2` node, or null for a miss. An owner miss (NOT_FOUND)
54
+ * and any other non-access error advance the ladder; a scope or auth refusal
55
+ * is raised as a `ProjectAccessError`.
56
+ */
57
+ async function queryRung(
58
+ provider,
59
+ scope,
60
+ { owner, projectNumber, projectFields },
61
+ ) {
62
+ const vars = scope.needsOwner
63
+ ? { owner, number: projectNumber }
64
+ : { number: projectNumber };
65
+ try {
66
+ const data = await provider.graphql(
67
+ buildScopedQuery(scope, projectFields),
68
+ vars,
69
+ );
70
+ return data?.[scope.root]?.projectV2 ?? null;
71
+ } catch (err) {
72
+ if (isProjectAccessFailure(err)) throw toProjectAccessError(err);
73
+ return null;
74
+ }
75
+ }
76
+
77
+ /**
78
+ * The first non-null `projectV2` node down the ladder. A null rung or an
79
+ * owner miss (NOT_FOUND — expected on two of three rungs) advances; a scope
80
+ * or auth refusal is identical on every rung, so it fails fast as a
81
+ * `ProjectAccessError` instead of being hidden by the ladder. With no
82
+ * `owner`, only `viewer` is tried.
47
83
  *
48
84
  * @param {{
49
85
  * provider: { graphql: Function },
@@ -52,6 +88,7 @@ function buildScopedQuery(scope, projectFields) {
52
88
  * projectFields: string,
53
89
  * }} args
54
90
  * @returns {Promise<object|null>} the resolved `projectV2` node, or null.
91
+ * @throws {ProjectAccessError} when the token cannot read the board.
55
92
  */
56
93
  export async function resolveProjectMeta(args) {
57
94
  const { provider, owner, projectNumber, projectFields } = args ?? {};
@@ -66,21 +103,11 @@ export async function resolveProjectMeta(args) {
66
103
 
67
104
  for (const scope of OWNER_SCOPES) {
68
105
  if (scope.needsOwner && !owner) continue;
69
-
70
- const query = buildScopedQuery(scope, projectFields);
71
- const vars = scope.needsOwner
72
- ? { owner, number: projectNumber }
73
- : { number: projectNumber };
74
-
75
- let data;
76
- try {
77
- data = await provider.graphql(query, vars);
78
- } catch {
79
- // Wrong owner type (NOT_FOUND) etc. — advance the ladder.
80
- continue;
81
- }
82
-
83
- const node = data?.[scope.root]?.projectV2;
106
+ const node = await queryRung(provider, scope, {
107
+ owner,
108
+ projectNumber,
109
+ projectFields,
110
+ });
84
111
  if (node) return node;
85
112
  }
86
113
 
@@ -176,6 +176,19 @@ function headSha(ctx) {
176
176
  return gitLine(ctx.git, ctx.cwd, ['rev-parse', 'HEAD']);
177
177
  }
178
178
 
179
+ /**
180
+ * A child's env with `AP_AGENTRC_CWD` pinned to the Story worktree, layered
181
+ * last so a stale inherited value cannot win: a gate judges the branch by
182
+ * the branch's own `.agentrc.json`.
183
+ *
184
+ * @param {object} ctx
185
+ * @param {Record<string, string|undefined>} [env] defaults to `ctx.env`.
186
+ * @returns {Record<string, string|undefined>}
187
+ */
188
+ function worktreeEnv(ctx, env) {
189
+ return { ...(env ?? ctx.env), AP_AGENTRC_CWD: ctx.cwd };
190
+ }
191
+
179
192
  /**
180
193
  * Run one child with its combined output streamed live into the step's
181
194
  * evidence log (announced, and recorded in story-progress, before it spawns).
@@ -197,7 +210,7 @@ async function runLogged(ctx, logName, cmd, args, env) {
197
210
  progress: ctx.progress,
198
211
  cmd,
199
212
  args,
200
- opts: { cwd: ctx.cwd, env },
213
+ opts: { cwd: ctx.cwd, env: worktreeEnv(ctx, env) },
201
214
  file,
202
215
  tag: logName,
203
216
  });
@@ -139,7 +139,10 @@ export function resolveVerifyCredit(
139
139
  const { crap } = getQualityImpl(config);
140
140
  const mode =
141
141
  crap?.enabled !== false &&
142
- hasNpmScriptImpl(readPackageScriptsImpl(worktree), 'test:coverage')
142
+ hasNpmScriptImpl(
143
+ readPackageScriptsImpl(worktree),
144
+ crap?.captureScript ?? 'test:coverage',
145
+ )
143
146
  ? 'capture'
144
147
  : 'evidence';
145
148
 
@@ -2,10 +2,13 @@
2
2
  * GitHub Provider — post-create "add issue to the Projects V2 board" step.
3
3
  * Needed because GitHub's auto-add workflow is off on fresh boards and can't
4
4
  * be enabled via API. Never throws (issue creation survives a board failure)
5
- * and is idempotent (the mutation returns an existing item).
5
+ * and is idempotent (the mutation returns an existing item). A token without
6
+ * the `project` scope reports `reason: 'insufficient-scope'` and trips the
7
+ * warn-once latch rather than warning per issue.
6
8
  */
7
9
 
8
10
  import { Logger } from '../../lib/Logger.js';
11
+ import { boardScopeFailure } from '../../lib/orchestration/board-access-latch.js';
9
12
 
10
13
  /**
11
14
  * No project number → no-op without network.
@@ -16,7 +19,7 @@ import { Logger } from '../../lib/Logger.js';
16
19
  * getProjectNumber?: () => number|null,
17
20
  * addItemToProject?: (nodeId: string) => Promise<unknown>,
18
21
  * }} opts
19
- * @returns {Promise<{ added: boolean, reason?: string }>}
22
+ * @returns {Promise<{ added: boolean, reason?: string, scope?: string }>}
20
23
  */
21
24
  export async function addIssueToBoard({
22
25
  nodeId,
@@ -35,13 +38,19 @@ export async function addIssueToBoard({
35
38
  await addItemToProject(nodeId);
36
39
  return { added: true };
37
40
  } catch (err) {
38
- const label =
39
- issueNumber !== null && issueNumber !== undefined
40
- ? `Issue #${issueNumber}`
41
- : `issue ${nodeId}`;
42
- Logger.warn(
43
- `[GitHubProvider] Failed to add ${label} to project: ${err.message}`,
44
- );
41
+ const scopeFailure = boardScopeFailure(err);
42
+ if (scopeFailure) return { added: false, ...scopeFailure };
43
+ warnAddFailure(err, issueNumber, nodeId);
45
44
  return { added: false, reason: 'error' };
46
45
  }
47
46
  }
47
+
48
+ function warnAddFailure(err, issueNumber, nodeId) {
49
+ const label =
50
+ issueNumber !== null && issueNumber !== undefined
51
+ ? `Issue #${issueNumber}`
52
+ : `issue ${nodeId}`;
53
+ Logger.warn(
54
+ `[GitHubProvider] Failed to add ${label} to project: ${err.message}`,
55
+ );
56
+ }
@@ -65,7 +65,16 @@ async function gql(ctx, query, variables, { retry = false } = {}) {
65
65
  return retry ? withTransientRetry(run) : run();
66
66
  }
67
67
 
68
- async function lookupProject(ctx, fragment, strict = false) {
68
+ /**
69
+ * `strict` rethrows every failure; `scopeStrict` rethrows only a scope
70
+ * refusal (identical on both rungs), leaving an owner miss a soft null.
71
+ */
72
+ async function lookupProject(
73
+ ctx,
74
+ fragment,
75
+ strict = false,
76
+ { scopeStrict = false } = {},
77
+ ) {
69
78
  if (!ctx.projectNumber) return null;
70
79
  let lastError = null;
71
80
  for (const scope of ['user', 'organization']) {
@@ -78,7 +87,7 @@ async function lookupProject(ctx, fragment, strict = false) {
78
87
  );
79
88
  if (data?.[scope]?.projectV2) return data[scope].projectV2;
80
89
  } catch (err) {
81
- if (strict && isInsufficientScopes(err)) throw err;
90
+ if ((strict || scopeStrict) && isInsufficientScopes(err)) throw err;
82
91
  lastError = err;
83
92
  }
84
93
  }
@@ -260,7 +269,10 @@ export async function ensureProjectFields(ctx, fieldDefs) {
260
269
 
261
270
  export async function addItemToProject(ctx, contentNodeId) {
262
271
  if (!ctx.state.projectId) {
263
- const project = await lookupProject(ctx, 'id');
272
+ // A scope refusal must reach the caller, not read as "no board".
273
+ const project = await lookupProject(ctx, 'id', false, {
274
+ scopeStrict: true,
275
+ });
264
276
  if (!project) return;
265
277
  ctx.state.projectId = project.id;
266
278
  }
@@ -39,7 +39,7 @@ const USAGE = {
39
39
  ],
40
40
  [
41
41
  '--coverage <path>',
42
- 'Read coverage from this path (default `coverage/coverage-final.json`).',
42
+ "Read coverage from this path; wins over config (default `delivery.quality.gates.crap.coveragePath`, falling back to the coverage gate's `coveragePath`, `coverage/coverage-final.json`).",
43
43
  ],
44
44
  [
45
45
  '--full-scope',
@@ -55,7 +55,7 @@ const USAGE = {
55
55
  ],
56
56
  ],
57
57
  notes: [
58
- 'Run `npm run test:coverage` first — without a coverage artifact the refresh refuses (exit 1) and leaves the baseline untouched.',
58
+ 'Run the CRAP capture script first — `npm run <delivery.quality.gates.crap.captureScript>`, default `npm run test:coverage` — without a coverage artifact the refresh refuses (exit 1) and leaves the baseline untouched.',
59
59
  ],
60
60
  };
61
61
 
@@ -107,8 +107,13 @@ Two envelope-level reads come **before** any finding:
107
107
  - `baselineExists` is `false`, or `parseError` is non-null — the instrument
108
108
  cannot be read at all.
109
109
  - `deadIgnoreGlobs` is non-empty — a configured ignore pattern matches zero
110
- files. It protects nothing today and silently exempts the next file that
111
- happens to match it.
110
+ files that **its own gate's scanner walk** would visit: that gate's
111
+ `targetDirs`, minus the directories its scanner skips. It protects nothing
112
+ today and silently exempts the next file that happens to match it. A glob
113
+ aimed at a generated or installed tree (`node_modules`, `dist`, `build`,
114
+ `out`, `coverage`, `.next`) that the scanner would visit is never reported
115
+ dead — it is load-bearing after an install or build, even when the tree is
116
+ absent now.
112
117
 
113
118
  Grade a stub or unenforced gate **Medium**, a `parseError` on an enforced
114
119
  gate **High** (delivery reads that file every run), a dead glob **Low**.
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,32 @@ 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.90.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.89.0...mandrel-v2.90.0) (2026-10-16)
19
+
20
+
21
+ ### Added
22
+
23
+ * surface Projects v2 scope failures instead of swallowing them, and backfill the board ([#5727](https://github.com/dsj1984/mandrel/issues/5727)) ([#5733](https://github.com/dsj1984/mandrel/issues/5733)) ([41bf87a](https://github.com/dsj1984/mandrel/commit/41bf87a94e2930d04ce4a8f374fb204bfca94e77))
24
+
25
+
26
+ ### Fixed
27
+
28
+ * coverage-capture: route the tree/content digest git calls through child-exec so large repos get a freshable stamp ([#5728](https://github.com/dsj1984/mandrel/issues/5728)) ([#5730](https://github.com/dsj1984/mandrel/issues/5730)) ([8919d41](https://github.com/dsj1984/mandrel/commit/8919d414e715afa9dd352a8c18cd41a72fbb2118))
29
+ * handoff and close gate children resolve .agentrc.json from the Story worktree, not the main checkout ([#5729](https://github.com/dsj1984/mandrel/issues/5729)) ([#5731](https://github.com/dsj1984/mandrel/issues/5731)) ([af4f4cf](https://github.com/dsj1984/mandrel/commit/af4f4cf05e7f7b05e75ab0418a366733206b84ad))
30
+
31
+ ## [2.89.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.88.0...mandrel-v2.89.0) (2026-10-16)
32
+
33
+
34
+ ### Added
35
+
36
+ * CRAP gate: own coverage source (crap.coveragePath + crap.captureScript) honored by seat, capture, preview and updater ([#5717](https://github.com/dsj1984/mandrel/issues/5717)) ([#5719](https://github.com/dsj1984/mandrel/issues/5719)) ([2912ae0](https://github.com/dsj1984/mandrel/commit/2912ae07ae488b171f005e69cab16d2dab473d6c))
37
+
38
+
39
+ ### Fixed
40
+
41
+ * audit-baselines: judge dead ignoreGlobs against each gate's own scanner walk, not the lens's ([#5716](https://github.com/dsj1984/mandrel/issues/5716)) ([#5718](https://github.com/dsj1984/mandrel/issues/5718)) ([9d00bb1](https://github.com/dsj1984/mandrel/commit/9d00bb1f25a1e6b4745ea9efcf260d9ed09f8ae9))
42
+ * coverage-capture failure and timeout messages, and the close coverage-c… ([#5721](https://github.com/dsj1984/mandrel/issues/5721)) ([#5722](https://github.com/dsj1984/mandrel/issues/5722)) ([dbf1ac8](https://github.com/dsj1984/mandrel/commit/dbf1ac855a19206a179ebdc664e4fe4f4c6c4f56))
43
+
18
44
  ## [2.88.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.87.0...mandrel-v2.88.0) (2026-10-15)
19
45
 
20
46