vouchington-tooling 0.87.1 → 1.0.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 (97) hide show
  1. package/README.md +1 -8
  2. package/dist/agent-blackboard/feedback-journal-audit.mjs +14 -6
  3. package/dist/agent-blackboard/feedback-journal-sandbox.d.mts +4 -2
  4. package/dist/agent-blackboard/feedback-journal-sandbox.mjs +14 -6
  5. package/dist/agent-blackboard/snapshot-cleanup-receipt.d.mts +2 -2
  6. package/dist/agent-blackboard/snapshot-cleanup-receipt.mjs +20 -12
  7. package/dist/agent-blackboard/snapshot-partition-cleanup.d.mts +1 -0
  8. package/dist/agent-blackboard/snapshot-partition-cleanup.mjs +3 -0
  9. package/dist/agent-blackboard/snapshot-partitions.mjs +1 -1
  10. package/dist/agent-blackboard/snapshot-types.d.mts +8 -0
  11. package/dist/audit-journal/audit-block.d.mts +2 -0
  12. package/dist/audit-journal/audit-block.mjs +13 -8
  13. package/dist/audit-journal/ci-failures.d.mts +6 -2
  14. package/dist/audit-journal/ci-failures.mjs +12 -6
  15. package/dist/audit-journal/journal.d.mts +2 -0
  16. package/dist/audit-journal/journal.mjs +18 -3
  17. package/dist/audit-journal/scope.d.mts +25 -0
  18. package/dist/audit-journal/scope.mjs +47 -0
  19. package/dist/audit-journal/types.d.mts +3 -0
  20. package/dist/cli/index.mjs +0 -6
  21. package/dist/cli/parse-forwarded-commands.d.mts +1 -1
  22. package/dist/cli/parse-forwarded-commands.mjs +0 -2
  23. package/dist/cli/parse.d.mts +1 -7
  24. package/dist/cli/parse.mjs +0 -1
  25. package/dist/cli/script-paths.mjs +0 -1
  26. package/dist/cli/usage-text.d.mts +1 -1
  27. package/dist/cli/usage-text.mjs +0 -6
  28. package/dist/gh-cli/exec.d.mts +8 -2
  29. package/dist/gh-cli/exec.mjs +3 -3
  30. package/dist/gha-review-payload/index.d.mts +0 -2
  31. package/dist/gha-review-payload/index.mjs +0 -1
  32. package/dist/index.d.mts +2 -8
  33. package/dist/index.mjs +1 -4
  34. package/dist/mcp-server/dispatch.mjs +1 -1
  35. package/dist/mcp-server/handlers-pr.mjs +1 -1
  36. package/dist/mcp-server/handlers-snapshot-cleanup.mjs +8 -0
  37. package/dist/mcp-server/handlers-snapshot-partition.mjs +6 -1
  38. package/dist/mcp-server/install-info.d.mts +2 -2
  39. package/dist/mcp-server/install-info.mjs +10 -6
  40. package/dist/mcp-server/pr-diff-size.d.mts +16 -0
  41. package/dist/mcp-server/pr-diff-size.mjs +49 -0
  42. package/dist/mcp-server/pr-live.d.mts +3 -0
  43. package/dist/mcp-server/pr-live.mjs +8 -2
  44. package/dist/mcp-server/pr-prepare.mjs +20 -12
  45. package/dist/mcp-server/server.mjs +2 -1
  46. package/dist/mcp-server/snapshot-recovery.d.mts +8 -0
  47. package/dist/mcp-server/snapshot-recovery.mjs +76 -0
  48. package/dist/mcp-server/snapshot-registry.d.mts +3 -1
  49. package/dist/mcp-server/snapshot-registry.mjs +3 -1
  50. package/dist/mcp-server/tools-pr.mjs +2 -1
  51. package/dist/mcp-server/tools.mjs +16 -5
  52. package/dist/mcp-server/worktree.mjs +4 -1
  53. package/docs/mcp-server.md +43 -10
  54. package/package.json +1 -16
  55. package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
  56. package/skills/agent-workflow/SKILL.md +7 -1
  57. package/skills/dependabot/SKILL.md +4 -3
  58. package/skills/final-review/references/orchestrator.md +3 -3
  59. package/skills/manifest.json +25 -33
  60. package/skills/planning/SKILL.md +3 -0
  61. package/skills/retrospective/SKILL.md +2 -1
  62. package/skills/review-ci-logs/SKILL.md +2 -0
  63. package/skills/stacked-prs/SKILL.md +8 -2
  64. package/skills/stacked-prs/references/drain.md +3 -1
  65. package/skills/triage-loop/SKILL.md +125 -21
  66. package/skills/triage-loop/references/shepherd.md +45 -0
  67. package/skills/triage-prs/SKILL.md +15 -18
  68. package/skills/triage-prs/references/rubric.md +2 -2
  69. package/skills/triage-sweep/SKILL.md +40 -12
  70. package/dist/gha-check-run/cli.d.mts +0 -2
  71. package/dist/gha-check-run/cli.mjs +0 -81
  72. package/dist/gha-check-run/github.d.mts +0 -30
  73. package/dist/gha-check-run/github.mjs +0 -63
  74. package/dist/gha-check-run/index.d.mts +0 -2
  75. package/dist/gha-check-run/index.mjs +0 -2
  76. package/dist/gha-claude-post-review/index.d.mts +0 -3
  77. package/dist/gha-claude-post-review/index.mjs +0 -2
  78. package/dist/gha-post-review/claude-token.d.mts +0 -25
  79. package/dist/gha-post-review/claude-token.mjs +0 -109
  80. package/dist/gha-post-review/cli.d.mts +0 -1
  81. package/dist/gha-post-review/cli.mjs +0 -22
  82. package/dist/gha-post-review/github.d.mts +0 -13
  83. package/dist/gha-post-review/github.mjs +0 -58
  84. package/dist/gha-post-review/index.d.mts +0 -13
  85. package/dist/gha-post-review/index.mjs +0 -8
  86. package/dist/gha-post-review/post.d.mts +0 -24
  87. package/dist/gha-post-review/post.mjs +0 -39
  88. package/dist/gha-post-review/pull-io.d.mts +0 -13
  89. package/dist/gha-post-review/pull-io.mjs +0 -88
  90. package/dist/gha-post-review/token.d.mts +0 -9
  91. package/dist/gha-post-review/token.mjs +0 -21
  92. package/dist/gha-review-payload/cli.d.mts +0 -1
  93. package/dist/gha-review-payload/cli.mjs +0 -24
  94. package/dist/gha-review-payload/file.d.mts +0 -7
  95. package/dist/gha-review-payload/file.mjs +0 -62
  96. package/scripts/gha/materialize-pr-context.sh +0 -123
  97. package/skills/ready-and-shepherd/SKILL.md +0 -110
