vouchington-tooling 0.56.0 → 0.58.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 (59) hide show
  1. package/README.md +14 -0
  2. package/dist/agent-issue-labels/ensure-labels.d.mts +17 -0
  3. package/dist/agent-issue-labels/ensure-labels.mjs +55 -0
  4. package/dist/agent-issue-labels/index.d.mts +5 -0
  5. package/dist/agent-issue-labels/index.mjs +3 -0
  6. package/dist/agent-issue-labels/label-policy.d.mts +21 -0
  7. package/dist/agent-issue-labels/label-policy.mjs +67 -0
  8. package/dist/agent-issue-labels/labels-from-paths.d.mts +9 -0
  9. package/dist/agent-issue-labels/labels-from-paths.mjs +54 -0
  10. package/dist/cli/commands/agent-issue-labels.d.mts +2 -0
  11. package/dist/cli/commands/agent-issue-labels.mjs +17 -0
  12. package/dist/cli/index.mjs +6 -0
  13. package/dist/cli/parse-agent-issue-labels.d.mts +19 -0
  14. package/dist/cli/parse-agent-issue-labels.mjs +70 -0
  15. package/dist/cli/parse-forwarded-commands.d.mts +3 -0
  16. package/dist/cli/parse-forwarded-commands.mjs +2 -0
  17. package/dist/cli/parse.d.mts +5 -1
  18. package/dist/cli/parse.mjs +3 -0
  19. package/dist/cli/usage.d.mts +1 -1
  20. package/dist/cli/usage.mjs +5 -0
  21. package/dist/index.d.mts +2 -0
  22. package/dist/index.mjs +1 -0
  23. package/dist/input-otp-mock/index.d.mts +25 -0
  24. package/dist/input-otp-mock/index.mjs +34 -0
  25. package/dist/jsdom-stubs/index.d.mts +12 -0
  26. package/dist/jsdom-stubs/index.mjs +85 -0
  27. package/dist/next-navigation-mock/index.d.mts +27 -0
  28. package/dist/next-navigation-mock/index.mjs +58 -0
  29. package/dist/workflow-secrets-drift/cli.d.mts +10 -0
  30. package/dist/workflow-secrets-drift/cli.mjs +73 -0
  31. package/dist/workflow-secrets-drift/collect.d.mts +10 -0
  32. package/dist/workflow-secrets-drift/collect.mjs +70 -0
  33. package/dist/workflow-secrets-drift/drift.d.mts +22 -0
  34. package/dist/workflow-secrets-drift/drift.mjs +49 -0
  35. package/dist/workflow-secrets-drift/gh-parse.d.mts +5 -0
  36. package/dist/workflow-secrets-drift/gh-parse.mjs +41 -0
  37. package/dist/workflow-secrets-drift/gh.d.mts +4 -0
  38. package/dist/workflow-secrets-drift/gh.mjs +51 -0
  39. package/dist/workflow-secrets-drift/index.d.mts +11 -0
  40. package/dist/workflow-secrets-drift/index.mjs +6 -0
  41. package/dist/workflow-secrets-drift/inventory.d.mts +10 -0
  42. package/dist/workflow-secrets-drift/inventory.mjs +78 -0
  43. package/dist/workflow-secrets-drift/scopes.d.mts +12 -0
  44. package/dist/workflow-secrets-drift/scopes.mjs +56 -0
  45. package/dist/workflow-secrets-drift/settle.d.mts +3 -0
  46. package/dist/workflow-secrets-drift/settle.mjs +19 -0
  47. package/dist/workflow-secrets-drift/types.d.mts +33 -0
  48. package/dist/workflow-secrets-drift/types.mjs +1 -0
  49. package/package.json +39 -1
  50. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
  51. package/skills/blackboard/SKILL.md +19 -0
  52. package/skills/github-issue/SKILL.md +12 -0
  53. package/skills/manifest.json +20 -20
  54. package/skills/retrospective/SKILL.md +17 -1
  55. package/skills/retrospective/references/ci-failures.md +48 -0
  56. package/skills/retrospective/references/sandbox-audit.md +48 -0
  57. package/skills/retrospective-distill/SKILL.md +11 -3
  58. package/skills/retrospective-distill/references/issue-body.md +40 -0
  59. package/skills/stacked-prs/references/gh-stack.md +5 -1
