vouchington-tooling 0.55.0 → 0.57.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 (46) hide show
  1. package/README.md +9 -0
  2. package/dist/gh-api-shell-quoting/logical-line.mjs +14 -74
  3. package/dist/input-otp-mock/index.d.mts +25 -0
  4. package/dist/input-otp-mock/index.mjs +34 -0
  5. package/dist/jsdom-stubs/index.d.mts +12 -0
  6. package/dist/jsdom-stubs/index.mjs +85 -0
  7. package/dist/mcp-server/policy-run.d.mts +2 -0
  8. package/dist/mcp-server/policy-run.mjs +6 -2
  9. package/dist/mcp-server/policy-spawn.d.mts +1 -0
  10. package/dist/mcp-server/policy-spawn.mjs +10 -2
  11. package/dist/next-navigation-mock/index.d.mts +27 -0
  12. package/dist/next-navigation-mock/index.mjs +58 -0
  13. package/dist/retrospective-transcript/codex-records.mjs +4 -0
  14. package/dist/retrospective-transcript/command-prefix.d.mts +1 -0
  15. package/dist/retrospective-transcript/command-prefix.mjs +1 -1
  16. package/dist/retrospective-transcript/command-segments.d.mts +1 -1
  17. package/dist/retrospective-transcript/command-segments.mjs +3 -48
  18. package/dist/retrospective-transcript/escalations.d.mts +6 -0
  19. package/dist/retrospective-transcript/escalations.mjs +34 -0
  20. package/dist/retrospective-transcript/format.mjs +13 -0
  21. package/dist/retrospective-transcript/index.mjs +2 -1
  22. package/dist/retrospective-transcript/malformed-record.d.mts +1 -0
  23. package/dist/retrospective-transcript/malformed-record.mjs +13 -0
  24. package/dist/retrospective-transcript/shared.d.mts +2 -1
  25. package/dist/retrospective-transcript/shared.mjs +1 -12
  26. package/dist/shell-parse/index.d.mts +2 -0
  27. package/dist/shell-parse/index.mjs +2 -0
  28. package/dist/shell-parse/shell-command-segments.d.mts +6 -0
  29. package/dist/shell-parse/shell-command-segments.mjs +26 -0
  30. package/dist/shell-parse/shell-tokenizer-operators.d.mts +2 -4
  31. package/dist/shell-parse/shell-tokenizer-operators.mjs +14 -4
  32. package/dist/shell-parse/shell-tokenizer.d.mts +9 -5
  33. package/dist/shell-parse/shell-tokenizer.mjs +5 -1
  34. package/dist/shell-parse/shell-walk.d.mts +8 -0
  35. package/dist/shell-parse/shell-walk.mjs +62 -0
  36. package/package.json +29 -1
  37. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
  38. package/skills/blackboard/SKILL.md +19 -0
  39. package/skills/github-issue/SKILL.md +12 -0
  40. package/skills/manifest.json +20 -20
  41. package/skills/retrospective/SKILL.md +17 -1
  42. package/skills/retrospective/references/ci-failures.md +48 -0
  43. package/skills/retrospective/references/sandbox-audit.md +48 -0
  44. package/skills/retrospective-distill/SKILL.md +11 -3
  45. package/skills/retrospective-distill/references/issue-body.md +40 -0
  46. package/skills/stacked-prs/references/gh-stack.md +5 -1
@@ -16,6 +16,7 @@ export const emptyFacts = () => ({
16
16
  tokens: emptyTokens(),
17
17
  subagentToolCalls: 0,
18
18
  subagentTokens: emptyTokens(),
19
+ escalations: [],
19
20
  });
20
21
  export function asRecord(value) {
21
22
  return value !== null && typeof value === 'object' && !Array.isArray(value)
@@ -39,18 +40,6 @@ export function parseLines(lines) {
39
40
  }
40
41
  return records;
41
42
  }
