vouchington-tooling 0.56.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.
package/README.md CHANGED
@@ -584,6 +584,15 @@ there at construction and leaves the directory and other files alone. Applicatio
584
584
  directory are parameters. `checkFiniteTimeoutProfiles` writes one scratch project per admission
585
585
  profile and can take a caller-supplied runner.
586
586
 
587
+ `next-navigation-mock`, `jsdom-stubs` and `input-otp-mock` are test-only helpers for Vitest component
588
+ tests; `next` and `react` are optional peers, and each subpath imports only what it needs.
589
+ `vi.mock('next/navigation', () => navMockModule)` swaps in a singleton router whose spies and
590
+ state (`setSearchParams`, `setPathname`, `setParams`, `reset`) come from `createNavMock()`.
591
+ `installJsdomStubs()` adds no-op `ResizeObserver`, `IntersectionObserver`, `matchMedia` and
592
+ `scrollIntoView` only where jsdom lacks them. `installMemoryLocalStorage()` swaps in an in-memory
593
+ `localStorage` and returns it so `afterEach` can clear it. `vi.mock(import('input-otp'),
594
+ inputOtpMockFactory)` replaces the library's post-teardown timer with a plain input.
595
+
587
596
  `playwright` monitors browser console errors, web errors, dialogs, page crashes, and failed
588
597
  requests during Playwright tests. `@playwright/test` is an optional peer. `createBrowserTest` and
