vouchington-tooling 3.4.1 → 3.5.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.
- package/dist/mcp-server/handlers-retrospective-save.d.mts +1 -1
- package/dist/mcp-server/handlers-retrospective-save.mjs +8 -1
- package/dist/mcp-server/retrospective-sections.test-helpers.d.mts +4 -0
- package/dist/mcp-server/retrospective-sections.test-helpers.mjs +29 -0
- package/dist/mcp-server/retrospective-validate-assessments.d.mts +2 -0
- package/dist/mcp-server/retrospective-validate-assessments.mjs +51 -0
- package/dist/mcp-server/retrospective-validate-ci.d.mts +4 -0
- package/dist/mcp-server/retrospective-validate-ci.mjs +79 -0
- package/dist/mcp-server/retrospective-validate.d.mts +6 -0
- package/dist/mcp-server/retrospective-validate.mjs +35 -0
- package/docs/mcp-server.md +17 -1
- package/package.json +1 -1
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
- package/skills/blackboard/SKILL.md +2 -0
- package/skills/blackboard/references/session-id.md +14 -0
- package/skills/manifest.json +9 -9
- package/skills/retrospective/SKILL.md +6 -2
- package/skills/retrospective/references/pr-feedback.md +45 -0
- package/skills/retrospective/references/sandbox-audit.md +44 -0
- package/skills/retrospective-distill/SKILL.md +6 -3
- package/skills/triage-prs/SKILL.md +2 -2
- package/skills/triage-prs/references/feedback.md +4 -1
|
@@ -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,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,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
|
+
}
|
package/docs/mcp-server.md
CHANGED
|
@@ -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.
|
|
3
|
+
"version": "3.5.0",
|
|
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": {
|
|
Binary file
|
|
@@ -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.
|
package/skills/manifest.json
CHANGED
|
@@ -4,57 +4,57 @@
|
|
|
4
4
|
{
|
|
5
5
|
"name": "blackboard",
|
|
6
6
|
"plugin": "vouchington-workflow",
|
|
7
|
-
"pluginVersion": "0.26.
|
|
7
|
+
"pluginVersion": "0.26.1",
|
|
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.
|
|
13
|
+
"pluginVersion": "0.26.1",
|
|
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.
|
|
19
|
+
"pluginVersion": "0.26.1",
|
|
20
20
|
"path": "pr-description/SKILL.md"
|
|
21
21
|
},
|
|
22
22
|
{
|
|
23
23
|
"name": "retrospective",
|
|
24
24
|
"plugin": "vouchington-workflow",
|
|
25
|
-
"pluginVersion": "0.26.
|
|
25
|
+
"pluginVersion": "0.26.1",
|
|
26
26
|
"path": "retrospective/SKILL.md"
|
|
27
27
|
},
|
|
28
28
|
{
|
|
29
29
|
"name": "retrospective-distill",
|
|
30
30
|
"plugin": "vouchington-workflow",
|
|
31
|
-
"pluginVersion": "0.26.
|
|
31
|
+
"pluginVersion": "0.26.1",
|
|
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.
|
|
37
|
+
"pluginVersion": "0.26.1",
|
|
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.
|
|
44
|
+
"pluginVersion": "0.26.1",
|
|
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.
|
|
50
|
+
"pluginVersion": "0.26.1",
|
|
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.
|
|
57
|
+
"pluginVersion": "0.26.1",
|
|
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
|
-
|
|
73
|
-
|
|
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
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# PR creation feedback
|
|
2
|
+
|
|
3
|
+
Read this when a PR-triage caller supplied agent-authored PR creation feedback this session. Keep
|
|
4
|
+
both the per-PR findings and the deduplicated grouped themes.
|
|
5
|
+
|
|
6
|
+
```markdown
|
|
7
|
+
## PR Creation Feedback
|
|
8
|
+
|
|
9
|
+
### Per-PR findings
|
|
10
|
+
|
|
11
|
+
- PR #N - `<recurring|one-off>`
|
|
12
|
+
- Evidence: <body, diff, checks, or shepherd correction>
|
|
13
|
+
- Generator provenance: <verified generating prompt or skill>
|
|
14
|
+
- Source target: <exact file path>
|
|
15
|
+
- Recommendation: <specific preventive improvement>
|
|
16
|
+
|
|
17
|
+
### Grouped themes
|
|
18
|
+
|
|
19
|
+
- <theme>
|
|
20
|
+
- PRs: #N, #N
|
|
21
|
+
- Recurrence: <recurring|one-off>
|
|
22
|
+
- Source target: <exact file path>
|
|
23
|
+
- Recommendation: <deduplicated improvement>
|
|
24
|
+
- Disposition: <issue #N|PR #N|preauthorized-pr #N|deferred>
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
When there is no actionable feedback, write `No actionable feedback: none` instead of inventing a
|
|
28
|
+
theme.
|
|
29
|
+
|
|
30
|
+
## Disposition
|
|
31
|
+
|
|
32
|
+
When the caller did not already publish the feedback, ask the user to choose one:
|
|
33
|
+
|
|
34
|
+
- **File issues:** deduplicate by root cause, file through the repository's issue workflow, and
|
|
35
|
+
record each issue link.
|
|
36
|
+
- **Make a PR:** when several unrelated themes exist, ask which single theme to implement. Reuse or
|
|
37
|
+
create its tracking issue, make one coherent draft PR, do not merge it, and record the PR link.
|
|
38
|
+
- **Defer:** make no GitHub change; the theme stays eligible for a later distillation run.
|
|
39
|
+
|
|
40
|
+
When the triage flow already completed its bounded publication
|
|
41
|
+
([feedback](../../triage-prs/references/feedback.md)), it passes `Disposition: preauthorized-pr #N`.
|
|
42
|
+
Record that exact disposition and the PR link without asking again. If publication failed or only
|
|
43
|
+
partly completed, record the concrete blocker as `deferred`; never claim the feedback was handled.
|
|
44
|
+
|
|
45
|
+
Save one retrospective with the final disposition and links for all PRs.
|
|
@@ -40,9 +40,53 @@ or package entry it names still exists. A transcript can be stale.
|
|
|
40
40
|
- Human-rejected command: propose a block rule, but surface it for human review and never write a
|
|
41
41
|
deny rule from a retrospective. One rejection is one data point; confirm the pattern recurs.
|
|
42
42
|
|
|
43
|
+
## Reading the command audit report
|
|
44
|
+
|
|
45
|
+
The `sandbox-command-audit` command reports three signals instead of one merged ranking, because
|
|
46
|
+
each maps to a different action:
|
|
47
|
+
|
|
48
|
+
- Genuine bypass: Claude Bash failures on a permission or access signature, not `E2BIG`. Judge them
|
|
49
|
+
by the decision criteria above.
|
|
50
|
+
- Block candidates: Claude denials where a human rejected the command. Propose a block rule for
|
|
51
|
+
human review.
|
|
52
|
+
- Escalation pressure: Claude `dangerouslyDisableSandbox` escalations, split into covered and
|
|
53
|
+
uncovered by policy, plus the `E2BIG` count. It shows sandbox friction and is not by itself a
|
|
54
|
+
command to allow.
|
|
55
|
+
|
|
56
|
+
Also:
|
|
57
|
+
|
|
58
|
+
- `permission-rule` and `automode-blocked` denials appear only as a hygiene count: a block policy
|
|
59
|
+
working as intended.
|
|
60
|
+
- Codex transcripts are read only when the consumer's rules module sets `classifyFailure`, which
|
|
61
|
+
then runs on each completed `CommandExecution` result whatever its exit status. A push can
|
|
62
|
+
succeed before a later local write fails, so a zero exit does not exempt a result.
|
|
63
|
+
- Worktree write-path denials are not built in. The package ships only the `genuine` and `e2big`
|
|
64
|
+
kinds; a consumer's `classifyFailure` rule claims these (it runs before the generic permission
|
|
65
|
+
signatures), and they are reported as `Other classified sandbox failures`, a count per kind and
|
|
66
|
+
never a bypass candidate. A conservative rule requires git command context, a git-produced
|
|
67
|
+
diagnostic (`fatal:`, `error:`, or `warning:`), and a permission token (`Operation not permitted`,
|
|
68
|
+
`EPERM`, `Permission denied`, `EROFS`, `Read-only file system`) adjacent to
|
|
69
|
+
`.git/worktrees/<name>/`, `.git/config`, `.git/packed-refs`, or `.git/refs/`. File content shown
|
|
70
|
+
by `git show` or `git diff` is not a diagnostic, and `index.lock` contention is not a permission
|
|
71
|
+
denial.
|
|
72
|
+
|
|
73
|
+
### Repo scoping
|
|
74
|
+
|
|
75
|
+
- Check the `Scope:` line before trusting a report: it lists the roots and counts the files
|
|
76
|
+
skipped as `other repo` or `cwd unknown`.
|
|
77
|
+
- A transcript is attributed by its first recorded `cwd`. The walk stops at `--limit`, so the skip
|
|
78
|
+
counts are lower bounds: a `0` for `other repo` is not proof that nothing else was reachable.
|
|
79
|
+
- A deleted worktree that `git worktree list` no longer reports is not discoverable, and its
|
|
80
|
+
transcripts count as `other repo`. Restore its path with `--repo-root`, or its layout with
|
|
81
|
+
`--worktree-glob`.
|
|
82
|
+
|
|
43
83
|
## Privacy
|
|
44
84
|
|
|
45
85
|
Report a normalized `<command> <subcommand>` prefix and counts, never the raw command line or a
|
|
46
86
|
justification verbatim. For a short command the prefix is the whole command, so a branch slug, short
|
|
47
87
|
path, or hostname can appear in it: skim and redact before saving. Retrospectives are distilled into
|
|
48
88
|
public issues.
|
|
89
|
+
|
|
90
|
+
The audit's default output is prefix-only, and any token longer than 40 characters is replaced
|
|
91
|
+
outright with a marker, never truncated. `--raw` adds full commands and failure text for local
|
|
92
|
+
inspection only; never paste `--raw` output into a retrospective.
|
|
@@ -128,11 +128,14 @@ difference is a conflicting payload and stays quarantined.
|
|
|
128
128
|
for sessions whose only themes were deferred, since deferral promises re-evaluation. Keep a theme
|
|
129
129
|
tied to a closed-without-merge issue or change eligible; do not treat open state alone as
|
|
130
130
|
conclusive. Preserve each theme's contributing session IDs through merging and deduplication.
|
|
131
|
-
- Delegate partitions only to read-only inspectors
|
|
131
|
+
- Delegate partitions only to read-only inspectors (the host's read-only explore agent), which
|
|
132
|
+
must not call MCP, create issues, archive
|
|
132
133
|
sessions, edit files, or keep a copy of a partition. Have each return a compact disposition
|
|
133
134
|
summary: partition index, deduplicated themes with their session IDs, and each session's
|
|
134
|
-
disposition.
|
|
135
|
-
|
|
135
|
+
disposition. Before hand-reading, each inspector runs
|
|
136
|
+
`vouchington agent-blackboard distill classify <partition> --retro-cutoff <retroCutoff> --session-cutoff <sessionCutoff>`
|
|
137
|
+
with the shared cutoffs. Inspectors hand-read only journal-only and retrospective sessions; every
|
|
138
|
+
other shape is determined structurally.
|
|
136
139
|
- Keep the verified snapshot until the last `snapshot_archive` call, because the server's archival
|
|
137
140
|
check reads it.
|
|
138
141
|
Then call `snapshot_cleanup`, which removes the snapshot and the partitions
|
|
@@ -124,8 +124,8 @@ the Step 6 report so it is not dropped. Process MERGE decisions in
|
|
|
124
124
|
ascending PR-number order through the loop's
|
|
125
125
|
[ready and merge](../triage-loop/SKILL.md#ready-and-merge) procedure, passing the PR number, the
|
|
126
126
|
merge flag, and any steering file. That procedure light-reviews the diff, posts steering, readies
|
|
127
|
-
the draft, gates on the final review when the loop's configuration turns that gate on, and merges through pr-shepherd.
|
|
128
|
-
|
|
127
|
+
the draft, gates on the final review when the loop's configuration turns that gate on, and merges through pr-shepherd. The merge method is a
|
|
128
|
+
parameter of the consumer wrapper and a setting the repository owns. Run its preflight before every mutation.
|
|
129
129
|
If the preflight fails, record the reason and report separately any mutation already completed
|
|
130
130
|
(for example the PR was readied before the head moved) and the failed preflight; do not describe
|
|
131
131
|
the PR as merging.
|
|
@@ -50,7 +50,10 @@ not ready, shepherd, or merge a generated or reused feedback PR in the same run.
|
|
|
50
50
|
exact-match reuse, or `same-paths-new-feedback` update of the canonical PR and issue.
|
|
51
51
|
- `disposition: deferred`: record `deferred` with the concrete blocker after a failed, partial, or
|
|
52
52
|
ambiguous publication. Do not ask the user or claim the feedback was handled.
|
|
53
|
-
- `disposition: user-choice`: keep non-prompt feedback in the normal human follow-up flow.
|
|
53
|
+
- `disposition: user-choice`: keep non-prompt feedback in the normal human follow-up flow. Outside
|
|
54
|
+
this preauthorized path, the retrospective asks the user to file issues, make a PR, or defer; see
|
|
55
|
+
[PR creation feedback](../../retrospective/references/pr-feedback.md) for the document shape and
|
|
56
|
+
those choices.
|
|
54
57
|
|
|
55
58
|
Group the Step 3 PR-creation recommendations by root cause and invoke
|
|
56
59
|
[retrospective](../../retrospective/SKILL.md). It records findings for merged and closed PRs alike.
|