42
- export function hasMalformedInteriorRecord(lines) {
43
- const nonblank = lines.filter((line) => line.trim());
44
- const complete = lines.at(-1)?.trim() ? nonblank.slice(0, -1) : nonblank;
45
- return complete.some((line) => {
46
- try {
47
- return !asRecord(JSON.parse(line));
48
- }
49
- catch {
50
- return true;
51
- }
52
- });
53
- }
54
43
  function hereDocs(tokens) {
55
44
  return tokens.flatMap((token, index) => {
56
45
  if (token.startsWith('<<<'))
@@ -18,3 +18,5 @@ export { stripUnquotedShellComments } from './shell-tokenizer-comments.mts';
18
18
  export { consumeShellSeparator } from './shell-tokenizer-operators.mts';
19
19
  export { tokenizeShellWords, tokenizeShellWordsDetailed } from './shell-tokenizer.mts';
20
20
  export type { ShellWord } from './shell-tokenizer.mts';
21
+ export { walkUnquotedShell } from './shell-walk.mts';
22
+ export { splitCommandSegments } from './shell-command-segments.mts';
@@ -13,3 +13,5 @@ export { commandSegmentStart, isShellAssignment, isShellCommandSeparator, nextSh
13
13
  export { stripUnquotedShellComments } from "./shell-tokenizer-comments.mjs";
14
14
  export { consumeShellSeparator } from "./shell-tokenizer-operators.mjs";
15
15
  export { tokenizeShellWords, tokenizeShellWordsDetailed } from "./shell-tokenizer.mjs";
16
+ export { walkUnquotedShell } from "./shell-walk.mjs";
17
+ export { splitCommandSegments } from "./shell-command-segments.mjs";
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Splits a command into segments on unquoted `;`, `&`, `&&`, `|`, `||`, and newlines, each segment
3
+ * being its already-unquoted words. Parentheses stay inside words (`$(git status)` is one word
4
+ * run, not a nested command), so only top-level command position is exposed.
5
+ */
6
+ export declare function splitCommandSegments(command: string): string[][];
@@ -0,0 +1,26 @@
1
+ import { tokenizeShellWordsDetailed } from "./shell-tokenizer.mjs";
2
+ /**
3
+ * Splits a command into segments on unquoted `;`, `&`, `&&`, `|`, `||`, and newlines, each segment
4
+ * being its already-unquoted words. Parentheses stay inside words (`$(git status)` is one word
5
+ * run, not a nested command), so only top-level command position is exposed.
6
+ */
7
+ export function splitCommandSegments(command) {
8
+ const segments = [];
9
+ let current = [];
10
+ for (const word of tokenizeShellWordsDetailed(command, {
11
+ keepParentheses: true,
12
+ markOperators: true,
13
+ })) {
14
+ if (word.operator === true) {
15
+ if (current.length > 0)
16
+ segments.push(current);
17
+ current = [];
18
+ }
19
+ else {
20
+ current.push(word.value);
21
+ }
22
+ }
23
+ if (current.length > 0)
24
+ segments.push(current);
25
+ return segments;
26
+ }
@@ -1,12 +1,10 @@
1
- import type { ShellWord } from './shell-tokenizer.mts';
1
+ import type { ShellTokenizeOptions, ShellWord } from './shell-tokenizer.mts';
2
2
  type SeparatorState = {
3
3
  char: string;
4
4
  command: string;
5
5
  expandable: boolean;
6
6
  index: number;
7
- options: {
8
- splitRedirections?: boolean;
9
- };
7
+ options: ShellTokenizeOptions;
10
8
  token: string;
11
9
  tokens: ShellWord[];
12
10
  };
@@ -29,17 +29,27 @@ export function consumeShellSeparator(state) {
29
29
  return state.index + redirectionOperator.length - 1;
30
30
  }
31
31
  const { char } = state;
32
- if (char === '&' || char === '|' || char === ';' || char === '(' || char === ')') {
32
+ const isParenthesis = char === '(' || char === ')';
33
+ if (char === '&' ||
34
+ char === '|' ||
35
+ char === ';' ||
36
+ (isParenthesis && !state.options.keepParentheses)) {
33
37
  pushStateToken(state);
34
- const previousToken = state.tokens.at(-1)?.value;
35
- if ((char === '&' && previousToken === '&') || (char === '|' && previousToken === '|')) {
38
+ const operator = state.options.markOperators ? { operator: true } : {};
39
+ const previous = state.tokens.at(-1);
40
+ const previousToken = previous?.value;
41
+ // With `markOperators` a quoted `"|"` argument is not an operator, so only operators merge.
42
+ const mergeable = state.options.markOperators !== true || previous?.operator === true;
43
+ if (mergeable &&
44
+ ((char === '&' && previousToken === '&') || (char === '|' && previousToken === '|'))) {
36
45
  state.tokens[state.tokens.length - 1] = {
37
46
  expandable: false,
47
+ ...operator,
38
48
  value: `${previousToken}${char}`,
39
49
  };
40
50
  }
41
51
  else {
42
- state.tokens.push({ expandable: false, value: char });
52
+ state.tokens.push({ expandable: false, ...operator, value: char });
43
53
  }
44
54
  return state.index;
45
55
  }
@@ -1,12 +1,16 @@
1
1
  import { stripUnquotedShellComments } from './shell-tokenizer-comments.mts';
2
2
  export type ShellWord = {
3
3
  expandable: boolean;
4
+ operator?: true;
4
5
  value: string;
5
6
  };
6
- export declare function tokenizeShellWordsDetailed(command: string, options?: {
7
+ export type ShellTokenizeOptions = {
8
+ /** Keep `(` and `)` inside words instead of emitting them as operator tokens. */
9
+ keepParentheses?: boolean;
10
+ /** Tag command-separator tokens (`;`, `&`, `&&`, `|`, `||`, `(`, `)`, newline) with `operator`. */
11
+ markOperators?: boolean;
7
12
  splitRedirections?: boolean;
8
- }): ShellWord[];
9
- export declare function tokenizeShellWords(command: string, options?: {
10
- splitRedirections?: boolean;
11
- }): string[];
13
+ };
14
+ export declare function tokenizeShellWordsDetailed(command: string, options?: ShellTokenizeOptions): ShellWord[];
15
+ export declare function tokenizeShellWords(command: string, options?: ShellTokenizeOptions): string[];
12
16
  export { stripUnquotedShellComments };
@@ -64,7 +64,11 @@ export function tokenizeShellWordsDetailed(command, options = {}) {
64
64
  }
65
65
  if (char === '\n') {
66
66
  pushToken();
67
- tokens.push({ expandable: false, value: '\n' });
67
+ tokens.push({
68
+ expandable: false,
69
+ value: '\n',
70
+ ...(options.markOperators ? { operator: true } : {}),
71
+ });
68
72
  continue;
69
73
  }
70
74
  if (/\s/.test(char)) {
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Calls `visit(index, state)` for every character outside quotes, escapes, comments, and the
3
+ * structural `$(` / `(` / `)` of a substitution. `state` belongs to the current `$(...)` level. The
4
+ * visitor returns the next index to consume from, or `undefined` to advance by one. Backslash
5
+ * escapes consume the following character, even inside double quotes, and a `#` at the start or
6
+ * after whitespace ends the text.
7
+ */
8
+ export declare function walkUnquotedShell<State>(text: string, createState: () => State, visit: (index: number, state: State) => number | undefined): void;
@@ -0,0 +1,62 @@
1
+ // A quote-aware walk over shell text for callers that need per-character positions rather than
2
+ // tokens (for example to report offsets). It tracks single and double quotes, backslash escapes,
3
+ // unquoted `#` comments, and `$(...)` nesting, giving each nesting level its own caller-defined
4
+ // state. Unlike `tokenizeShellWordsDetailed` it never classifies expansion or glob characters, so a
5
+ // quoted `"...${VAR}...?x=1"` yields no unquoted `?` to the visitor.
6
+ function newFrame(state, parenDepth) {
7
+ return { inSingleQuote: false, inDoubleQuote: false, parenDepth, state };
8
+ }
9
+ /**
10
+ * Calls `visit(index, state)` for every character outside quotes, escapes, comments, and the
11
+ * structural `$(` / `(` / `)` of a substitution. `state` belongs to the current `$(...)` level. The
12
+ * visitor returns the next index to consume from, or `undefined` to advance by one. Backslash
13
+ * escapes consume the following character, even inside double quotes, and a `#` at the start or
14
+ * after whitespace ends the text.
15
+ */
16
+ export function walkUnquotedShell(text, createState, visit) {
17
+ const stack = [newFrame(createState(), 0)];
18
+ let i = 0;
19
+ while (i < text.length) {
20
+ const frame = stack[stack.length - 1];
21
+ const char = text[i];
22
+ if (frame.inSingleQuote) {
23
+ if (char === "'")
24
+ frame.inSingleQuote = false;
25
+ i += 1;
26
+ continue;
27
+ }
28
+ if (char === '\\') {
29
+ i += 2;
30
+ continue;
31
+ }
32
+ if (char === '$' && text[i + 1] === '(') {
33
+ stack.push(newFrame(createState(), 1));
34
+ i += 2;
35
+ continue;
36
+ }
37
+ if (frame.inDoubleQuote) {
38
+ if (char === '"')
39
+ frame.inDoubleQuote = false;
40
+ i += 1;
41
+ continue;
42
+ }
43
+ if (char === '#' && (i === 0 || /\s/.test(text[i - 1])))
44
+ break;
45
+ if (char === "'" || char === '"') {
46
+ if (char === "'")
47
+ frame.inSingleQuote = true;
48
+ else
49
+ frame.inDoubleQuote = true;
50
+ i += 1;
51
+ continue;
52
+ }
53
+ if (stack.length > 1 && (char === '(' || char === ')')) {
54
+ frame.parenDepth += char === '(' ? 1 : -1;
55
+ i += 1;
56
+ if (frame.parenDepth === 0)
57
+ stack.pop();
58
+ continue;
59
+ }
60
+ i = visit(i, frame.state) ?? i + 1;
61
+ }
62
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vouchington-tooling",
3
- "version": "0.55.0",
3
+ "version": "0.57.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": {
@@ -391,6 +391,21 @@
391
391
  "types": "./dist/post-publication-inventory/index.d.mts",
392
392
  "import": "./dist/post-publication-inventory/index.mjs",
393
393
  "default": "./dist/post-publication-inventory/index.mjs"
394
+ },
395
+ "./next-navigation-mock": {
396
+ "types": "./dist/next-navigation-mock/index.d.mts",
397
+ "import": "./dist/next-navigation-mock/index.mjs",
398
+ "default": "./dist/next-navigation-mock/index.mjs"
399
+ },
400
+ "./jsdom-stubs": {
401
+ "types": "./dist/jsdom-stubs/index.d.mts",
402
+ "import": "./dist/jsdom-stubs/index.mjs",
403
+ "default": "./dist/jsdom-stubs/index.mjs"
404
+ },
405
+ "./input-otp-mock": {
406
+ "types": "./dist/input-otp-mock/index.d.mts",
407
+ "import": "./dist/input-otp-mock/index.mjs",
408
+ "default": "./dist/input-otp-mock/index.mjs"
394
409
  }
395
410
  },
396
411
  "publishConfig": {
@@ -421,15 +436,22 @@
421
436
  "@modelcontextprotocol/sdk": "1.32.1",
422
437
  "@playwright/test": "1.64.1",
423
438
  "@types/picomatch": "^4.0.3",
439
+ "@types/react": "19.3.0",
440
+ "@types/react-dom": "19.3.0",
424
441
  "@types/spdx-expression-parse": "4.0.0",
442
+ "next": "16.4.2",
425
443
  "no-mistakes": "0.83.0",
444
+ "react": "19.3.1",
445
+ "react-dom": "19.3.1",
426
446
  "smol-toml": "1.9.1",
427
447
  "typescript5": "npm:typescript@5.9.3"
428
448
  },
429
449
  "peerDependencies": {
430
450
  "@modelcontextprotocol/sdk": "^1.31.0",
431
451
  "@playwright/test": ">=1.64.1",
452
+ "next": ">=15",
432
453
  "no-mistakes": "*",
454
+ "react": ">=18",
433
455
  "typescript": ">=5",
434
456
  "vitest": ">=5"
435
457
  },
@@ -440,9 +462,15 @@
440
462
  "@playwright/test": {
441
463
  "optional": true
442
464
  },
465
+ "next": {
466
+ "optional": true
467
+ },
443
468
  "no-mistakes": {
444
469
  "optional": true
445
470
  },
471
+ "react": {
472
+ "optional": true
473
+ },
446
474
  "typescript": {
447
475
  "optional": true
448
476
  },
@@ -119,6 +119,25 @@ bounded structured facts or sanitized summaries, never raw command output, trans
119
119
  environment dumps, provider payloads, or secrets. Known-secret redaction supplements the author's
120
120
  minimization responsibility; it cannot prove arbitrary prose contains no undisclosed secret.
121
121
 
122
+ ## Sandbox and permission blocks
123
+
124
+ A denied or escalated command uses this block grammar, one block per entry, because a
125
+ retrospective's sandbox and permission audit is built only from entries that match it:
126
+
127
+ ```
128
+ - `sandbox-escalation` — <command and subcommand only: no paths, hosts, branches, or secrets> — <what needed elevated access>
129
+ - Outcome: requested|approved|denied|unknown
130
+ - Evidence: <sanitized denial or approval text>
131
+ - Disposition: <allowlist change, issue #N, or none>
132
+ ```
133
+
134
+ Use `sandbox-failure` (a sandbox refusal) or `ambiguous-failure` (a failure whose cause is unclear)
135
+ in place of `sandbox-escalation` for a command that failed without an escalation; those blocks omit
136
+ the `Outcome` line. Set `Outcome` only from observed evidence: a request is `requested`, never
137
+ `approved`. Always journal the block: the audit section is built from journal blocks alone, so an
138
+ escalation reported only in the transcript facts leaves it saying none observed. The transcript's
139
+ `escalations` are supplementary evidence under the transcript facts, not a substitute.
140
+
122
141
  ## Credential failures
123
142
 
124
143
  - Never search shell profiles, `env`, or `.env*` files for a credential. Check presence only with
@@ -63,6 +63,18 @@ templates, and repository-routing policy before any remote mutation.
63
63
  unchanged and report the gap.
64
64
  3. Write a self-contained issue: problem, desired outcome, ownership boundaries, concrete areas,
65
65
  validation, and external context. A discovered blocker does not widen implementation scope.
66
+ - Before absorbing a newly discovered blocker, require the calling workflow to reproduce it
67
+ against the refreshed default branch and provide the evidence, then search for an existing fix
68
+ or issue. If a fix resolves it, report it so the caller can use and retest it. Otherwise ask
69
+ whether to widen the accepted scope or only link or record a follow-up. Filing records work;
70
+ it does not amend the accepted plan or authorize implementation.
71
+ - A stop condition in an issue names a real decision for a human. Adding or changing an index,
72
+ or a rewrite that returns the same rows, is never one: the worker makes the change and records
73
+ the plan before and after.
74
+ - Verify every existing path in `## Files / areas` against `HEAD`. Mark a proposed path `New`
75
+ and verify its owning parent or module. Reject absolute and parent-traversal (`..`) paths. For
76
+ a target outside the current checkout, verify only redacted remote metadata through the
77
+ Contents API.
66
78
  4. Fetch the complete live taxonomy, including open projects. Apply matching existing labels and a
67
79
  selected existing milestone with no separate approval.
68
80
  - Use an existing open project for strategic, initiative-level tracking, and a milestone for
@@ -4,7 +4,7 @@
4
4
  {
5
5
  "name": "agent-workflow",
6
6
  "plugin": "vouchington-workflow",
7
- "pluginVersion": "0.13.1",
7
+ "pluginVersion": "0.14.0",
8
8
  "path": "agent-workflow/SKILL.md",
9
9
  "prerequisites": [
10
10
  "blackboard",
@@ -24,7 +24,7 @@
24
24
  {
25
25
  "name": "blackboard",
26
26
  "plugin": "vouchington-workflow",
27
- "pluginVersion": "0.13.1",
27
+ "pluginVersion": "0.14.0",
28
28
  "path": "blackboard/SKILL.md"
29
29
  },
30
30
  {
@@ -36,7 +36,7 @@
36
36
  {
37
37
  "name": "dependabot",
38
38
  "plugin": "vouchington-workflow",
39
- "pluginVersion": "0.13.1",
39
+ "pluginVersion": "0.14.0",
40
40
  "path": "dependabot/SKILL.md",
41
41
  "prerequisites": ["github-actions-checklist"]
42
42
  },
@@ -50,26 +50,26 @@
50
50
  {
51
51
  "name": "git-commit-checklist",
52
52
  "plugin": "vouchington-workflow",
53
- "pluginVersion": "0.13.1",
53
+ "pluginVersion": "0.14.0",
54
54
  "path": "git-commit-checklist/SKILL.md"
55
55
  },
56
56
  {
57
57
  "name": "github-actions-authoring",
58
58
  "plugin": "vouchington-workflow",
59
- "pluginVersion": "0.13.1",
59
+ "pluginVersion": "0.14.0",
60
60
  "path": "github-actions-authoring/SKILL.md",
61
61
  "prerequisites": ["github-actions-checklist"]
62
62
  },
63
63
  {
64
64
  "name": "github-actions-checklist",
65
65
  "plugin": "vouchington-workflow",
66
- "pluginVersion": "0.13.1",
66
+ "pluginVersion": "0.14.0",
67
67
  "path": "github-actions-checklist/SKILL.md"
68
68
  },
69
69
  {
70
70
  "name": "github-issue",
71
71
  "plugin": "vouchington-workflow",
72
- "pluginVersion": "0.13.1",
72
+ "pluginVersion": "0.14.0",
73
73
  "path": "github-issue/SKILL.md"
74
74
  },
75
75
  {
@@ -82,26 +82,26 @@
82
82
  {
83
83
  "name": "npm-publishing",
84
84
  "plugin": "vouchington-workflow",
85
- "pluginVersion": "0.13.1",
85
+ "pluginVersion": "0.14.0",
86
86
  "path": "npm-publishing/SKILL.md"
87
87
  },
88
88
  {
89
89
  "name": "organize-github-issues",
90
90
  "plugin": "vouchington-workflow",
91
- "pluginVersion": "0.13.1",
91
+ "pluginVersion": "0.14.0",
92
92
  "path": "organize-github-issues/SKILL.md",
93
93
  "prerequisites": ["github-issue"]
94
94
  },
95
95
  {
96
96
  "name": "package-json-checklist",
97
97
  "plugin": "vouchington-workflow",
98
- "pluginVersion": "0.13.1",
98
+ "pluginVersion": "0.14.0",
99
99
  "path": "package-json-checklist/SKILL.md"
100
100
  },
101
101
  {
102
102
  "name": "planning",
103
103
  "plugin": "vouchington-workflow",
104
- "pluginVersion": "0.13.1",
104
+ "pluginVersion": "0.14.0",
105
105
  "path": "planning/SKILL.md",
106
106
  "prerequisites": ["github-issue"]
107
107
  },
@@ -133,53 +133,53 @@
133
133
  {
134
134
  "name": "pr-description",
135
135
  "plugin": "vouchington-workflow",
136
- "pluginVersion": "0.13.1",
136
+ "pluginVersion": "0.14.0",
137
137
  "path": "pr-description/SKILL.md"
138
138
  },
139
139
  {
140
140
  "name": "retrospective",
141
141
  "plugin": "vouchington-workflow",
142
- "pluginVersion": "0.13.1",
142
+ "pluginVersion": "0.14.0",
143
143
  "path": "retrospective/SKILL.md"
144
144
  },
145
145
  {
146
146
  "name": "retrospective-distill",
147
147
  "plugin": "vouchington-workflow",
148
- "pluginVersion": "0.13.1",
148
+ "pluginVersion": "0.14.0",
149
149
  "path": "retrospective-distill/SKILL.md",
150
150
  "prerequisites": ["github-issue"]
151
151
  },
152
152
  {
153
153
  "name": "review-ci-logs",
154
154
  "plugin": "vouchington-workflow",
155
- "pluginVersion": "0.13.1",
155
+ "pluginVersion": "0.14.0",
156
156
  "path": "review-ci-logs/SKILL.md",
157
157
  "prerequisites": ["github-actions-checklist", "pr-description"]
158
158
  },
159
159
  {
160
160
  "name": "review-github-issue-taxonomy",
161
161
  "plugin": "vouchington-workflow",
162
- "pluginVersion": "0.13.1",
162
+ "pluginVersion": "0.14.0",
163
163
  "path": "review-github-issue-taxonomy/SKILL.md",
164
164
  "prerequisites": ["github-issue"]
165
165
  },
166
166
  {
167
167
  "name": "revisit-followups",
168
168
  "plugin": "vouchington-workflow",
169
- "pluginVersion": "0.13.1",
169
+ "pluginVersion": "0.14.0",
170
170
  "path": "revisit-followups/SKILL.md",
171
171
  "prerequisites": ["github-issue"]
172
172
  },
173
173
  {
174
174
  "name": "stacked-prs",
175
175
  "plugin": "vouchington-workflow",
176
- "pluginVersion": "0.13.1",
176
+ "pluginVersion": "0.14.0",
177
177
  "path": "stacked-prs/SKILL.md"
178
178
  },
179
179
  {
180
180
  "name": "static-analysis-checklist",
181
181
  "plugin": "vouchington-workflow",
182
- "pluginVersion": "0.13.1",
182
+ "pluginVersion": "0.14.0",
183
183
  "path": "static-analysis-checklist/SKILL.md",
184
184
  "prerequisites": ["github-actions-checklist"]
185
185
  },
@@ -206,7 +206,7 @@
206
206
  {
207
207
  "name": "triage-prs",
208
208
  "plugin": "vouchington-workflow",
209
- "pluginVersion": "0.13.1",
209
+ "pluginVersion": "0.14.0",
210
210
  "path": "triage-prs/SKILL.md",
211
211
  "prerequisites": [
212
212
  "pr-description",
@@ -12,11 +12,24 @@ Local policy overrides these defaults; do not reload an already-read adapter or
12
12
  Use at task completion or session close-out when the repository has a retrospective workflow. Read
13
13
  local `AGENTS.md`, and journal guidance first.
14
14
 
15
+ Budget: at most 10 tool calls, 5 minutes, and 25k tokens. Aggregate already-captured facts; do not
16
+ re-mine transcripts, dispatch a subagent, read raw session files, or search transcripts with
17
+ `grep`, `rg`, `jq`, or `awk`. The evidence sources are the `facts` and `transcript` inputs of
18
+ `retrospective_save`'s `compose` argument and the `journal_entries` tool. Evidence that neither can
19
+ answer is `unknown — no journal`, never a guess.
20
+
15
21
  1. Read the agent's own journal oldest-first and check for an existing retrospective. Capture a
16
22
  material new observation before filing a follow-up issue. Preserve entry-level repository tags.
17
23
  2. Generate routine repository and transcript facts with the approved composer: pass `compose` to
18
24
  the `retrospective_save` MCP tool and preview the composition with `dryRun`, never a CLI. Save the preview by passing its
19
- `previewToken` to `retrospective_save` (no markdown); put sensitive values only in
25
+ `previewToken` to `retrospective_save` (no markdown). `compose` takes a concise `narrative`,
26
+ `date`, `issues`, `prs`, `description`, `facts`, `transcript`, `tools`, and `architecture`; the
27
+ server adds the session, repositories, outcome, and coverage from the call's own `workOutcome`,
28
+ `feedbackCoverage`, and `repositories`. Pass `compose.transcript.harnessSessionId` whenever the
29
+ harness session id differs from the call's `sessionId`. The composer builds the CI failures and
30
+ sandbox audit sections from the session's hosted journal entries alone, so do not rerun
31
+ collectors to fill them. A session unknown to the journal reports both as unavailable, not as
32
+ none observed. Put sensitive values only in
20
33
  `compose.knownSensitiveValues`, or `knownSensitiveValues` for a markdown save. Keep exact factual
21
34
  section markers generated, preserve unavailable counts, and never replace missing evidence with
22
35
  invented zero statistics. Do not paste raw collectors' output or manually reconstruct facts.
@@ -40,6 +53,9 @@ local `AGENTS.md`, and journal guidance first.
40
53
  online and never uses that outbox to authorize an attempt or completion. Report the acknowledged
41
54
  record/receipt, or the actual pending/blocked state and next replay action.
42
55
 
56
+ Read [ci-failures](references/ci-failures.md) when the session observed CI failures, and
57
+ [sandbox-audit](references/sandbox-audit.md) when it hit denied or escalated commands.
58
+
43
59
  Use raw evidence only for local verification. Save only bounded structured facts or redacted summaries
44
60
  in durable retrospectives; never embed unredacted logs, command output, environment dumps, provider
45
61
  payloads, or transcript content there. Exclude secrets. Consumer wrappers own providers, commands,
@@ -0,0 +1,48 @@
1
+ # CI failures
2
+
3
+ A retrospective's `## CI Failures` section is an observed-failures log, not a historical audit of the
4
+ hosting service. Build it from the session journal alone, as the composer does. Transcript output
5
+ cannot establish CI status. Do not crawl workflow history for failures the session never observed,
6
+ and do not infer that none occurred because the final run passed.
7
+
8
+ Use exactly one status line:
9
+
10
+ - `Status: failures observed`
11
+ - `Status: none observed`, only when the journal was readable and showed no failures
12
+ - `Status: unavailable (<reason>)`, when the journal cannot establish whether failures occurred,
13
+ such as an unreadable journal or a session unknown to the journal; the reason is non-blank
14
+
15
+ ## Journal block
16
+
17
+ Journal a CI failure in this grammar, one block per root cause rather than per run. A flake counts,
18
+ even one that passed on a later run with no code change. Record whether it was flaky, the gotcha, and
19
+ how to reach passing CI in fewer commits:
20
+
21
+ ```
22
+ - `recurring|one-off` — `GitHub Actions` — <check name>: <gotcha, or flaky: <test>>
23
+ - Evidence: <run URL and commit>
24
+ - Root diagnostic: <first actionable error, with the affected test, file, or symbol; for a flake, the nondeterminism observed>
25
+ - Disposition: <fix commit, unresolved with issue #N, or infrastructure/pre-existing with evidence>
26
+ ```
27
+
28
+ A consumer wrapper may add fields to `Disposition` (for example, whether a test-selection tool chose
29
+ the failing test). Keep any such field when grouping.
30
+
31
+ ## Grouping
32
+
33
+ - Group repeated occurrences by root signature and state the occurrence count when one signature
34
+ hit several pushes.
35
+ - Report the first or root failure, not downstream aggregate or fan-in failures.
36
+ - Keep an earlier failure even when a later attempt passes.
37
+ - Hosted CI jobs are in scope; external checks are out of scope unless the failure was emitted
38
+ inside such a job.
39
+ - Never paste complete logs, environment dumps, credentials, or tokens.
40
+
41
+ ## Wording rules
42
+
43
+ - Use "direct-to-main" only when `git branch -r --contains <sha>` lists the default branch's remote
44
+ ref and the commit is on that branch's first-parent history. An unmerged branch is "committed to
45
+ topic branch X, unmerged at retrospective time".
46
+ - Pair every commit count with a push count. The expensive unit is the push, which triggers CI and
47
+ bot reviewers: write "N pushes (M commits), each retriggering CI", not "N fix commits".
48
+ - Count bot review rounds as distinct pushes that triggered a review cycle, not individual comments.
@@ -0,0 +1,48 @@
1
+ # Sandbox and permission audit
2
+
3
+ The `## Sandbox & Permission Audit` section reports commands that were denied, escalated, or failed
4
+ under a sandbox. It is built from journal entries alone:
5
+
6
+ - `sandbox-escalation`, `sandbox-failure`, and `ambiguous-failure` blocks in the journal (see the
7
+ [blackboard](../../blackboard/SKILL.md#sandbox-and-permission-blocks) skill) are the source for
8
+ every escalation, denial, and failure on every harness.
9
+ - The `escalations` in `retrospective-transcript` facts are supplementary evidence, reported
10
+ separately under the transcript facts. They list tool calls whose arguments requested elevated
11
+ permissions, with a normalized command prefix, justification, and prefix rule, but only for
12
+ harnesses whose rollout records a sandbox-permission request on the tool call. Use them to check
13
+ that each reported request has a journal block; they do not replace one. The approval outcome is
14
+ not recorded in a stable shape, so never report one from these.
15
+
16
+ ## Reading the evidence
17
+
18
+ - Escalation frequency alone is not a policy gap. Attribute an escalation to a mechanism, such as
19
+ an argument-size limit from an oversized sandbox profile, only from the current normalized
20
+ diagnostic. Keep argument-limit failures, linked-worktree write denials, credential or network
21
+ boundaries, and deliberate policy refusals separate.
22
+ - A request is not approval or denial, and a localhost refusal is not proof of sandbox enforcement.
23
+ Report an outcome only when evidence shows it.
24
+ - A linked-worktree write denial needs the sandbox's write coverage to change; an allowlist entry
25
+ does not fix it.
26
+ - A denial from a rule working as intended, such as a blocked force push, is a hygiene count, not a
27
+ candidate for anything.
28
+
29
+ ## Decision criteria
30
+
31
+ Before treating an uncovered command as a gap, confirm it is invokable at `HEAD`: the binary, script,
32
+ or package entry it names still exists. A transcript can be stale.
33
+
34
+ - Genuine bypass, judged read-only and safe: a generic tool family belongs in machine-level policy,
35
+ not this repository. A checked-in script that must leave the sandbox gets the narrowest exact
36
+ entry the consumer's policy allows. Never allowlist a broad prefix such as a bare `git`.
37
+ - Genuine bypass needing network access whose safety is unclear: do not allowlist it because it
38
+ appeared once. Escalation is the correct behavior for a command that always needs a judgment call.
39
+ Flag it for a human.
40
+ - Human-rejected command: propose a block rule, but surface it for human review and never write a
41
+ deny rule from a retrospective. One rejection is one data point; confirm the pattern recurs.
42
+
43
+ ## Privacy
44
+
45
+ Report a normalized `<command> <subcommand>` prefix and counts, never the raw command line or a
46
+ justification verbatim. For a short command the prefix is the whole command, so a branch slug, short
47
+ path, or hostname can appear in it: skim and redact before saving. Retrospectives are distilled into
48
+ public issues.