@@ -0,0 +1,78 @@
1
+ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
2
+ if (typeof path === "string" && /^\.\.?\//.test(path)) {
3
+ return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
4
+ return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
5
+ });
6
+ }
7
+ return path;
8
+ };
9
+ import { resolve } from 'node:path';
10
+ import { pathToFileURL } from 'node:url';
11
+ export const DEFAULT_INVENTORY_PATH = '.github/workflows/workflow-secrets-inventory.mts';
12
+ export const DEFAULT_INVENTORY_EXPORT = 'SECRET_INVENTORY';
13
+ const OPTIONAL_FIELDS = [
14
+ ['neverProvision', 'boolean'],
15
+ ['requiredEnvironment', 'string'],
16
+ ['requiredBranchPolicy', 'string'],
17
+ ];
18
+ function entryProblem(entry) {
19
+ if (typeof entry !== 'object' || entry === null)
20
+ return 'must be an object';
21
+ return recordProblem(entry);
22
+ }
23
+ function recordProblem(record) {
24
+ if (typeof record.provisioned !== 'boolean')
25
+ return 'must have a boolean provisioned';
26
+ for (const [field, type] of OPTIONAL_FIELDS) {
27
+ if (record[field] !== undefined && typeof record[field] !== type) {
28
+ return `${field} must be a ${type}`;
29
+ }
30
+ }
31
+ if (record.neverProvision && record.provisioned) {
32
+ return 'neverProvision cannot be combined with provisioned: true';
33
+ }
34
+ if (record.neverProvision && (record.requiredEnvironment ?? record.requiredBranchPolicy)) {
35
+ return 'neverProvision cannot be combined with a required scope';
36
+ }
37
+ if (record.requiredEnvironment !== undefined && record.requiredBranchPolicy !== undefined) {
38
+ return 'requiredEnvironment and requiredBranchPolicy are mutually exclusive';
39
+ }
40
+ return undefined;
41
+ }
42
+ /**
43
+ * GitHub stores secret names upper-case and treats environment names case-insensitively, so
44
+ * names are compared as upper-case secrets and lower-case environments.
45
+ */
46
+ export function normalizeInventory(inventory) {
47
+ const normalized = {};
48
+ for (const [name, entry] of Object.entries(inventory)) {
49
+ const { requiredEnvironment, requiredBranchPolicy } = entry;
50
+ if (Object.hasOwn(normalized, name.toUpperCase())) {
51
+ throw new Error(`inventory names collide after normalization: ${name}`);
52
+ }
53
+ normalized[name.toUpperCase()] = {
54
+ ...entry,
55
+ ...(requiredEnvironment === undefined
56
+ ? {}
57
+ : { requiredEnvironment: requiredEnvironment.toLowerCase() }),
58
+ ...(requiredBranchPolicy === undefined
59
+ ? {}
60
+ : { requiredBranchPolicy: requiredBranchPolicy.toLowerCase() }),
61
+ };
62
+ }
63
+ return normalized;
64
+ }
65
+ /** Loads the named export of an inventory module (resolved against `cwd`) and checks its shape. */
66
+ export async function loadInventory(modulePath, exportName, cwd = process.cwd()) {
67
+ const loaded = (await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(cwd, modulePath)).href)));
68
+ const inventory = loaded[exportName];
69
+ if (typeof inventory !== 'object' || inventory === null || Array.isArray(inventory)) {
70
+ throw new Error(`${modulePath} must export an object named ${exportName}`);
71
+ }
72
+ for (const [name, entry] of Object.entries(inventory)) {
73
+ const problem = entryProblem(entry);
74
+ if (problem !== undefined)
75
+ throw new Error(`${modulePath}: ${exportName}.${name} ${problem}`);
76
+ }
77
+ return inventory;
78
+ }
@@ -0,0 +1,12 @@
1
+ import type { EnvironmentDeploymentBranchPolicy, WorkflowSecretInventory } from './types.mts';
2
+ export declare function requiredEnvironmentNames(inventory: WorkflowSecretInventory): Set<string>;
3
+ export interface ScopeInput {
4
+ repositoryNames: ReadonlySet<string>;
5
+ environmentNames: ReadonlyMap<string, ReadonlySet<string>>;
6
+ organizationNames: ReadonlySet<string>;
7
+ environmentDeploymentBranchPolicies: ReadonlyMap<string, EnvironmentDeploymentBranchPolicy>;
8
+ /** The only branch a required environment may deploy from. */
9
+ deploymentBranch: string;
10
+ }
11
+ /** Names whose checked-in scope contract disagrees with the live secret metadata. */
12
+ export declare function requiredSecretScopeViolations(inventory: WorkflowSecretInventory, input: ScopeInput): string[];
@@ -0,0 +1,56 @@
1
+ export function requiredEnvironmentNames(inventory) {
2
+ const names = new Set();
3
+ for (const entry of Object.values(inventory)) {
4
+ if (entry.requiredEnvironment !== undefined)
5
+ names.add(entry.requiredEnvironment);
6
+ if (entry.requiredBranchPolicy !== undefined)
7
+ names.add(entry.requiredBranchPolicy);
8
+ }
9
+ return names;
10
+ }
11
+ function permitsOnlyBranch(policy, branch) {
12
+ const [rule] = policy?.deploymentBranchRules ?? [];
13
+ return (policy?.protectedBranchesEnabled === false &&
14
+ policy.customBranchPoliciesEnabled &&
15
+ policy.deploymentBranchRules.length === 1 &&
16
+ rule?.name === branch &&
17
+ rule.type === 'branch');
18
+ }
19
+ /** Names whose checked-in scope contract disagrees with the live secret metadata. */
20
+ export function requiredSecretScopeViolations(inventory, input) {
21
+ const { repositoryNames, environmentNames, organizationNames } = input;
22
+ const violations = [];
23
+ const rejectOtherScopes = (name, keepEnvironment) => {
24
+ for (const [environment, names] of environmentNames) {
25
+ if (environment !== keepEnvironment && names.has(name)) {
26
+ violations.push(`${name} must not exist in environment ${environment}`);
27
+ }
28
+ }
29
+ if (organizationNames.has(name)) {
30
+ violations.push(`${name} must not exist as an organization secret`);
31
+ }
32
+ };
33
+ for (const [name, entry] of Object.entries(inventory)) {
34
+ if (entry.requiredEnvironment) {
35
+ if (entry.provisioned && !environmentNames.get(entry.requiredEnvironment)?.has(name)) {
36
+ violations.push(`${name} is missing from environment ${entry.requiredEnvironment}`);
37
+ }
38
+ if (repositoryNames.has(name))
39
+ violations.push(`${name} must not exist as a repository secret`);
40
+ rejectOtherScopes(name, entry.requiredEnvironment);
41
+ }
42
+ else if (entry.requiredBranchPolicy) {
43
+ if (entry.provisioned && !repositoryNames.has(name)) {
44
+ violations.push(`${name} is missing from repository secrets`);
45
+ }
46
+ rejectOtherScopes(name, undefined);
47
+ }
48
+ }
49
+ for (const environment of requiredEnvironmentNames(inventory)) {
50
+ const policy = input.environmentDeploymentBranchPolicies.get(environment);
51
+ if (!permitsOnlyBranch(policy, input.deploymentBranch)) {
52
+ violations.push(`environment ${environment} must permit deployments from only ${input.deploymentBranch}`);
53
+ }
54
+ }
55
+ return violations;
56
+ }
@@ -0,0 +1,3 @@
1
+ export declare const errorMessage: (error: unknown) => string;
2
+ /** `Promise.allSettled` over `items` with at most `limit` mappers in flight; results keep input order. */
3
+ export declare function settleLimited<T, R>(items: readonly T[], limit: number, mapper: (item: T) => Promise<R>): Promise<PromiseSettledResult<R>[]>;
@@ -0,0 +1,19 @@
1
+ export const errorMessage = (error) => error instanceof Error ? error.message : String(error);
2
+ /** `Promise.allSettled` over `items` with at most `limit` mappers in flight; results keep input order. */
3
+ export async function settleLimited(items, limit, mapper) {
4
+ const results = Array.from({ length: items.length });
5
+ let next = 0;
6
+ const worker = async () => {
7
+ while (next < items.length) {
8
+ const index = next++;
9
+ try {
10
+ results[index] = { status: 'fulfilled', value: await mapper(items[index]) };
11
+ }
12
+ catch (reason) {
13
+ results[index] = { status: 'rejected', reason };
14
+ }
15
+ }
16
+ };
17
+ await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
18
+ return results;
19
+ }
@@ -0,0 +1,33 @@
1
+ import type { SecretInventoryEntry } from '../workflow-policy/secret-readiness.mts';
2
+ /**
3
+ * One inventory entry. Extends the readiness inventory entry with the optional drift and scope
4
+ * contracts. Only secret names and presence are ever read; values never leave the secret store.
5
+ */
6
+ export interface WorkflowSecretInventoryEntry extends SecretInventoryEntry {
7
+ /** Secret must live only in this environment, never as a repository, other-environment or organization secret. */
8
+ readonly requiredEnvironment?: string;
9
+ /** Environment kept only for its deployment-branch gate while the secret itself is repository scoped. */
10
+ readonly requiredBranchPolicy?: string;
11
+ /** Contract-only placeholder name that must never become a real secret. */
12
+ readonly neverProvision?: boolean;
13
+ }
14
+ export type WorkflowSecretInventory = Readonly<Record<string, WorkflowSecretInventoryEntry>>;
15
+ export interface DeploymentBranchRule {
16
+ name: string;
17
+ type: string;
18
+ }
19
+ export interface EnvironmentDeploymentBranchPolicy {
20
+ protectedBranchesEnabled: boolean;
21
+ customBranchPoliciesEnabled: boolean;
22
+ deploymentBranchRules: DeploymentBranchRule[];
23
+ }
24
+ /** Live secret-store reads. Every method returns names or metadata, never secret values. */
25
+ export interface WorkflowSecretsDependencies {
26
+ resolveRepo: () => Promise<string>;
27
+ listRepoSecretNames: (repo: string) => Promise<string[]>;
28
+ listRepositoryOwnerType: (repo: string) => Promise<string>;
29
+ listRepositoryOrganizationSecretNames: (repo: string) => Promise<string[]>;
30
+ listEnvironmentNames: (repo: string) => Promise<string[]>;
31
+ listEnvironmentSecretNames: (repo: string, environment: string) => Promise<string[]>;
32
+ getEnvironmentDeploymentBranchPolicy: (repo: string, environment: string) => Promise<EnvironmentDeploymentBranchPolicy>;
33
+ }
@@ -0,0 +1 @@
1
+ export {};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vouchington-tooling",
3
- "version": "0.56.0",
3
+ "version": "0.58.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": {
@@ -171,6 +171,11 @@
171
171
  "import": "./dist/gha-artifacts-cleanup/index.mjs",
172
172
  "default": "./dist/gha-artifacts-cleanup/index.mjs"
173
173
  },
