vouchington-tooling 3.4.1 → 3.5.1

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 (37) hide show
  1. package/dist/mcp-server/handlers-retrospective-save.d.mts +1 -1
  2. package/dist/mcp-server/handlers-retrospective-save.mjs +8 -1
  3. package/dist/mcp-server/retrospective-sections.test-helpers.d.mts +4 -0
  4. package/dist/mcp-server/retrospective-sections.test-helpers.mjs +29 -0
  5. package/dist/mcp-server/retrospective-validate-assessments.d.mts +2 -0
  6. package/dist/mcp-server/retrospective-validate-assessments.mjs +51 -0
  7. package/dist/mcp-server/retrospective-validate-ci.d.mts +4 -0
  8. package/dist/mcp-server/retrospective-validate-ci.mjs +79 -0
  9. package/dist/mcp-server/retrospective-validate.d.mts +6 -0
  10. package/dist/mcp-server/retrospective-validate.mjs +35 -0
  11. package/dist/triage-loop-scripts.test-helpers.d.mts +53 -0
  12. package/dist/triage-loop-scripts.test-helpers.mjs +143 -0
  13. package/docs/mcp-server.md +17 -1
  14. package/package.json +3 -3
  15. package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
  16. package/skills/blackboard/SKILL.md +2 -0
  17. package/skills/blackboard/references/session-id.md +14 -0
  18. package/skills/manifest.json +9 -9
  19. package/skills/retrospective/SKILL.md +6 -2
  20. package/skills/retrospective/references/pr-feedback.md +45 -0
  21. package/skills/retrospective/references/sandbox-audit.md +44 -0
  22. package/skills/retrospective-distill/SKILL.md +6 -3
  23. package/skills/triage-loop/SKILL.md +43 -8
  24. package/skills/triage-loop/references/config.md +4 -2
  25. package/skills/triage-loop/scripts/__pycache__/events.cpython-314.pyc +0 -0
  26. package/skills/triage-loop/scripts/__pycache__/late_review.cpython-314.pyc +0 -0
  27. package/skills/triage-loop/scripts/__pycache__/state.cpython-314.pyc +0 -0
  28. package/skills/triage-loop/scripts/__pycache__/update_check.cpython-314.pyc +0 -0
  29. package/skills/triage-loop/scripts/events.py +120 -0
  30. package/skills/triage-loop/scripts/late_review.py +78 -0
  31. package/skills/triage-loop/scripts/state.py +79 -11
  32. package/skills/triage-loop/scripts/update_check.py +35 -0
  33. package/skills/triage-loop/scripts/wait.py +98 -36
  34. package/skills/triage-prs/SKILL.md +2 -2
  35. package/skills/triage-prs/references/feedback.md +4 -1
  36. package/skills/triage-sweep/SKILL.md +2 -1
  37. package/skills/triage-sweep/references/dependency-update-check.md +6 -3
@@ -3,7 +3,7 @@ import { type ToolHandler } from './context.mts';
3
3
  export declare function defaultSourceEventId(sessionId: string): string;
4
4
  /**
5
5
  * Saves the session's retrospective: composes it when `compose` is given, checks the arguments
6
- * against the document's front matter, runs the checkout's `validateRetrospective` policy (in a
6
+ * against the document's front matter, checks a hand-written document's sections, runs the checkout's `validateRetrospective` policy (in a
7
7
  * child process) and writes nothing if it reports errors, then writes through the same verified
8
8
  * path as `journal_append`.
9
9
  */
@@ -9,6 +9,7 @@ import { deliver, saveFromPreview } from "./retrospective-preview.mjs";
9
9
  import { parseRetrospectiveFrontMatter } from "./retrospective-front-matter.mjs";
10
10
  import { FEEDBACK_MARKDOWN_MAX_BYTES, redactFeedbackText, } from "../agent-blackboard/feedback-codec.mjs";
11
11
  import { composeFromArgs, sensitiveValues } from "./retrospective-input.mjs";
12
+ import { validateRetrospectiveMarkdown } from "./retrospective-validate.mjs";
12
13
  import { checkFrontMatter, resolveRepositories } from "./retrospective-resolve.mjs";