589
598
  `withMonitoredPage` install the generic telemetry blocks (Google Tag Manager, Google Analytics, and
@@ -0,0 +1,25 @@
1
+ import type { ComponentType, InputHTMLAttributes, ReactNode } from 'react';
2
+ type InputOtpProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'onChange' | 'pattern'> & {
3
+ children?: ReactNode;
4
+ onChange?: (value: string) => void;
5
+ containerClassName?: string;
6
+ pattern?: string | RegExp;
7
+ };
8
+ /**
9
+ * Factory for `vi.mock(import('input-otp'), inputOtpMockFactory)`. The real library schedules a
10
+ * password-manager timeout that can fire after jsdom teardown ("window is not defined"); this
11
+ * renders a plain text input that forwards `onChange(value)` instead.
12
+ */
13
+ export declare function inputOtpMockFactory(): Promise<{
14
+ OTPInput: ComponentType<InputOtpProps>;
15
+ OTPInputContext: import("react").Context<{
16
+ slots: {
17
+ char: string;
18
+ hasFakeCaret: boolean;
19
+ isActive: boolean;
20
+ }[];
21
+ }>;
22
+ REGEXP_ONLY_DIGITS: RegExp;
23
+ REGEXP_ONLY_DIGITS_AND_CHARS: RegExp;
24
+ }>;
25
+ export {};
@@ -0,0 +1,34 @@
1
+ const SLOT_COUNT = 8;
2
+ /**
3
+ * Factory for `vi.mock(import('input-otp'), inputOtpMockFactory)`. The real library schedules a
4
+ * password-manager timeout that can fire after jsdom teardown ("window is not defined"); this
5
+ * renders a plain text input that forwards `onChange(value)` instead.
6
+ */
7
+ export async function inputOtpMockFactory() {
8
+ const React = await import('react');
9
+ const OTPInputContext = React.createContext({
10
+ slots: Array.from({ length: SLOT_COUNT }, () => ({
11
+ char: '',
12
+ hasFakeCaret: false,
13
+ isActive: false,
14
+ })),
15
+ });
16
+ const OTPInput = React.forwardRef(function OTPInputMock({ children, maxLength, onChange, containerClassName, pattern, ...rest }, ref) {
17
+ const source = pattern instanceof RegExp ? pattern.source : pattern;
18
+ return React.createElement('div', { 'data-input-otp': true, maxLength, className: containerClassName }, React.createElement('input', {
19
+ type: 'text',
20
+ maxLength,
21
+ ref,
22
+ onChange: (event) => onChange?.(event.target.value),
23
+ pattern: source,
24
+ ...rest,
25
+ }), children);
26
+ });
27
+ OTPInput.displayName = 'OTPInput';
28
+ return {
29
+ OTPInput,
30
+ OTPInputContext,
31
+ REGEXP_ONLY_DIGITS: /^\d*$/,
32
+ REGEXP_ONLY_DIGITS_AND_CHARS: /^[a-zA-Z0-9]*$/,
33
+ };
34
+ }
@@ -0,0 +1,12 @@
1
+ /** In-memory `Storage`. Keep the returned object to `clear()` it between tests. */
2
+ export declare function createMemoryStorage(): Storage;
3
+ /**
4
+ * Replaces `localStorage` on `target` (and its `window`, when present) with a fresh in-memory
5
+ * store and returns it so the caller can clear it in `afterEach`.
6
+ */
7
+ export declare function installMemoryLocalStorage(target?: object): Storage;
8
+ /**
9
+ * Installs no-op `ResizeObserver`, `IntersectionObserver`, `matchMedia` and
10
+ * `HTMLElement.prototype.scrollIntoView` stubs, each only when jsdom leaves it undefined.
11
+ */
12
+ export declare function installJsdomStubs(target?: object): void;
@@ -0,0 +1,85 @@
1
+ const noop = () => { };
2
+ class StubResizeObserver {
3
+ observe = noop;
4
+ unobserve = noop;
5
+ disconnect = noop;
6
+ }
7
+ class StubIntersectionObserver {
8
+ observe = noop;
9
+ unobserve = noop;
10
+ disconnect = noop;
11
+ takeRecords() {
12
+ return [];
13
+ }
14
+ }
15
+ function stubMatchMedia(query) {
16
+ return {
17
+ matches: false,
18
+ media: query,
19
+ onchange: null,
20
+ addListener: noop,
21
+ removeListener: noop,
22
+ addEventListener: noop,
23
+ removeEventListener: noop,
24
+ dispatchEvent: () => false,
25
+ };
26
+ }
27
+ /** In-memory `Storage`. Keep the returned object to `clear()` it between tests. */
28
+ export function createMemoryStorage() {
29
+ const store = new Map();
30
+ return {
31
+ getItem: (key) => store.get(key) ?? null,
32
+ setItem: (key, value) => {
33
+ store.set(key, value);
34
+ },
35
+ removeItem: (key) => {
36
+ store.delete(key);
37
+ },
38
+ clear: () => {
39
+ store.clear();
40
+ },
41
+ get length() {
42
+ return store.size;
43
+ },
44
+ key: (index) => [...store.keys()][index] ?? null,
45
+ };
46
+ }
47
+ function asTarget(target) {
48
+ return target;
49
+ }
50
+ function define(target, name, value) {
51
+ Object.defineProperty(target, name, { configurable: true, writable: true, value });
52
+ }
53
+ /**
54
+ * Replaces `localStorage` on `target` (and its `window`, when present) with a fresh in-memory
55
+ * store and returns it so the caller can clear it in `afterEach`.
56
+ */
57
+ export function installMemoryLocalStorage(target = globalThis) {
58
+ const storage = createMemoryStorage();
59
+ define(target, 'localStorage', storage);
60
+ const win = target.window;
61
+ if (win !== undefined && win !== target)
62
+ define(win, 'localStorage', storage);
63
+ return storage;
64
+ }
65
+ /**
66
+ * Installs no-op `ResizeObserver`, `IntersectionObserver`, `matchMedia` and
67
+ * `HTMLElement.prototype.scrollIntoView` stubs, each only when jsdom leaves it undefined.
68
+ */
69
+ export function installJsdomStubs(target = globalThis) {
70
+ const global = asTarget(target);
71
+ if (global.ResizeObserver === undefined)
72
+ define(global, 'ResizeObserver', StubResizeObserver);
73
+ if (global.IntersectionObserver === undefined) {
74
+ define(global, 'IntersectionObserver', StubIntersectionObserver);
75
+ }
76
+ const win = global.window;
77
+ if (win === undefined)
78
+ return;
79
+ if (win.matchMedia === undefined)
80
+ define(win, 'matchMedia', stubMatchMedia);
81
+ const proto = win.HTMLElement?.prototype;
82
+ if (proto !== undefined && proto.scrollIntoView === undefined) {
83
+ define(proto, 'scrollIntoView', noop);
84
+ }
85
+ }
@@ -0,0 +1,27 @@
1
+ type NextNavigation = typeof import('next/navigation.js');
2
+ type SearchParamsInit = string | URLSearchParams | undefined;
3
+ /**
4
+ * Pass to `vi.mock('next/navigation', () => navMockModule)`. Hooks read the mutable state lazily,
5
+ * so changes made between tests apply on the next render. Import it before the component under
6
+ * test so the factory is initialized when the mock is evaluated.
7
+ */
8
+ export declare const navMockModule: NextNavigation;
9
+ /**
10
+ * Control object for the shared `navMockModule` singleton: repeated calls share spies and state.
11
+ * Call `reset()` in `beforeEach`.
12
+ */
13
+ export declare function createNavMock(): {
14
+ push: import("vitest").Mock<(...args: unknown[]) => unknown>;
15
+ replace: import("vitest").Mock<(...args: unknown[]) => unknown>;
16
+ refresh: import("vitest").Mock<(...args: unknown[]) => unknown>;
17
+ back: import("vitest").Mock<(...args: unknown[]) => unknown>;
18
+ forward: import("vitest").Mock<(...args: unknown[]) => unknown>;
19
+ prefetch: import("vitest").Mock<(...args: unknown[]) => unknown>;
20
+ /** Accepts the same init forms as `new URLSearchParams()`; `undefined` clears it. */
21
+ setSearchParams(init?: SearchParamsInit): void;
22
+ setPathname(pathname: string): void;
23
+ setParams(params: Record<string, string | string[]>): void;
24
+ /** Restores empty search params, pathname `/`, empty params, and clears spy history. */
25
+ reset(): void;
26
+ };
27
+ export {};
@@ -0,0 +1,58 @@
1
+ import { vi } from 'vitest';
2
+ const state = {
3
+ // A plain URLSearchParams at runtime; the cast only satisfies the real hook's return type.
4
+ searchParams: new URLSearchParams(),
5
+ pathname: '/',
6
+ params: {},
7
+ };
8
+ const push = vi.fn();
9
+ const replace = vi.fn();
10
+ const refresh = vi.fn();
11
+ const back = vi.fn();
12
+ const forward = vi.fn();
13
+ const prefetch = vi.fn();
14
+ const spies = [push, replace, refresh, back, forward, prefetch];
15
+ const router = { push, replace, refresh, back, forward, prefetch };
16
+ /**
17
+ * Pass to `vi.mock('next/navigation', () => navMockModule)`. Hooks read the mutable state lazily,
18
+ * so changes made between tests apply on the next render. Import it before the component under
19
+ * test so the factory is initialized when the mock is evaluated.
20
+ */
21
+ export const navMockModule = {
22
+ useRouter: () => router,
23
+ useSearchParams: () => state.searchParams,
24
+ usePathname: () => state.pathname,
25
+ useParams: () => state.params,
26
+ };
27
+ /**
28
+ * Control object for the shared `navMockModule` singleton: repeated calls share spies and state.
29
+ * Call `reset()` in `beforeEach`.
30
+ */
31
+ export function createNavMock() {
32
+ return {
33
+ push,
34
+ replace,
35
+ refresh,
36
+ back,
37
+ forward,
38
+ prefetch,
39
+ /** Accepts the same init forms as `new URLSearchParams()`; `undefined` clears it. */
40
+ setSearchParams(init) {
41
+ state.searchParams = new URLSearchParams(init);
42
+ },
43
+ setPathname(pathname) {
44
+ state.pathname = pathname;
45
+ },
46
+ setParams(params) {
47
+ state.params = params;
48
+ },
49
+ /** Restores empty search params, pathname `/`, empty params, and clears spy history. */
50
+ reset() {
51
+ state.searchParams = new URLSearchParams();
52
+ state.pathname = '/';
53
+ state.params = {};
54
+ for (const spy of spies)
55
+ spy.mockReset();
56
+ },
57
+ };
58
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vouchington-tooling",
3
- "version": "0.56.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.
@@ -31,8 +31,10 @@ Use when completed retrospectives or journals should become durable follow-up wo
31
31
  treating missing records as absent. Require `manifest.schemaVersion` to be 1, `manifest.status`
32
32
  to be `"complete"`, a nonempty `cleanupToken`, and manifest counts that exactly match the export
33
33
  counts, including the terminal manifest record. Hand subagents only read-only partitions of the
34
- verified file, never the original snapshot, and give each partition its own bounded session and
35
- byte limits. Read full records, with their storage type, repository
34
+ verified file, never the original snapshot. Bound each partition to at most 25 contiguous
35
+ session groups or 1 MiB. A session's record and entries form an indivisible group, so fail the run
36
+ rather than split a group or weaken the bound. Only the root keeps the `cleanupToken`; never
37
+ delegate it. Read full records, with their storage type, repository
36
38
  tags, source identity, coverage, and outcomes, from that file. Do not distill from
37
39
  `journal_entries`: it reads one session at a time and has no checksum or manifest to show that
38
40
  the read is complete. For repository-scoped work, filter sessions by
@@ -53,8 +55,14 @@ Use when completed retrospectives or journals should become durable follow-up wo
53
55
  drafting. Skip work that is complete, explicitly rejected, or already covered. A first-party version
54
56
  bump is not proof of resolution: verify the adopted change against the original finding before
55
57
  deferring. Capture a new observation in the journal before filing it.
58
+ Inspect against the refreshed remote default branch, never the local one, which may sit on an
59
+ unmerged branch. Before filing a claim such as "direct-to-main" or "merged without CI", verify it
60
+ with `git branch -r --contains <sha>` and `git merge-base --is-ancestor <sha> origin/<default>`.
61
+ Prefer a retrospective's generated verifiable facts over its narration, and verify journal-only
62
+ claims the same way before they reach an issue body; an agent's in-session narration is not
63
+ evidence.
56
64
  6. Draft self-contained issues with the problem, concrete proposed work, relevant areas, and
57
- validation. Route every authorized creation through
65
+ validation, using the [issue body template](references/issue-body.md). Route every authorized creation through
58
66
  [github-issue](../github-issue/SKILL.md), including its repository gate, label approval, and
59
67
  denied-external tracking behavior.
60
68
  7. Archive only verified records fully processed across every represented repository, and never
@@ -0,0 +1,40 @@
1
+ # Issue body template
2
+
3
+ Use this shape for a new issue and for a comment on an existing one. The body must be fully
4
+ self-contained: the source sessions are archived afterward, so never reference a session id, a
5
+ retrospective file name, or a local journal path. Embed the relevant evidence instead.
6
+
7
+ For a comment, open with a line such as "Additional context from recent retrospectives". Omit
8
+ `## Root cause` when the issue already documents it, or retitle it `## Additional root cause
9
+ context` when the comment adds new information.
10
+
11
+ ```markdown
12
+ ## Root cause
13
+
14
+ <the underlying process or tooling gap; for a recurring theme, why it keeps happening>
15
+
16
+ ## Problem
17
+
18
+ <symptoms with concrete PR and commit references>
19
+
20
+ ## Proposed fixes
21
+
22
+ - [ ] <each fix as a checkbox with the file path it touches>
23
+
24
+ ## Files / areas
25
+
26
+ - <existing paths verified at HEAD, and proposed paths marked `New`>
27
+
28
+ ## Context
29
+
30
+ <evidence lifted from the source records: the specific reflection text, root-cause notes, concrete
31
+ paths, and the relevant verifiable-fact figures (push and commit counts, diff scope) that motivated
32
+ the theme. Use only durable references: PR #N, issue #N, and the retrospective date (YYYY-MM-DD).>
33
+ ```
34
+
35
+ Journal entries are unminimized notes and can carry credentials or sensitive local context. Summarize
36
+ a finding in your own words; never paste a command line or stderr, and strip any long opaque token,
37
+ `VAR=value` assignment, or credential-bearing URL. Checking a claim against the remote default branch
38
+ verifies its accuracy; it does not sanitize the text.
39
+
40
+ Apply the path rules of [github-issue](../../github-issue/SKILL.md) to `## Files / areas`.
@@ -27,7 +27,11 @@ Use only non-interactive forms, and run every `gh stack` command without a TTY.
27
27
  create ordinary pull requests when stacks are disabled; without a TTY these fail instead, so treat
28
28
  a failure as the exit-9 recovery above rather than answering a prompt.
29
29
 
30
- - `gh stack init <branch>`, rooted on the default branch only.
30
+ - `gh stack init <branch>`, rooted on the default branch only. It roots the first layer at the
31
+ local default branch, not `origin/<default>`, and in a linked worktree `git fetch origin` does not
32
+ advance that ref. Fast-forward it with `git fetch origin <default>:<default>` only when no worktree
33
+ has the default branch checked out. Otherwise the checkout that has it fast-forwards itself with
34
+ `git merge --ff-only origin/<default>`; never move it from another worktree.
31
35
  - `gh stack add <branch>`, after the layer cap check in [SKILL.md](../SKILL.md#work-bottom-up).
32
36
  - `gh stack checkout <stack-or-pr-number>` imports an existing remote stack. See
33
37
  [Import a stack](#import-a-stack-before-acting-on-it).