174
+ "./agent-issue-labels": {
175
+ "types": "./dist/agent-issue-labels/index.d.mts",
176
+ "import": "./dist/agent-issue-labels/index.mjs",
177
+ "default": "./dist/agent-issue-labels/index.mjs"
178
+ },
174
179
  "./http-origin": {
175
180
  "types": "./dist/http-origin/index.d.mts",
176
181
  "import": "./dist/http-origin/index.mjs",
@@ -301,6 +306,11 @@
301
306
  "import": "./dist/dependency-license-policy/index.mjs",
302
307
  "default": "./dist/dependency-license-policy/index.mjs"
303
308
  },
309
+ "./workflow-secrets-drift": {
310
+ "types": "./dist/workflow-secrets-drift/index.d.mts",
311
+ "import": "./dist/workflow-secrets-drift/index.mjs",
312
+ "default": "./dist/workflow-secrets-drift/index.mjs"
313
+ },
304
314
  "./nuget-central-version": {
305
315
  "types": "./dist/nuget-central-version/index.d.mts",
306
316
  "import": "./dist/nuget-central-version/index.mjs",
@@ -391,6 +401,21 @@
391
401
  "types": "./dist/post-publication-inventory/index.d.mts",
392
402
  "import": "./dist/post-publication-inventory/index.mjs",
393
403
  "default": "./dist/post-publication-inventory/index.mjs"
404
+ },
405
+ "./next-navigation-mock": {
406
+ "types": "./dist/next-navigation-mock/index.d.mts",
407
+ "import": "./dist/next-navigation-mock/index.mjs",
408
+ "default": "./dist/next-navigation-mock/index.mjs"
409
+ },
410
+ "./jsdom-stubs": {
411
+ "types": "./dist/jsdom-stubs/index.d.mts",
412
+ "import": "./dist/jsdom-stubs/index.mjs",
413
+ "default": "./dist/jsdom-stubs/index.mjs"
414
+ },
415
+ "./input-otp-mock": {
416
+ "types": "./dist/input-otp-mock/index.d.mts",
417
+ "import": "./dist/input-otp-mock/index.mjs",
418
+ "default": "./dist/input-otp-mock/index.mjs"
394
419
  }