13
14
  function readMarkdownSource(args) {
14
15
  const compose = optionalRecord(args, 'compose');
@@ -25,7 +26,7 @@ export function defaultSourceEventId(sessionId) {
25
26
  }
26
27
  /**
27
28
  * Saves the session's retrospective: composes it when `compose` is given, checks the arguments
28
- * against the document's front matter, runs the checkout's `validateRetrospective` policy (in a
29
+ * against the document's front matter, checks a hand-written document's sections, runs the checkout's `validateRetrospective` policy (in a
29
30
  * child process) and writes nothing if it reports errors, then writes through the same verified
30
31
  * path as `journal_append`.
31
32
  */
@@ -98,6 +99,12 @@ export const retrospectiveSave = async (args, context) => {
98
99
  }, { knownSensitiveValues: secrets });
99
100
  const redactedFront = parseRetrospectiveFrontMatter(envelope.markdown);
100
101
  validateFeedbackEnvelope(envelope);
102
+ // Composed documents conform by construction; a hand-written one is checked before any policy.
103
+ if (given !== undefined) {
104
+ const problems = validateRetrospectiveMarkdown(envelope.markdown, envelope.feedbackCoverage.status);
105
+ if (problems.length)
106
+ throw new Error(`retrospective markdown is malformed:\n- ${problems.join('\n- ')}`);
107
+ }
101
108
  const report = await runValidator({
102
109
  ...policy,
103
110
  export: 'validateRetrospective',
@@ -0,0 +1,4 @@
1
+ /** The sections a hand-written retrospective needs, every source fully assessed. */
2
+ export declare const ASSESSED_SECTIONS: string;
3
+ /** The same sections with every source marked as not assessed. */
4
+ export declare const UNASSESSED_SECTIONS: string;
@@ -0,0 +1,29 @@
1
+ /** The sections a hand-written retrospective needs, every source fully assessed. */
2
+ export const ASSESSED_SECTIONS = [
3
+ '## Verifiable Facts',
4
+ '=== Retrospective Facts ===',
5
+ 'PR: 5',
6
+ '',
7
+ '## Transcript Facts',
8
+ '=== Transcript Facts ===',
9
+ 'User prompts: 3',
10
+ '',
11
+ '## CI Failures',
12
+ 'Status: none observed',
13
+ '',
14
+ '## Sandbox & Permission Audit',
15
+ 'Status: none observed (journal entries only)',
16
+ '',
17
+ '## Tool Findings',
18
+ 'Status: none observed (read the tool results)',
19
+ '',
20
+ '## Architecture Findings',
21
+ 'Status: none observed (read the changed modules)',
22
+ ].join('\n');
23
+ /** The same sections with every source marked as not assessed. */
24
+ export const UNASSESSED_SECTIONS = ASSESSED_SECTIONS.replace('PR: 5', 'Status: unavailable (n/a)')
25
+ .replace('User prompts: 3', 'Status: not assessed (no transcript)')
26
+ .replace('Status: none observed\n', 'Status: unavailable (not assessed)\n')
27
+ .replace('Status: none observed (journal entries only)', 'Status: unavailable (not assessed)')
28
+ .replace('Status: none observed (read the tool results)', 'Status: not assessed (skipped)')
29
+ .replace('Status: none observed (read the changed modules)', 'Status: not assessed (skipped)');
@@ -0,0 +1,2 @@
1
+ /** Checks `## Tool Findings` and `## Architecture Findings`: one status, evidence per finding. */
2
+ export declare function validateAssessments(lines: string[]): string[];
@@ -0,0 +1,51 @@
1
+ import { sectionBody } from "./retrospective-validate-ci.mjs";
2
+ const NON_FINDING = /^Status: (?:none observed|not assessed|unavailable) \(.*\S.*\)$/;
3
+ const FINDINGS = /^Status: findings(?: \(.*\S.*\))?$/;
4
+ const STATUS_MAX_BYTES = 320;
5
+ function findingErrors(header, section, bullets) {
6
+ return bullets.flatMap((position, index) => {
7
+ const group = section.slice(position + 1, bullets[index + 1]);
8
+ const missing = ['Evidence', 'Disposition'].filter((field) => !group.some((line) => new RegExp(`^ {2}- ${field}: .*\\S$`).test(line)));
9
+ return missing.length
10
+ ? [
11
+ `"${header}" finding ${JSON.stringify(section[position])} is missing ${missing.map((field) => `" - ${field}: ..."`).join(' and ')}`,
12
+ ]
13
+ : [];
14
+ });
15
+ }
16
+ function sectionErrors(header, section) {
17
+ const statuses = section.filter((line) => line.startsWith('Status: '));
18
+ if (statuses.length !== 1)
19
+ return [`"${header}" needs exactly one "Status: " line (found ${statuses.length})`];
20
+ const status = statuses[0];
21
+ if (Buffer.byteLength(status) > STATUS_MAX_BYTES)
22
+ return [`"${header}" status must be at most ${STATUS_MAX_BYTES} bytes`];
23
+ const bullets = section.flatMap((line, index) => (/^- .+\S$/.test(line) ? [index] : []));
24
+ if (NON_FINDING.test(status))
25
+ return bullets.length
26
+ ? [`"${header}" lists findings but its status says there are none; use "Status: findings"`]
27
+ : [];
28
+ if (!FINDINGS.test(status))
29
+ return [
30
+ `"${header}" status must be "Status: findings", or "Status: none observed|not assessed|unavailable (<reason>)" with a non-blank reason`,
31
+ ];
32
+ if (bullets.length === 0)
33
+ return [
34
+ `"${header}" says "Status: findings" but lists no finding; add "- <observation>" bullets`,
35
+ ];
36
+ return findingErrors(header, section, bullets);
37
+ }
38
+ /** Checks `## Tool Findings` and `## Architecture Findings`: one status, evidence per finding. */
39
+ export function validateAssessments(lines) {
40
+ return ['Tool Findings', 'Architecture Findings'].flatMap((title) => {
41
+ const header = `## ${title}`;
42
+ const starts = lines.flatMap((line, index) => (line === header ? [index] : []));
43
+ if (starts.length !== 1)
44
+ return [
45
+ starts.length === 0
46
+ ? `missing "${header}" section`
47
+ : `"${header}" must appear exactly once`,
48
+ ];
49
+ return sectionErrors(header, sectionBody(lines, starts[0]));
50
+ });
51
+ }
@@ -0,0 +1,4 @@
1
+ /** The lines of the section whose header is at `start`, up to the next `## ` header. */
2
+ export declare function sectionBody(lines: string[], start: number): string[];
3
+ /** Checks `## CI Failures`: placement after Transcript Facts, one Status line, and group grammar. */
4
+ export declare function validateCiFailures(lines: string[]): string[];
@@ -0,0 +1,79 @@
1
+ const CI_HEADER = '## CI Failures';
2
+ const TRANSCRIPT_HEADER = '## Transcript Facts';
3
+ const GROUP = /^- `(?:recurring|one-off)` — `(.+?)` — .*[^\s]$/;
4
+ const FIELDS = [
5
+ /^ {2}- Evidence: .*[^\s]$/,
6
+ /^ {2}- Root diagnostic: .*[^\s]$/,
7
+ /^ {2}- Disposition: .*[^\s]$/,
8
+ ];
9
+ const EXCLUDED_NOTE = /^Excluded: .*[^\s]$/;
10
+ const UNAVAILABLE = /^Status: unavailable \(.*\S.*\)$/;
11
+ const SOURCE = 'GitHub Actions';
12
+ const STATUS_CHOICES = '"Status: failures observed", "Status: none observed", or "Status: unavailable (<non-blank reason>)"';
13
+ /** The lines of the section whose header is at `start`, up to the next `## ` header. */
14
+ export function sectionBody(lines, start) {
15
+ const next = lines.findIndex((line, index) => index > start && line.startsWith('## '));
16
+ return lines.slice(start + 1, next < 0 ? undefined : next);
17
+ }
18
+ function groupsOf(body) {
19
+ const groups = [];
20
+ const unexpected = [];
21
+ for (const line of body) {
22
+ const header = GROUP.exec(line);
23
+ const current = groups.at(-1);
24
+ if (header)
25
+ groups.push({ source: header[1], fields: 0 });
26
+ else if (current && FIELDS[current.fields]?.test(line))
27
+ current.fields++;
28
+ else if (!/^\s*$/.test(line) && !line.startsWith('Status: ') && !EXCLUDED_NOTE.test(line))
29
+ unexpected.push(line);
30
+ }
31
+ return { groups, unexpected };
32
+ }
33
+ function statusErrors(statuses, groupCount) {
34
+ if (statuses.length !== 1)
35
+ return [
36
+ `"${CI_HEADER}" must contain exactly one "Status: " line (found ${statuses.length}); use ${STATUS_CHOICES}`,
37
+ ];
38
+ const status = statuses[0];
39
+ if (status === 'Status: failures observed')
40
+ return groupCount === 0
41
+ ? [`"Status: failures observed" requires at least one failure group under "${CI_HEADER}"`]
42
+ : [];
43
+ if (status === 'Status: none observed')
44
+ return groupCount > 0
45
+ ? [
46
+ `failure groups are present but "${CI_HEADER}" says "Status: none observed"; use "Status: failures observed"`,
47
+ ]
48
+ : [];
49
+ if (UNAVAILABLE.test(status))
50
+ return [];
51
+ return [`"${CI_HEADER}" status ${JSON.stringify(status)} is invalid; use ${STATUS_CHOICES}`];
52
+ }
53
+ /** Checks `## CI Failures`: placement after Transcript Facts, one Status line, and group grammar. */
54
+ export function validateCiFailures(lines) {
55
+ const starts = lines.flatMap((line, index) => (line === CI_HEADER ? [index] : []));
56
+ if (starts.length !== 1)
57
+ return [
58
+ starts.length === 0
59
+ ? `missing "${CI_HEADER}" section header`
60
+ : `"${CI_HEADER}" must appear exactly once`,
61
+ ];
62
+ const start = starts[0];
63
+ const errors = [];
64
+ const transcript = lines.indexOf(TRANSCRIPT_HEADER);
65
+ const between = lines.slice(transcript + 1, start).some((line) => line.startsWith('## '));
66
+ if (transcript >= 0 && (transcript > start || between))
67
+ errors.push(`"${CI_HEADER}" must come immediately after "${TRANSCRIPT_HEADER}"`);
68
+ const body = sectionBody(lines, start);
69
+ const { groups, unexpected } = groupsOf(body);
70
+ errors.push(...statusErrors(body.filter((line) => line.startsWith('Status: ')), groups.length));
71
+ if (groups.some((group) => group.fields < FIELDS.length))
72
+ errors.push('each failure group needs indented " - Evidence:", " - Root diagnostic:" and " - Disposition:" lines, in that order, each non-blank');
73
+ const other = [...new Set(groups.map((group) => group.source))].filter((source) => source !== SOURCE);
74
+ if (other.length)
75
+ errors.push(`failure group source must be \`${SOURCE}\`, not ${other.map((name) => `\`${name}\``).join(', ')}`);
76
+ if (unexpected.length)
77
+ errors.push(`unexpected content inside "${CI_HEADER}": ${JSON.stringify(unexpected[0])}; only Status, an optional "Excluded:" note, and failure groups are allowed`);
78
+ return errors;
79
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Checks a hand-written retrospective against the section grammar `composeRetrospective` writes
3
+ * and returns one actionable message per problem (empty when the document conforms). Front
4
+ * matter is checked separately by `parseRetrospectiveFrontMatter`.
5
+ */
6
+ export declare function validateRetrospectiveMarkdown(markdown: string, feedbackCoverageStatus: string): string[];
@@ -0,0 +1,35 @@
1
+ import { validateAssessments } from "./retrospective-validate-assessments.mjs";
2
+ import { validateCiFailures } from "./retrospective-validate-ci.mjs";
3
+ const REQUIRED_LINES = [
4
+ '## Verifiable Facts',
5
+ '=== Retrospective Facts ===',
6
+ '## Transcript Facts',
7
+ '=== Transcript Facts ===',
8
+ ];
9
+ const INCOMPLETE = /^Status: (?:unavailable|not assessed|partial)/;
10
+ /** Lines that say a source was not fully assessed, each with the section it sits in. */
11
+ function incompleteSources(lines) {
12
+ let section = 'the front of the document';
13
+ const found = [];
14
+ for (const line of lines) {
15
+ if (line.startsWith('## ') || line.startsWith('=== '))
16
+ section = `"${line}"`;
17
+ else if (INCOMPLETE.test(line))
18
+ found.push(`${JSON.stringify(line)} in ${section}`);
19
+ }
20
+ return found;
21
+ }
22
+ /**
23
+ * Checks a hand-written retrospective against the section grammar `composeRetrospective` writes
24
+ * and returns one actionable message per problem (empty when the document conforms). Front
25
+ * matter is checked separately by `parseRetrospectiveFrontMatter`.
26
+ */
27
+ export function validateRetrospectiveMarkdown(markdown, feedbackCoverageStatus) {
28
+ const lines = markdown.replaceAll('\r\n', '\n').replaceAll('\r', '\n').split('\n');
29
+ const errors = REQUIRED_LINES.filter((line) => !lines.includes(line)).map((line) => `missing the required line "${line}"`);
30
+ errors.push(...validateCiFailures(lines), ...validateAssessments(lines));
31
+ const incomplete = incompleteSources(lines);
32
+ if (feedbackCoverageStatus === 'complete' && incomplete.length)
33
+ errors.push(`feedbackCoverage "complete" contradicts unassessed sources (${incomplete.join('; ')}); assess them, or save with a feedbackCoverage status other than "complete"`);
34
+ return errors;
35
+ }
@@ -0,0 +1,53 @@
1
+ export declare const updateDoc: string;
2
+ export type Env = ReturnType<typeof makeEnv>;
3
+ export declare function makeEnv(extraConfig?: Record<string, unknown>): {
4
+ writeConfig: (more: Record<string, unknown>) => void;
5
+ run(script: string, ...args: string[]): {
6
+ code: number | null;
7
+ out: string;
8
+ err: string;
9
+ lines: string[];
10
+ };
11
+ mock(name: string, value: unknown): void;
12
+ gql(connection: string, number: number, nodes: unknown[], options?: {
13
+ cursor?: string;
14
+ next?: string;
15
+ pull?: object;
16
+ }): void;
17
+ clean(number: number): void;
18
+ hh(n: number, events: unknown[], extra?: Record<string, unknown>): void;
19
+ state: () => Record<string, any>;
20
+ seed: (value: unknown) => void;
21
+ hhLast: () => Record<string, any>;
22
+ log: (name: string) => string[];
23
+ cleanup: () => void;
24
+ };
25
+ export declare function mergeEvent(id: string, number: number, bot?: boolean): {
26
+ id: string;
27
+ repo: string;
28
+ event: string;
29
+ action: string;
30
+ prs: number[];
31
+ receivedAt: string;
32
+ sender: {
33
+ login: string;
34
+ };
35
+ payload: {
36
+ pull_request: {
37
+ number: number;
38
+ merged: boolean;
39
+ user: {
40
+ login: string;
41
+ };
42
+ };
43
+ };
44
+ };
45
+ export declare const ejection: {
46
+ id: string;
47
+ repo: string;
48
+ event: string;
49
+ action: string;
50
+ reason: string;
51
+ headSha: string;
52
+ prs: number[];
53
+ };
@@ -0,0 +1,143 @@
1
+ import { spawnSync } from 'node:child_process';
2
+ import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
3
+ import { tmpdir } from 'node:os';
4
+ import { dirname, join, resolve } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+ const plugin = resolve(dirname(fileURLToPath(import.meta.url)), '../../../plugins/vouchington-workflow');
7
+ const scripts = join(plugin, 'skills/triage-loop/scripts');
8
+ export const updateDoc = join(plugin, 'skills/triage-sweep/references/dependency-update-check.md');
9
+ // gh: the org repo list, and graphql answers read from gql-<connection>-<number>-<cursor|first>.json.
10
+ const GH = `#!/usr/bin/env python3
11
+ import os, sys
12
+ a, d = sys.argv[1:], os.environ["MOCK_DIR"]
13
+ if a[:2] == ["api", "--paginate"]:
14
+ print(open(d + "/repos").read())
15
+ sys.exit(0)
16
+ if a[0] == "api" and a[1].startswith("repos/"):
17
+ n = a[1].rsplit("/", 1)[1]
18
+ if os.path.exists(f"{d}/merged-{n}.fail"):
19
+ sys.stderr.write("HTTP 404")
20
+ sys.exit(1)
21
+ if os.path.exists(f"{d}/merged-{n}"):
22
+ print("2026-11-20T10:00:00Z")
23
+ sys.exit(0)
24
+ v = {x.partition("=")[0]: x.partition("=")[2] for x in a if "=" in x}
25
+ conn = "reviewThreads" if "reviewThreads(" in v["query"] else "reviews"
26
+ name = f"{d}/gql-{conn}-{v['p']}-{v.get('c', 'first')}.json"
27
+ open(d + "/gh.log", "a").write(name + "\\n")
28
+ if not os.path.exists(name):
29
+ sys.stderr.write("HTTP 502")
30
+ sys.exit(1)
31
+ print(open(name).read())
32
+ `;
33
+ // npx: answers the nth call from hh-<n>.json (exit code from hh-<n>.code) and logs its arguments.
34
+ const NPX = `#!/usr/bin/env python3
35
+ import json, os, sys, time
36
+ d = os.environ["MOCK_DIR"]
37
+ n = int(open(d + "/npx.count").read()) + 1 if os.path.exists(d + "/npx.count") else 1
38
+ open(d + "/npx.count", "w").write(str(n))
39
+ open(d + "/npx.log", "a").write(json.dumps(sys.argv[1:]) + "\\n")
40
+ if os.path.exists(f"{d}/hh-{n}.sleep"):
41
+ time.sleep(float(open(f"{d}/hh-{n}.sleep").read()))
42
+ if os.path.exists(f"{d}/hh-{n}.code"):
43
+ sys.exit(int(open(f"{d}/hh-{n}.code").read()))
44
+ print(open(f"{d}/hh-{n}.json").read())
45
+ `;
46
+ export function makeEnv(extraConfig = {}) {
47
+ const dir = mkdtempSync(join(tmpdir(), 'triage-loop-'));
48
+ const bin = join(dir, 'bin');
49
+ const mock = join(dir, 'mock');
50
+ const stateDir = join(dir, 'state');
51
+ mkdirSync(bin);
52
+ mkdirSync(mock);
53
+ for (const [name, body] of [
54
+ ['gh', GH],
55
+ ['npx', NPX],
56
+ ]) {
57
+ writeFileSync(join(bin, name), body);
58
+ chmodSync(join(bin, name), 0o755);
59
+ }
60
+ writeFileSync(join(mock, 'repos'), 'repo-a\nrepo-b\nother\n');
61
+ const config = join(dir, 'config.json');
62
+ const writeConfig = (more) => writeFileSync(config, JSON.stringify({
63
+ org: 'org',
64
+ repoPrefix: 'repo-',
65
+ stateDir,
66
+ dependencyBot: { author: 'app/dependabot' },
67
+ ...more,
68
+ }));
69
+ writeConfig(extraConfig);
70
+ const env = {
71
+ ...process.env,
72
+ PATH: `${bin}:${process.env.PATH}`,
73
+ MOCK_DIR: mock,
74
+ TRIAGE_LOOP_CONFIG: config,
75
+ };
76
+ return {
77
+ writeConfig,
78
+ run(script, ...args) {
79
+ const done = spawnSync('python3', ['-I', join(scripts, script), ...args], {
80
+ env,
81
+ encoding: 'utf8',
82
+ });
83
+ return {
84
+ code: done.status,
85
+ out: done.stdout,
86
+ err: done.stderr,
87
+ lines: done.stdout.split('\n').filter(Boolean),
88
+ };
89
+ },
90
+ mock(name, value) {
91
+ writeFileSync(join(mock, name), typeof value === 'string' ? value : JSON.stringify(value));
92
+ },
93
+ gql(connection, number, nodes, options = {}) {
94
+ const page = { hasNextPage: Boolean(options.next), endCursor: options.next ?? null };
95
+ const pull = {
96
+ state: 'MERGED',
97
+ mergedAt: '2026-11-20T10:00:00Z',
98
+ [connection]: { pageInfo: page, nodes },
99
+ };
100
+ writeFileSync(join(mock, `gql-${connection}-${number}-${options.cursor ?? 'first'}.json`), JSON.stringify({ data: { repository: { pullRequest: { ...pull, ...options.pull } } } }));
101
+ },
102
+ clean(number) {
103
+ this.gql('reviewThreads', number, [{ isResolved: true }]);
104
+ this.gql('reviews', number, [{ body: 'early', submittedAt: '2026-11-20T09:00:00Z' }]);
105
+ },
106
+ hh(n, events, extra = {}) {
107
+ this.mock(`hh-${n}.json`, { events, gap: false, cursor: `c${n}`, ...extra });
108
+ },
109
+ state: () => JSON.parse(readFileSync(join(stateDir, 'state.json'), 'utf8')),
110
+ seed: (value) => {
111
+ mkdirSync(stateDir, { recursive: true });
112
+ writeFileSync(join(stateDir, 'state.json'), JSON.stringify(value));
113
+ },
114
+ hhLast: () => JSON.parse(readFileSync(join(stateDir, 'hh-last.json'), 'utf8')),
115
+ log: (name) => existsSync(join(mock, name))
116
+ ? readFileSync(join(mock, name), 'utf8').split('\n').filter(Boolean)
117
+ : [],
118
+ cleanup: () => rmSync(dir, { recursive: true, force: true }),
119
+ };
120
+ }
121
+ export function mergeEvent(id, number, bot = false) {
122
+ return {
123
+ id,
124
+ repo: 'org/repo-a',
125
+ event: 'pull_request',
126
+ action: 'closed',
127
+ prs: [number],
128
+ receivedAt: 'x',
129
+ sender: { login: 'jong' },
130
+ payload: {
131
+ pull_request: { number, merged: true, user: { login: bot ? 'dependabot[bot]' : 'jong' } },
132
+ },
133
+ };
134
+ }
135
+ export const ejection = {
136
+ id: 'e1',
137
+ repo: 'org/repo-a',
138
+ event: 'merge_group',
139
+ action: 'destroyed',
140
+ reason: 'failure',
141
+ headSha: 'abc',
142
+ prs: [9],
143
+ };
@@ -285,6 +285,20 @@ repository configuration (which can select helpers that run code), so the worktr
285
285
  `.git/config`, must be as trusted as the policy module. `dryRun`
286
286
  runs every check and returns the document without writing, plus a `previewToken`.
287
287
 
288
+ A `markdown` save is validated by default, with no policy module needed, after front matter and
289
+ argument consistency and before any policy export; one error lists every problem and nothing is
290
+ written. The document must contain the lines `## Verifiable Facts`, `=== Retrospective Facts ===`,
291
+ `## Transcript Facts` and `=== Transcript Facts ===`. `## CI Failures` must appear once, directly
292
+ after `## Transcript Facts`, with exactly one `Status:` line (`failures observed`, which needs a
293
+ group, `none observed`, or `unavailable (<reason>)`), an optional `Excluded:` note, and groups
294
+ written as ``- `recurring|one-off` — `GitHub Actions` — <text>`` followed by indented `Evidence:`,
295
+ `Root diagnostic:` and `Disposition:` lines. `## Tool Findings` and `## Architecture Findings` must
296
+ each appear once with one `Status:` line (`findings`, or `none observed`, `not assessed` or
297
+ `unavailable` with a reason in parentheses); each finding is a `- ` bullet with indented
298
+ `Evidence:` and `Disposition:` lines. A `feedbackCoverage` of `complete` is rejected when any
299
+ `Status:` line starts `unavailable`, `not assessed` or `partial`. The `compose` input produces
300
+ documents that pass these checks, so `compose` saves are not re-checked.
301
+
288
302
  `knownSensitiveValues` (each at least 4 characters) is also accepted beside `markdown`, and
289
303
  redacts the markdown, `category` and `feedbackCoverage` just as `compose.knownSensitiveValues`
290
304
  does; with `compose`, pass it inside `compose`. The `previewToken` is 32 random bytes (base64url),
@@ -324,7 +338,9 @@ blocks because the boundary is the newest retrospective older than the newest bl
324
338
 
325
339
  The consumer's root `package.json` may declare
326
340
  `"vouchington-tooling": { "policy": "dev/agent-policy.mts" }`. The path must be relative and, after
327
- resolving symlinks, stay inside the worktree. Without a declaration the policy checks are skipped.
341
+ resolving symlinks, stay inside the worktree. Without a declaration the policy checks are skipped; the built-in
342
+ `markdown` validation of `retrospective_save` runs either way, before the policy's
343
+ `validateRetrospective`, which adds repository-specific checks.
328
344
  Policy tools also require a server launched inside a repository worktree on macOS or Linux (they
329
345
  refuse to run on Windows, where the server cannot reap a policy's descendants by process group),
330
346
  and refuse to run when `AGENT_BLACKBOARD_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN` is set to a value
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vouchington-tooling",
3
- "version": "3.4.1",
3
+ "version": "3.5.1",
4
4
  "description": "Vouchington CLI and extractable tooling libraries.",
5
5
  "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
6
6
  "bugs": {
@@ -515,7 +515,7 @@
515
515
  "devDependencies": {
516
516
  "@ast-grep/cli": "0.51.2",
517
517
  "@modelcontextprotocol/sdk": "1.32.2",
518
- "@playwright/test": "1.65.0",
518
+ "@playwright/test": "1.65.1",
519
519
  "@types/pg": "8.23.1",
520
520
  "@types/picomatch": "^4.0.3",
521
521
  "@types/react": "19.3.0",
@@ -525,7 +525,7 @@
525
525
  "@vouchington/worker-runtime": "0.3.1",
526
526
  "glide-mq": "^0.20.0",
527
527
  "next": "16.4.6",
528
- "no-mistakes": "0.109.96",
528
+ "no-mistakes": "0.109.109",
529
529
  "pg": "8.23.1",
530
530
  "react": "19.3.1",
531
531
  "react-dom": "19.3.1",
@@ -162,6 +162,8 @@ escalation reported only in the transcript facts leaves it saying none observed.
162
162
 
163
163
  ## Child identity for spawned agents
164
164
 
165
+ - Read [session-id](references/session-id.md) for the harness environment variables that supply
166
+ the root session id, the precedence of an assigned child id, and why no hook starts a session.
165
167
  - Pass the parent's own session id in the assignment prompt. The child resolves its own id from its
166
168
  runtime through the consumer's identity policy, then calls `session_ensure` with it, the given
167
169
  `parentSessionId`, its `agent`, and its version before other work. With no id or a failed ensure,
@@ -0,0 +1,14 @@
1
+ # Session id
2
+
3
+ The root session id is the current harness's own session id, read from its environment:
4
+
5
+ - `CODEX_THREAD_ID`
6
+ - `CLAUDE_CODE_SESSION_ID`
7
+ - `GROK_SESSION_ID`
8
+
9
+ Use only the variable of the harness you are running in. Never use another harness's id or
10
+ synthesize one. An explicitly assigned child id (from the parent's assignment prompt) takes
11
+ precedence over the environment id.
12
+
13
+ No hook starts or journals a session. `session_ensure` and `journal_append` create it on demand, and
14
+ hooks never journal on the agent's behalf.
@@ -4,57 +4,57 @@
4
4
  {
5
5
  "name": "blackboard",
6
6
  "plugin": "vouchington-workflow",
7
- "pluginVersion": "0.26.0",
7
+ "pluginVersion": "0.27.0",
8
8
  "path": "blackboard/SKILL.md"
9
9
  },
10
10
  {
11
11
  "name": "organize-github-issues",
12
12
  "plugin": "vouchington-workflow",
13
- "pluginVersion": "0.26.0",
13
+ "pluginVersion": "0.27.0",
14
14
  "path": "organize-github-issues/SKILL.md"
15
15
  },
16
16
  {
17
17
  "name": "pr-description",
18
18
  "plugin": "vouchington-workflow",
19
- "pluginVersion": "0.26.0",
19
+ "pluginVersion": "0.27.0",
20
20
  "path": "pr-description/SKILL.md"
21
21
  },
22
22
  {
23
23
  "name": "retrospective",
24
24
  "plugin": "vouchington-workflow",
25
- "pluginVersion": "0.26.0",
25
+ "pluginVersion": "0.27.0",
26
26
  "path": "retrospective/SKILL.md"
27
27
  },
28
28
  {
29
29
  "name": "retrospective-distill",
30
30
  "plugin": "vouchington-workflow",
31
- "pluginVersion": "0.26.0",
31
+ "pluginVersion": "0.27.0",
32
32
  "path": "retrospective-distill/SKILL.md"
33
33
  },
34
34
  {
35
35
  "name": "review-github-issue-taxonomy",
36
36
  "plugin": "vouchington-workflow",
37
- "pluginVersion": "0.26.0",
37
+ "pluginVersion": "0.27.0",
38
38
  "path": "review-github-issue-taxonomy/SKILL.md",
39
39
  "prerequisites": ["organize-github-issues"]
40
40
  },
41
41
  {
42
42
  "name": "triage-loop",
43
43
  "plugin": "vouchington-workflow",
44
- "pluginVersion": "0.26.0",
44
+ "pluginVersion": "0.27.0",
45
45
  "path": "triage-loop/SKILL.md"
46
46
  },
47
47
  {
48
48
  "name": "triage-prs",
49
49
  "plugin": "vouchington-workflow",
50
- "pluginVersion": "0.26.0",
50
+ "pluginVersion": "0.27.0",
51
51
  "path": "triage-prs/SKILL.md",
52
52
  "prerequisites": ["pr-description", "retrospective"]
53
53
  },
54
54
  {
55
55
  "name": "triage-sweep",
56
56
  "plugin": "vouchington-workflow",
57
- "pluginVersion": "0.26.0",
57
+ "pluginVersion": "0.27.0",
58
58
  "path": "triage-sweep/SKILL.md",
59
59
  "prerequisites": [
60
60
  "triage-loop",
@@ -69,8 +69,12 @@ answer is `unknown — no journal`, never a guess.
69
69
  `merge-pr<number>`: the writer rejects the retrospective's ID reused for different content.
70
70
  Never write a second retrospective.
71
71
 
72
- Read [ci-failures](references/ci-failures.md) when the session observed CI failures, and
73
- [sandbox-audit](references/sandbox-audit.md) when it hit denied or escalated commands.
72
+ For a pull request in another repository, pass `compose.facts` as
73
+ `{status:"not-assessed", reason}` instead of repository facts.
74
+
75
+ Read [ci-failures](references/ci-failures.md) when the session observed CI failures,
76
+ [sandbox-audit](references/sandbox-audit.md) when it hit denied or escalated commands, and
77
+ [pr-feedback](references/pr-feedback.md) when a PR-triage caller supplied PR creation feedback.
74
78
 
75
79
  Use raw evidence only for local verification. Save only bounded structured facts or redacted summaries
76
80
  in durable retrospectives; never embed unredacted logs, command output, environment dumps, provider