package/README.md CHANGED
@@ -70,7 +70,6 @@ vouchington clean-workspace
70
70
  vouchington install-github-release --repo lycheeverse/lychee --version 0.24.2 --asset 'lychee-{platform}.tar.gz' --bin lychee
71
71
  vouchington run-with-timeout 120 10 docker push example
72
72
  vouchington lint-links --offline
73
- vouchington materialize-pr-context
74
73
  vouchington wait-for-apt-locks
75
74
  vouchington retrospective-transcript --jsonl /path/to/transcript.jsonl
76
75
  vouchington retrospective-facts --pr 49 --repo vouchington/vouchington-infra --raw
@@ -93,8 +92,6 @@ vouchington tmux agent-reminder session-start
93
92
  vouchington tmux post-tool < hook-payload.json
94
93
  vouchington dead-code --baseline dead-code-baseline.json --config .jscpd.json --update
95
94
  vouchington swift-semantic-equal BASE HEAD App.swift
96
- vouchington post-review
97
- vouchington stage-review-payload optional|required <source> <destination>
98
95
  ```
99
96
 
100
97
  ### Running `allocate-browser-safe-ports` without an install
@@ -686,8 +683,6 @@ import {
686
683
  import { readResponseBody } from 'vouchington-tooling/http-body'
687
684
  import { runAstGrepRule } from 'vouchington-tooling/ast-grep-rule'
688
685
  import { parseReviewPayload, remapReviewComments } from 'vouchington-tooling/gha-review-payload'
689
- import { postReviewWithTokenFromEnv, runPostReview } from 'vouchington-tooling/gha-post-review'
690
- import { postClaudeReviewFromEnv } from 'vouchington-tooling/gha-claude-post-review'
691
686
  import { nextPageUrlFromLinkHeader } from 'vouchington-tooling/http-link-pagination'
692
687
  import {
693
688
  cmdUpload,
@@ -990,9 +985,7 @@ previous process died first, including SIGKILL. Each workspace records its owner
990
985
  audit can delete directories whose owner is gone.
991
986
 
992
987
  The artifact, review-payload, HTTP body, and pagination APIs validate untrusted inputs at their
993
- boundaries. Neutral review posting lives in `gha-post-review` and requires a caller-supplied GitHub
994
- token. Claude App OIDC is an explicitly selected `gha-claude-post-review` adapter; the legacy
995
- token-source router remains deprecated for one release line.
988
+ boundaries.
996
989
 
997
990
  `vitest-diagnostics` reads Node diagnostic report JSON from a caller-selected directory. It sorts
998
991
  filenames, tolerates partial files, returns only a bounded field allowlist, and never emits raw
@@ -1,7 +1,8 @@
1
- import { buildCiFailuresSection, getConformingGroups, incompleteCiSection, } from "../audit-journal/ci-failures.mjs";
1
+ import { buildCiFailuresSection, countCiFailureBlocks, getConformingGroups, incompleteCiSection, } from "../audit-journal/ci-failures.mjs";
2
2
  import { scanJournal } from "../audit-journal/journal.mjs";
3
+ import { scopeSinceRetrospective } from "../audit-journal/scope.mjs";
3
4
  import { validateSessionId } from "../audit-journal/session-id.mjs";
4
- import { getConformingSandboxBlocks, journalSandboxSection, unavailableSandboxSection, } from "./feedback-journal-sandbox.mjs";
5
+ import { countSandboxBlocks, getConformingSandboxBlocks, journalSandboxSection, unavailableSandboxSection, } from "./feedback-journal-sandbox.mjs";
5
6
  function report(journalStatus, markdown) {
6
7
  return { coverage: { journalStatus, truncated: false }, markdown };
7
8
  }
@@ -23,11 +24,18 @@ export function renderJournalAuditReport(options, scanned) {
23
24
  return unavailable('blackboard unreachable');
24
25
  if (scanned.status === 'not-found')
25
26
  return unavailable('no journal for session');
26
- const ci = getConformingGroups(scanned.entries, options.redact, options.budgets?.ciBytes);
27
- const sandbox = getConformingSandboxBlocks(scanned.entries, options.redact, options.budgets?.sandboxBytes);
27
+ // Only what happened after the session's newest earlier retrospective is new to this one.
28
+ const { included, excluded, boundary } = scopeSinceRetrospective(scanned.entries, scanned.retrospectives);
29
+ const excludedNote = (count) => count > 0 && boundary
30
+ ? `Excluded: ${count} blocks from before retrospective ${boundary.sourceEventId}`
31
+ : undefined;
32
+ const ciNote = excludedNote(countCiFailureBlocks(excluded));
33
+ const sandboxNote = excludedNote(countSandboxBlocks(excluded));
34
+ const ci = getConformingGroups(included, options.redact, options.budgets?.ciBytes);
35
+ const sandbox = getConformingSandboxBlocks(included, options.redact, options.budgets?.sandboxBytes);
28
36
  if (scanned.truncated)
29
- return report('partial', `${incompleteCiSection(ci)}\n\n${unavailableSandboxSection('journal scan incomplete', sandbox)}`);
30
- return report('complete', `${buildCiFailuresSection(ci)}\n\n${journalSandboxSection(sandbox)}`);
37
+ return report('partial', `${incompleteCiSection(ci, ciNote)}\n\n${unavailableSandboxSection('journal scan incomplete', sandbox, sandboxNote)}`);
38
+ return report('complete', `${buildCiFailuresSection(ci, ciNote)}\n\n${journalSandboxSection(sandbox, sandboxNote)}`);
31
39
  }
32
40
  export async function buildJournalAuditReport(sessionId, options) {
33
41
  return renderJournalAuditReport(options, await loadJournalAuditInput(sessionId, options));
@@ -2,5 +2,7 @@ import type { AuditRedactor } from '../audit-journal/text.mts';
2
2
  import type { JournalEntry } from '../audit-journal/types.mts';
3
3
  /** Journal entries that hold sandbox or permission blocks (several per entry), made paste-safe. */
4
4
  export declare function getConformingSandboxBlocks(entries: Iterable<JournalEntry>, redact?: AuditRedactor, maxBytes?: number): string[];
5
- export declare function unavailableSandboxSection(reason: string, blocks?: string[]): string;
6
- export declare function journalSandboxSection(blocks: string[]): string;
5
+ /** How many sandbox blocks the entries hold, for reporting the ones a scope left out. */
6
+ export declare function countSandboxBlocks(entries: Iterable<JournalEntry>): number;
7
+ export declare function unavailableSandboxSection(reason: string, blocks?: string[], note?: string): string;
8
+ export declare function journalSandboxSection(blocks: string[], note?: string): string;
@@ -1,4 +1,5 @@
1
- import { conformingBlocks, matchAuditBlock } from "../audit-journal/audit-block.mjs";
1
+ import { conformingBlocks, countConformingBlocks, matchAuditBlock, } from "../audit-journal/audit-block.mjs";
2
+ import { lineOf } from "../audit-journal/ci-failures.mjs";
2
3
  const SANDBOX_SECTION_HEADER = '## Sandbox & Permission Audit';
3
4
  const SOURCE = 'journal entries only';
4
5
  const EVIDENCE = /^ {2}- Evidence: .*[^\s]$/;
@@ -57,11 +58,18 @@ const UNPARSED = {
57
58
  export function getConformingSandboxBlocks(entries, redact, maxBytes = SANDBOX_BLOCKS_MAX_BYTES) {
58
59
  return conformingBlocks(entries, matchBlock, Math.min(maxBytes, SANDBOX_BLOCKS_MAX_BYTES), redact, omissionBlock, UNPARSED);
59
60
  }
60
- export function unavailableSandboxSection(reason, blocks = []) {
61
- return [`${SANDBOX_SECTION_HEADER}\nStatus: unavailable (${reason})`, ...blocks].join('\n\n');
61
+ /** How many sandbox blocks the entries hold, for reporting the ones a scope left out. */
62
+ export function countSandboxBlocks(entries) {
63
+ return countConformingBlocks(entries, matchBlock);
62
64
  }
63
- export function journalSandboxSection(blocks) {
65
+ export function unavailableSandboxSection(reason, blocks = [], note) {
66
+ return [
67
+ `${SANDBOX_SECTION_HEADER}\nStatus: unavailable (${reason})${lineOf(note)}`,
68
+ ...blocks,
69
+ ].join('\n\n');
70
+ }
71
+ export function journalSandboxSection(blocks, note) {
64
72
  if (blocks.length === 0)
65
- return `${SANDBOX_SECTION_HEADER}\nStatus: none observed (${SOURCE})`;
66
- return `${SANDBOX_SECTION_HEADER}\nStatus: events observed (${SOURCE})\n\n${blocks.join('\n\n')}`;
73
+ return `${SANDBOX_SECTION_HEADER}\nStatus: none observed (${SOURCE})${lineOf(note)}`;
74
+ return `${SANDBOX_SECTION_HEADER}\nStatus: events observed (${SOURCE})${lineOf(note)}\n\n${blocks.join('\n\n')}`;
67
75
  }
@@ -1,6 +1,6 @@
1
- import type { SnapshotCleanupReceipt, SnapshotPartition } from './snapshot-types.mts';
1
+ import type { SnapshotCleanupOwner, SnapshotCleanupReceipt, SnapshotPartition } from './snapshot-types.mts';
2
2
  export declare const RECEIPT_NAME = ".agent-blackboard-cleanup-receipt.json";
3
3
  export declare function serializeCleanupReceipt(receipt: SnapshotCleanupReceipt): string;
4
4
  export declare function sameCleanupReceipt(left: unknown, right: SnapshotCleanupReceipt): boolean;
5
- export declare function writeCleanupReceipt(directory: string, partitions: Array<Pick<SnapshotPartition, 'path' | 'checksum'>>): Promise<SnapshotCleanupReceipt>;
5
+ export declare function writeCleanupReceipt(directory: string, partitions: Array<Pick<SnapshotPartition, 'path' | 'checksum'>>, owner?: SnapshotCleanupOwner): Promise<SnapshotCleanupReceipt>;
6
6
  export declare function verifyCleanupReceipt(receipt: SnapshotCleanupReceipt): Promise<void>;
@@ -9,19 +9,25 @@ function record(value) {
9
9
  function exact(value, keys) {
10
10
  return Object.keys(value).length === keys.length && keys.every((key) => key in value);
11
11
  }
12
+ function canonicalOwner(receipt) {
13
+ if (!('owner' in receipt))
14
+ return {};
15
+ const { owner } = receipt;
16
+ if (!record(owner) ||
17
+ !exact(owner, ['sessionId', 'worktree', 'source']) ||
18
+ !Object.values(owner).every((value) => typeof value === 'string' && value))
19
+ throw new Error('partition directory cleanup receipt is invalid');
20
+ const { sessionId, worktree, source } = owner;
21
+ return { owner: { sessionId, worktree, source } };
22
+ }
12
23
  function canonical(receipt, signature) {
24
+ const base = ['schemaVersion', 'directory', 'directoryDev', 'directoryIno', 'token', 'partitions'];
13
25
  if (!record(receipt) ||
14
- !exact(receipt, signature
15
- ? [
16
- 'schemaVersion',
17
- 'directory',
18
- 'directoryDev',
19
- 'directoryIno',
20
- 'token',
21
- 'partitions',
22
- 'signature',
23
- ]
24
- : ['schemaVersion', 'directory', 'directoryDev', 'directoryIno', 'token', 'partitions']))
26
+ !exact(receipt, [
27
+ ...base,
28
+ ...('owner' in receipt ? ['owner'] : []),
29
+ ...(signature ? ['signature'] : []),
30
+ ]))
25
31
  throw new Error('partition directory cleanup receipt is invalid');
26
32
  const { schemaVersion, directory, directoryDev, directoryIno, token, partitions } = receipt;
27
33
  if (schemaVersion !== 1 ||
@@ -64,6 +70,7 @@ function canonical(receipt, signature) {
64
70
  directoryIno: normalizedDirectoryIno,
65
71
  token,
66
72
  partitions: normalized,
73
+ ...canonicalOwner(receipt),
67
74
  };
68
75
  if (!signature)
69
76
  return JSON.stringify(unsigned);
@@ -85,7 +92,7 @@ export function sameCleanupReceipt(left, right) {
85
92
  return false;
86
93
  }
87
94
  }
88
- export async function writeCleanupReceipt(directory, partitions) {
95
+ export async function writeCleanupReceipt(directory, partitions, owner) {
89
96
  const info = await lstat(directory);
90
97
  const unsigned = {
91
98
  schemaVersion: 1,
@@ -94,6 +101,7 @@ export async function writeCleanupReceipt(directory, partitions) {
94
101
  directoryIno: info.ino,
95
102
  token: randomUUID(),
96
103
  partitions: partitions.map(({ path, checksum }) => ({ name: basename(path), checksum })),
104
+ ...(owner === undefined ? {} : { owner }),
97
105
  };
98
106
  const signature = createHmac('sha256', await loadCleanupSigningKey())
99
107
  .update(payload(unsigned))
@@ -9,5 +9,6 @@ declare const defaults: {
9
9
  rmdir: typeof rmdir;
10
10
  };
11
11
  export declare function setSnapshotCleanupFilesystemForTest(overrides?: Partial<typeof defaults>): void;
12
+ export declare function assertGeneratedPartitionDirectory(path: string): void;
12
13
  export declare function cleanupSnapshotPartitions(options: SnapshotCleanupOptions): Promise<void>;
13
14
  export {};
@@ -18,6 +18,9 @@ function assertGeneratedPath(path, expression, label) {
18
18
  !expression.test(basename(path)))
19
19
  throw new Error(`${label} must be a generated temporary ${label}`);
20
20
  }
21
+ export function assertGeneratedPartitionDirectory(path) {
22
+ assertGeneratedPath(path, DIRECTORY_NAME, 'partition directory');
23
+ }
21
24
  async function removeCaptured(path, expression, directory, receipt) {
22
25
  const label = directory ? 'partition directory' : 'snapshot path';
23
26
  assertGeneratedPath(path, expression, label);
@@ -86,7 +86,7 @@ export async function partitionSnapshot(options) {
86
86
  return {
87
87
  directory: directory,
88
88
  partitions,
89
- cleanupReceipt: await writeCleanupReceipt(directory, partitions),
89
+ cleanupReceipt: await writeCleanupReceipt(directory, partitions, options.owner),
90
90
  };
91
91
  }
92
92
  catch (error) {
@@ -37,6 +37,7 @@ export type SnapshotPartitionOptions = {
37
37
  counts?: SnapshotCounts;
38
38
  maxSessions?: number;
39
39
  maxBytes?: number;
40
+ owner?: SnapshotCleanupOwner;
40
41
  };
41
42
  export type SnapshotPartition = {
42
43
  path: string;
@@ -44,6 +45,12 @@ export type SnapshotPartition = {
44
45
  checksum: SnapshotChecksum;
45
46
  manifest: SnapshotManifest;
46
47
  };
48
+ /** Who exported a snapshot and the generated file it came from, signed into the receipt. */
49
+ export type SnapshotCleanupOwner = {
50
+ sessionId: string;
51
+ worktree: string;
52
+ source: string;
53
+ };
47
54
  export type SnapshotCleanupReceipt = {
48
55
  schemaVersion: 1;
49
56
  directory: string;
@@ -54,6 +61,7 @@ export type SnapshotCleanupReceipt = {
54
61
  name: string;
55
62
  checksum: SnapshotChecksum;
56
63
  }>;
64
+ owner?: SnapshotCleanupOwner;
57
65
  signature: string;
58
66
  };
59
67
  export type SnapshotPartitionResult = {
@@ -10,6 +10,8 @@ export type UnparsedReport = {
10
10
  marker: RegExp;
11
11
  note: (count: number) => string;
12
12
  };
13
+ /** How many blocks in the entries conform to the grammar `match` checks. */
14
+ export declare function countConformingBlocks(entries: Iterable<JournalEntry>, match: (markdown: string, render: AuditRender) => string | null): number;
13
15
  /**
14
16
  * Matches every journal block whole while together they fit `totalBudgetBytes`. Otherwise it keeps
15
17
  * the leading blocks that fit an equal share of the total and appends `omission(count)` — itself a
@@ -62,6 +62,18 @@ function splitBlocks(markdown) {
62
62
  }
63
63
  return chunks.map((chunk) => chunk.join('\n'));
64
64
  }
65
+ function journalBlocks(entries) {
66
+ return [...entries].flatMap((entry) => {
67
+ const data = entry?.data;
68
+ return data?.type === 'journal' && typeof data.markdown === 'string'
69
+ ? splitBlocks(data.markdown)
70
+ : [];
71
+ });
72
+ }
73
+ /** How many blocks in the entries conform to the grammar `match` checks. */
74
+ export function countConformingBlocks(entries, match) {
75
+ return journalBlocks(entries).filter((markdown) => match(markdown, {}) !== null).length;
76
+ }
65
77
  /**
66
78
  * Matches every journal block whole while together they fit `totalBudgetBytes`. Otherwise it keeps
67
79
  * the leading blocks that fit an equal share of the total and appends `omission(count)` — itself a
@@ -70,14 +82,7 @@ function splitBlocks(markdown) {
70
82
  */
71
83
  export function conformingBlocks(entries, match, totalBudgetBytes, redact, omission, unparsed) {
72
84
  let unparsedCount = 0;
73
- const markdowns = [...entries]
74
- .flatMap((entry) => {
75
- const data = entry?.data;
76
- return data?.type === 'journal' && typeof data.markdown === 'string'
77
- ? splitBlocks(data.markdown)
78
- : [];
79
- })
80
- .filter((markdown) => {
85
+ const markdowns = journalBlocks(entries).filter((markdown) => {
81
86
  if (match(markdown, { redact }) !== null)
82
87
  return true;
83
88
  if (unparsed?.marker.test(markdown))
@@ -1,6 +1,10 @@
1
1
  import type { JournalEntry } from './types.mts';
2
2
  import type { AuditRedactor } from './text.mts';
3
+ /** The optional scope line that follows a section's Status line. */
4
+ export declare const lineOf: (note?: string) => string;
3
5
  export declare function isConformingCiFailureBlock(markdown: string): boolean;
4
6
  export declare function getConformingGroups(entries: Iterable<JournalEntry>, redact?: AuditRedactor, maxBytes?: number): string[];
5
- export declare function incompleteCiSection(markdownBlocks: string[]): string;
6
- export declare function buildCiFailuresSection(markdownBlocks: string[]): string;
7
+ /** How many CI failure blocks the entries hold, for reporting the ones a scope left out. */
8
+ export declare function countCiFailureBlocks(entries: Iterable<JournalEntry>): number;
9
+ export declare function incompleteCiSection(markdownBlocks: string[], note?: string): string;
10
+ export declare function buildCiFailuresSection(markdownBlocks: string[], note?: string): string;
@@ -1,8 +1,10 @@
1
- import { conformingBlocks, matchAuditBlock } from "./audit-block.mjs";
1
+ import { conformingBlocks, countConformingBlocks, matchAuditBlock } from "./audit-block.mjs";
2
2
  const GROUP_HEADER = /^- `(recurring|one-off)` — `GitHub Actions` — .*[^\s]$/;
3
3
  const EVIDENCE = /^ {2}- Evidence: .*[^\s]$/;
4
4
  const ROOT_DIAGNOSTIC = /^ {2}- Root diagnostic: .*[^\s]$/;
5
5
  const DISPOSITION = /^ {2}- Disposition: .*[^\s]$/;
6
+ /** The optional scope line that follows a section's Status line. */
7
+ export const lineOf = (note) => (note === undefined ? '' : `\n${note}`);
6
8
  const CI_FAILURES_HEADER = '## CI Failures';
7
9
  const CI_FAILURE_BLOCK_MAX_BYTES = 10_000;
8
10
  const FIELD_PREFIXES = [
@@ -47,14 +49,18 @@ export function isConformingCiFailureBlock(markdown) {
47
49
  export function getConformingGroups(entries, redact, maxBytes = CI_SECTION_MAX_BYTES) {
48
50
  return conformingBlocks(entries, matchBlock, Math.min(maxBytes, CI_SECTION_MAX_BYTES), redact, omissionGroup, UNPARSED);
49
51
  }
50
- export function incompleteCiSection(markdownBlocks) {
52
+ /** How many CI failure blocks the entries hold, for reporting the ones a scope left out. */
53
+ export function countCiFailureBlocks(entries) {
54
+ return countConformingBlocks(entries, matchBlock);
55
+ }
56
+ export function incompleteCiSection(markdownBlocks, note) {
51
57
  return [
52
- `${CI_FAILURES_HEADER}\nStatus: unavailable (journal scan incomplete)`,
58
+ `${CI_FAILURES_HEADER}\nStatus: unavailable (journal scan incomplete)${lineOf(note)}`,
53
59
  ...markdownBlocks,
54
60
  ].join('\n\n');
55
61
  }
56
- export function buildCiFailuresSection(markdownBlocks) {
62
+ export function buildCiFailuresSection(markdownBlocks, note) {
57
63
  if (markdownBlocks.length === 0)
58
- return `${CI_FAILURES_HEADER}\nStatus: none observed`;
59
- return `${CI_FAILURES_HEADER}\nStatus: failures observed\n\n${markdownBlocks.join('\n\n')}`;
64
+ return `${CI_FAILURES_HEADER}\nStatus: none observed${lineOf(note)}`;
65
+ return `${CI_FAILURES_HEADER}\nStatus: failures observed${lineOf(note)}\n\n${markdownBlocks.join('\n\n')}`;
60
66
  }
@@ -1,7 +1,9 @@
1
1
  import type { JournalEntry, JournalLoader } from './types.mts';
2
+ import type { SavedRetrospective } from './scope.mts';
2
3
  export type JournalScan = {
3
4
  status: 'ok';
4
5
  entries: JournalEntry[];
6
+ retrospectives: SavedRetrospective[];
5
7
  truncated: boolean;
6
8
  } | {
7
9
  status: 'not-found';
@@ -4,7 +4,14 @@ const JOURNAL_TOTAL_MAX_BYTES = 1_000_000;
4
4
  function journalData(entry) {
5
5
  try {
6
6
  const data = entry?.data;
7
- return data ? { type: data.type, markdown: data.markdown } : undefined;
7
+ return data
8
+ ? {
9
+ type: data.type,
10
+ markdown: data.markdown,
11
+ sourceEventId: data.sourceEventId,
12
+ createdAt: entry.createdAt,
13
+ }
14
+ : undefined;
8
15
  }
9
16
  catch {
10
17
  return 'unreadable';
@@ -12,6 +19,7 @@ function journalData(entry) {
12
19
  }
13
20
  async function collectEntries(entries) {
14
21
  const result = [];
22
+ const retrospectives = [];
15
23
  let consumed = 0;
16
24
  let inspectedBytes = 0;
17
25
  let retainedBytes = 0;
@@ -23,6 +31,10 @@ async function collectEntries(entries) {
23
31
  truncated = true;
24
32
  const data = scanned === 'unreadable' ? undefined : scanned;
25
33
  const markdown = data?.markdown;
34
+ if (data?.type === 'retrospective' &&
35
+ typeof data.sourceEventId === 'string' &&
36
+ typeof data.createdAt === 'string')
37
+ retrospectives.push({ sourceEventId: data.sourceEventId, createdAt: data.createdAt });
26
38
  if (data?.type === 'journal' && typeof markdown !== 'string')
27
39
  truncated = true;
28
40
  if (data?.type === 'journal' && typeof markdown === 'string') {
@@ -31,7 +43,10 @@ async function collectEntries(entries) {
31
43
  if (bytes > JOURNAL_MARKDOWN_MAX_BYTES)
32
44
  truncated = true;
33
45
  if (bytes <= JOURNAL_MARKDOWN_MAX_BYTES && retainedBytes + bytes <= JOURNAL_TOTAL_MAX_BYTES) {
34
- result.push({ data: { type: 'journal', markdown } });
46
+ result.push({
47
+ ...(typeof data.createdAt === 'string' ? { createdAt: data.createdAt } : {}),
48
+ data: { type: 'journal', markdown },
49
+ });
35
50
  retainedBytes += bytes;
36
51
  }
37
52
  }
@@ -42,7 +57,7 @@ async function collectEntries(entries) {
42
57
  break;
43
58
  }
44
59
  }
45
- return { entries: result, truncated };
60
+ return { entries: result, retrospectives, truncated };
46
61
  }
47
62
  function errorMessage(error) {
48
63
  try {
@@ -0,0 +1,25 @@
1
+ import type { JournalEntry } from './types.mts';
2
+ /** A retrospective already saved in the session, with the blackboard's creation time for it. */
3
+ export type SavedRetrospective = {
4
+ sourceEventId: string;
5
+ createdAt: string;
6
+ };
7
+ export type JournalScope = {
8
+ included: JournalEntry[];
9
+ excluded: JournalEntry[];
10
+ /** The retrospective whose time bounds the scope; absent when every entry is in scope. */
11
+ boundary?: SavedRetrospective;
12
+ };
13
+ /**
14
+ * Keeps only the entries created after the boundary retrospective, so a later retrospective does
15
+ * not repeat what an earlier one already reported.
16
+ *
17
+ * The boundary is the newest saved retrospective created before the newest entry that holds an
18
+ * audit block. A new composition therefore starts after the latest retrospective (it is older than
19
+ * the newest block), while a revision of the latest retrospective, which has no block after it,
20
+ * falls back to the retrospective before it and so keeps its own blocks. The rule cannot tell a
21
+ * revision from a new retrospective with no new blocks: both repeat the blocks since the one
22
+ * before. Entries without a usable `createdAt` are never excluded, because nothing shows they are
23
+ * older. With no earlier retrospective, or no block, nothing is excluded.
24
+ */
25
+ export declare function scopeSinceRetrospective(entries: JournalEntry[], retrospectives: SavedRetrospective[]): JournalScope;
@@ -0,0 +1,47 @@
1
+ const AUDIT_BLOCK = /^- `(?:recurring|one-off|sandbox-escalation|sandbox-failure|ambiguous-failure)`/m;
2
+ function createdAtOf(entry) {
3
+ return typeof entry.createdAt === 'string' ? entry.createdAt : undefined;
4
+ }
5
+ function hasAuditBlock(entry) {
6
+ const markdown = entry.data?.markdown;
7
+ return typeof markdown === 'string' && AUDIT_BLOCK.test(markdown);
8
+ }
9
+ function newest(items, at) {
10
+ let best;
11
+ for (const item of items) {
12
+ const time = at(item);
13
+ if (time !== undefined && (best === undefined || time > at(best)))
14
+ best = item;
15
+ }
16
+ return best;
17
+ }
18
+ /**
19
+ * Keeps only the entries created after the boundary retrospective, so a later retrospective does
20
+ * not repeat what an earlier one already reported.
21
+ *
22
+ * The boundary is the newest saved retrospective created before the newest entry that holds an
23
+ * audit block. A new composition therefore starts after the latest retrospective (it is older than
24
+ * the newest block), while a revision of the latest retrospective, which has no block after it,
25
+ * falls back to the retrospective before it and so keeps its own blocks. The rule cannot tell a
26
+ * revision from a new retrospective with no new blocks: both repeat the blocks since the one
27
+ * before. Entries without a usable `createdAt` are never excluded, because nothing shows they are
28
+ * older. With no earlier retrospective, or no block, nothing is excluded.
29
+ */
30
+ export function scopeSinceRetrospective(entries, retrospectives) {
31
+ const newestBlock = newest(entries.filter(hasAuditBlock), createdAtOf);
32
+ const blockAt = newestBlock === undefined ? undefined : createdAtOf(newestBlock);
33
+ const boundary = blockAt === undefined
34
+ ? undefined
35
+ : newest(retrospectives.filter((retrospective) => retrospective.createdAt < blockAt), (retrospective) => retrospective.createdAt);
36
+ if (boundary === undefined)
37
+ return { included: entries, excluded: [] };
38
+ const isLater = (entry) => {
39
+ const at = createdAtOf(entry);
40
+ return at === undefined || at > boundary.createdAt;
41
+ };
42
+ return {
43
+ included: entries.filter(isLater),
44
+ excluded: entries.filter((entry) => !isLater(entry)),
45
+ boundary,
46
+ };
47
+ }
@@ -1,7 +1,10 @@
1
1
  export type JournalEntry = {
2
+ /** Service-generated ISO 8601 UTC time the entry was created, as the blackboard returns it. */
3
+ createdAt?: unknown;
2
4
  data?: {
3
5
  type?: unknown;
4
6
  markdown?: unknown;
7
+ sourceEventId?: unknown;
5
8
  };
6
9
  };
7
10
  export type JournalLoadResult = {
@@ -2,8 +2,6 @@
2
2
  import { realpathSync } from 'node:fs';
3
3
  import { resolve } from 'node:path';
4
4
  import { pathToFileURL } from 'node:url';
5
- import { runPostReviewCli } from "../gha-post-review/cli.mjs";
6
- import { runStageReviewPayloadCli } from "../gha-review-payload/cli.mjs";
7
5
  import { runSwiftSemanticEqualCli } from "../swift-semantic-equal/cli.mjs";
8
6
  import { runAgentIssueLabels } from "./commands/agent-issue-labels.mjs";
9
7
  import { runGhaArtifactsCleanup } from "./commands/gha-artifacts-cleanup.mjs";
@@ -90,10 +88,6 @@ export function runCli(argv = process.argv) {
90
88
  return runDeadCodeCli(parsed.args);
91
89
  case 'swift-semantic-equal':
92
90
  return runSwiftSemanticEqualCli(parsed.args);
93
- case 'post-review':
94
- return runPostReviewCli();
95
- case 'stage-review-payload':
96
- return runStageReviewPayloadCli(parsed.args);
97
91
  case 'http-origin':
98
92
  return runHttpOrigin(parsed.field, parsed.value);
99
93
  case 'gha-artifacts-cleanup':
@@ -1,4 +1,4 @@
1
- declare const FORWARDED: readonly ["with-host-lock", "host-storage", "pnpm-install", "vitest-blob-manifest", "vitest-report-attempt", "prepare-vitest-reports", "nuget-central-version", "verify-workflow-secrets", "runner-policy", "dead-code", "swift-semantic-equal", "post-review", "stage-review-payload", "retrospective-transcript", "retrospective-facts", "agent-blackboard", "mcp", "hook", "worktree", "transient-retry", "sandbox-command-audit", "cloc", "coverage-scope-check", "trivy-policy", "docker-image-mirror", "workspace-registry-check", "storybook-browser-runner", "tmux", "final-review"];
1
+ declare const FORWARDED: readonly ["with-host-lock", "host-storage", "pnpm-install", "vitest-blob-manifest", "vitest-report-attempt", "prepare-vitest-reports", "nuget-central-version", "verify-workflow-secrets", "runner-policy", "dead-code", "swift-semantic-equal", "retrospective-transcript", "retrospective-facts", "agent-blackboard", "mcp", "hook", "worktree", "transient-retry", "sandbox-command-audit", "cloc", "coverage-scope-check", "trivy-policy", "docker-image-mirror", "workspace-registry-check", "storybook-browser-runner", "tmux", "final-review"];
2
2
  type Name = (typeof FORWARDED)[number];
3
3
  type ForwardedCommand = {
4
4
  [K in Name]: {
@@ -10,8 +10,6 @@ const FORWARDED = [
10
10
  'runner-policy',
11
11
  'dead-code',
12
12
  'swift-semantic-equal',
13
- 'post-review',
14
- 'stage-review-payload',
15
13
  'retrospective-transcript',
16
14
  'retrospective-facts',
17
15
  'agent-blackboard',
@@ -53,12 +53,6 @@ export type ParsedCli = {
53
53
  } | {
54
54
  kind: 'swift-semantic-equal';
55
55
  args: string[];
56
- } | {
57
- kind: 'post-review';
58
- args: string[];
59
- } | {
60
- kind: 'stage-review-payload';
61
- args: string[];
62
56
  } | {
63
57
  kind: 'http-origin';
64
58
  field: string;
@@ -141,7 +135,7 @@ export type ParsedCli = {
141
135
  workflowDirectories?: string[];
142
136
  actionDirectories?: string[];
143
137
  } | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup | ParsedAgentIssueLabels | ParsedStoryCoverage;
144
- export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'download-optional-run-artifacts' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release' | 'run-with-timeout' | 'lint-links' | 'materialize-pr-context' | 'wait-for-apt-locks' | 'install-playwright-chromium-arm64' | 'ghcr-package-retention' | 'harness-admission-lane' | 'gha-collaborator-trust';
138
+ export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'download-optional-run-artifacts' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release' | 'run-with-timeout' | 'lint-links' | 'wait-for-apt-locks' | 'install-playwright-chromium-arm64' | 'ghcr-package-retention' | 'harness-admission-lane' | 'gha-collaborator-trust';
145
139
  export declare function parseCli(argv: readonly string[]): ParsedCli;
146
140
  export declare function parseCommandHelp(command: string | undefined, rest: readonly string[]): {
147
141
  kind: 'command-help';
@@ -22,7 +22,6 @@ const SCRIPT_COMMANDS = new Set([
22
22
  'install-github-release',
23
23
  'run-with-timeout',
24
24
  'lint-links',
25
- 'materialize-pr-context',
26
25
  'wait-for-apt-locks',
27
26
  'install-playwright-chromium-arm64',
28
27
  'ghcr-package-retention',
@@ -29,7 +29,6 @@ export const SCRIPT_PATHS = {
29
29
  'install-github-release': { command: 'bash', path: 'scripts/gha/install-github-release.sh' },
30
30
  'run-with-timeout': { command: 'bash', path: 'scripts/gha/run-with-timeout.sh' },
31
31
  'lint-links': { command: 'bash', path: 'scripts/gha/lint-links.sh' },
32
- 'materialize-pr-context': { command: 'bash', path: 'scripts/gha/materialize-pr-context.sh' },
33
32
  'wait-for-apt-locks': { command: 'bash', path: 'scripts/gha/wait-for-apt-locks.sh' },
34
33
  'install-playwright-chromium-arm64': {
35
34
  command: 'bash',