395
420
  },
396
421
  "publishConfig": {
@@ -421,15 +446,22 @@
421
446
  "@modelcontextprotocol/sdk": "1.32.1",
422
447
  "@playwright/test": "1.64.1",
423
448
  "@types/picomatch": "^4.0.3",
449
+ "@types/react": "19.3.0",
450
+ "@types/react-dom": "19.3.0",
424
451
  "@types/spdx-expression-parse": "4.0.0",
452
+ "next": "16.4.2",
425
453
  "no-mistakes": "0.83.0",
454
+ "react": "19.3.1",
455
+ "react-dom": "19.3.1",
426
456
  "smol-toml": "1.9.1",
427
457
  "typescript5": "npm:typescript@5.9.3"
428
458
  },
429
459
  "peerDependencies": {
430
460
  "@modelcontextprotocol/sdk": "^1.31.0",
431
461
  "@playwright/test": ">=1.64.1",
462
+ "next": ">=15",
432
463
  "no-mistakes": "*",
464
+ "react": ">=18",
433
465
  "typescript": ">=5",
434
466
  "vitest": ">=5"
435
467
  },
@@ -440,9 +472,15 @@
440
472
  "@playwright/test": {
441
473
  "optional": true
442
474
  },
475
+ "next": {
476
+ "optional": true
477
+ },
443
478
  "no-mistakes": {
444
479
  "optional": true
445
480
  },
481
+ "react": {
482
+ "optional": true
483
+ },
446
484
  "typescript": {
447
485
  "optional": true
448
486
  },
@@ -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.