vouchington-tooling 0.43.0 → 0.44.0

package/dist/retrospective-distill/args.mjs

@@ -0,0 +1,27 @@
+import { parseStringFlags } from "./flag-args.mjs";
+function requireIsoCutoff(value, flag) {
+    if (value === undefined)
+        throw new Error(`${flag} is required`);
+    if (Number.isNaN(Date.parse(value)))
+        throw new Error(`${flag} must be a valid ISO 8601 timestamp`);
+    return value;
+}
+/**
+ * Parses `<partition.jsonl> --retro-cutoff <iso> --session-cutoff <iso>`.
+ *
+ * The classifier never computes its own cutoffs: the eligibility rule is evaluated against
+ * whatever `retroCutoff`/`sessionCutoff` the caller passes in, so a classifier run always matches
+ * the caller's own idea of "eligible" for that same run.
+ */
+export function parseDistillClassifyArgs(argv) {
+    const { values, positional } = parseStringFlags(argv, ['--retro-cutoff', '--session-cutoff']);
+    const [partitionPath, ...extra] = positional;
+    if (partitionPath === undefined || extra.length > 0) {
+        throw new Error('expected exactly one positional argument: the partition JSONL path');
+    }
+    return {
+        partitionPath,
+        retroCutoff: requireIsoCutoff(values.get('--retro-cutoff'), '--retro-cutoff'),
+        sessionCutoff: requireIsoCutoff(values.get('--session-cutoff'), '--session-cutoff'),
+    };
+}

package/dist/retrospective-distill/checkpoint-entry.d.mts

@@ -0,0 +1,2 @@
+import type { SessionEntry } from './session-types.mts';
+export declare function isCheckpointEntry(entry: SessionEntry): boolean;

package/dist/retrospective-distill/checkpoint-entry.mjs

@@ -0,0 +1,11 @@
+// Historic hook-written journal entries stay in the journal until they are archived, even though
+// no hook appends them anymore: agents write their own journal entries. They kept
+// `type: "journal"` and carry this structural `checkpoint` field, which is the only marker that
+// tells one apart from an agent-written entry — the rendered markdown heading is never inspected.
+// Session-shape classification (shape.mts) reads it so those sessions stay `checkpoint-only`.
+const CHECKPOINT_KINDS = ['compaction', 'command-failure', 'pr-create', 'push'];
+const CHECKPOINT_ENTRY_FIELD = 'checkpoint';
+export function isCheckpointEntry(entry) {
+    const value = entry.data[CHECKPOINT_ENTRY_FIELD];
+    return typeof value === 'string' && CHECKPOINT_KINDS.includes(value);
+}

package/dist/retrospective-distill/fixtures.test-helpers.d.mts

@@ -0,0 +1,3 @@
+import type { Session, SessionEntry } from './session-types.mts';
+export declare function sessionFixture(overrides?: Partial<Session>): Session;
+export declare function entryFixture(overrides?: Partial<SessionEntry>): SessionEntry;

package/dist/retrospective-distill/fixtures.test-helpers.mjs

@@ -0,0 +1,21 @@
+export function sessionFixture(overrides = {}) {
+    return {
+        id: 'session-1',
+        parentSessionId: null,
+        agent: 'claude',
+        version: '1',
+        createdAt: '2026-07-01T00:00:00.000Z',
+        lastEntryAt: null,
+        archivedAt: null,
+        data: {},
+        ...overrides,
+    };
+}
+export function entryFixture(overrides = {}) {
+    return {
+        sessionId: 'session-1',
+        createdAt: '2026-07-01T00:00:00.000Z',
+        data: {},
+        ...overrides,
+    };
+}

package/dist/retrospective-distill/flag-args.d.mts

@@ -0,0 +1,5 @@
+export type ParsedFlagArgs = {
+    values: Map<string, string>;
+    positional: string[];
+};
+export declare function parseStringFlags(argv: string[], flags: readonly string[]): ParsedFlagArgs;

package/dist/retrospective-distill/flag-args.mjs

@@ -0,0 +1,31 @@
+// Walks argv for `--flag value` pairs. A value may itself start with a dash (a file path, say), so
+// a missing value is `undefined`, the end-of-options marker, or another recognized flag.
+export function parseStringFlags(argv, flags) {
+    const values = new Map();
+    const positional = [];
+    let optionsEnded = false;
+    let consumed = -1;
+    for (const [i, arg] of argv.entries()) {
+        if (i === consumed)
+            continue;
+        if (!optionsEnded && arg === '--') {
+            optionsEnded = true;
+        }
+        else if (!optionsEnded && flags.includes(arg)) {
+            const value = argv[i + 1];
+            if (value === undefined || value === '--' || flags.includes(value))
+                throw new Error(`${arg} requires a value`);
+            if (values.has(arg))
+                throw new Error(`${arg} may only be specified once`);
+            values.set(arg, value);
+            consumed = i + 1;
+        }
+        else if (!optionsEnded && arg.startsWith('-')) {
+            throw new Error(`unknown option: ${arg}`);
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { values, positional };
+}

package/dist/retrospective-distill/index.d.mts

@@ -0,0 +1,10 @@
+export { parseDistillClassifyArgs } from './args.mts';
+export type { DistillClassifyArgs } from './args.mts';
+export { isCheckpointEntry } from './checkpoint-entry.mts';
+export { readPartitionRecords } from './partition-records.mts';
+export type { PartitionData } from './partition-records.mts';
+export { isRetrospectiveEntry } from './retrospective-entry.mts';
+export { runDistillClassify } from './run.mts';
+export { classifySession } from './shape.mts';
+export type { DistillCutoffs, SessionClassification, SessionShape } from './shape.mts';
+export type { Session, SessionEntry } from './session-types.mts';

package/dist/retrospective-distill/index.mjs

@@ -0,0 +1,6 @@
+export { parseDistillClassifyArgs } from "./args.mjs";
+export { isCheckpointEntry } from "./checkpoint-entry.mjs";
+export { readPartitionRecords } from "./partition-records.mjs";
+export { isRetrospectiveEntry } from "./retrospective-entry.mjs";
+export { runDistillClassify } from "./run.mjs";
+export { classifySession } from "./shape.mjs";

package/dist/retrospective-distill/partition-records.d.mts

@@ -0,0 +1,6 @@
+import type { Session, SessionEntry } from './session-types.mts';
+export type PartitionData = {
+    sessions: Session[];
+    entriesBySession: Map<string, SessionEntry[]>;
+};
+export declare function readPartitionRecords(path: string): Promise<PartitionData>;

package/dist/retrospective-distill/partition-records.mjs

@@ -0,0 +1,49 @@
+import { readFile } from 'node:fs/promises';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// Mirrors the record envelope the agent-blackboard client's own partition writer emits: one JSON
+// object per line, discriminated by `type`. A partition file is written read-only only after its
+// own terminal `manifest` line has already validated, so this reader trusts the bytes on disk — it
+// does not re-verify partition integrity, only recognizes the shapes it can use. An unrecognized
+// `type` (a future upstream record kind, or the top-level snapshot stream's own `error` record,
+// which partition files never carry) is skipped rather than treated as fatal, so a
+// forward-compatible upstream release can't break this classifier.
+function parseLine(line) {
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch {
+        throw new Error('partition contains a line that is not valid JSON');
+    }
+    if (!isRecord(record) || typeof record.type !== 'string') {
+        throw new Error('partition contains a record with no string "type" field');
+    }
+    return record;
+}
+export async function readPartitionRecords(path) {
+    const raw = await readFile(path, 'utf8');
+    const sessions = [];
+    const entriesBySession = new Map();
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const record = parseLine(line);
+        if (record.type === 'session' && isRecord(record.session)) {
+            sessions.push(record.session);
+            continue;
+        }
+        if (record.type === 'entry' && isRecord(record.entry)) {
+            const entry = record.entry;
+            const existing = entriesBySession.get(entry.sessionId);
+            if (existing)
+                existing.push(entry);
+            else
+                entriesBySession.set(entry.sessionId, [entry]);
+        }
+        // 'manifest' (the partition's own terminal line) and any other record type carry no
+        // session-shape information for this classifier and are intentionally ignored.
+    }
+    return { sessions, entriesBySession };
+}

package/dist/retrospective-distill/retrospective-entry.d.mts

@@ -0,0 +1,3 @@
+import type { SessionEntry } from './session-types.mts';
+/** Whether a journal entry was written as a session retrospective. */
+export declare function isRetrospectiveEntry(entry: SessionEntry): boolean;

package/dist/retrospective-distill/retrospective-entry.mjs

@@ -0,0 +1,4 @@
+/** Whether a journal entry was written as a session retrospective. */
+export function isRetrospectiveEntry(entry) {
+    return entry.data.type === 'retrospective';
+}

package/dist/retrospective-distill/run.d.mts

@@ -0,0 +1,5 @@
+/**
+ * Pure local JSONL parsing plus classification — no network, blackboard client, or writes, so it
+ * can run under a read-only inspector sandbox. Returns one tab-separated line per session.
+ */
+export declare function runDistillClassify(argv: string[]): Promise<string>;

package/dist/retrospective-distill/run.mjs

@@ -0,0 +1,28 @@
+import { parseDistillClassifyArgs } from "./args.mjs";
+import { readPartitionRecords } from "./partition-records.mjs";
+import { classifySession } from "./shape.mjs";
+function formatLine(sessionId, shape, eligible) {
+    return `${sessionId}\t${shape}\t${eligible ? 'eligible' : 'not-yet-eligible'}`;
+}
+/**
+ * Pure local JSONL parsing plus classification — no network, blackboard client, or writes, so it
+ * can run under a read-only inspector sandbox. Returns one tab-separated line per session.
+ */
+export async function runDistillClassify(argv) {
+    const args = parseDistillClassifyArgs(argv);
+    const { sessions, entriesBySession } = await readPartitionRecords(args.partitionPath);
+    if (sessions.length === 0)
+        return 'No sessions found in partition.';
+    const cutoffs = { retroCutoff: args.retroCutoff, sessionCutoff: args.sessionCutoff };
+    return sessions
+        .map((session) => {
+        const entries = entriesBySession.get(session.id) ?? [];
+        const { shape, eligible, quarantine, duplicateEntryCount } = classifySession(session, entries, cutoffs);
+        const line = formatLine(session.id, shape, eligible) +
+            (duplicateEntryCount ? `\tduplicate-events=${duplicateEntryCount}` : '');
+        return quarantine
+            ? `${line}\tquarantined=${quarantine.entryCount};reasons=${quarantine.reasons.join(',')}`
+            : line;
+    })
+        .join('\n');
+}

package/dist/retrospective-distill/session-types.d.mts

@@ -0,0 +1,17 @@
+/** Structurally compatible with the agent-blackboard client's `Session`, so no client install is needed. */
+export interface Session {
+    id: string;
+    parentSessionId: string | null;
+    agent: string;
+    version: string;
+    createdAt: string;
+    lastEntryAt: string | null;
+    archivedAt: string | null;
+    data: Record<string, unknown>;
+}
+/** Structurally compatible with the agent-blackboard client's `SessionEntry`. */
+export interface SessionEntry {
+    sessionId: string;
+    createdAt: string;
+    data: Record<string, unknown>;
+}

package/dist/retrospective-distill/session-types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/retrospective-distill/shape.d.mts

@@ -0,0 +1,29 @@
+import type { Session, SessionEntry } from './session-types.mts';
+/**
+ * Session shape taxonomy and distillation eligibility.
+ *
+ * This code is the source of truth for both. The retrospective-distill skill is the canonical
+ * human-facing description; when an inspector's hand classification and this output disagree on
+ * the same session, fix the skill to match this code, not the other way around.
+ *
+ * `zero-entry-child` / `zero-entry-root` name a session-topology fact (whether `parentSessionId`
+ * is set), not a completion signal: a delegated child that dies mid-task is a zero-entry-child
+ * session too, indistinguishable here from one that finished its bounded assignment cleanly.
+ * Docs referencing this split must not imply "child" means "completed normally".
+ */
+export type SessionShape = 'retrospective' | 'entry-type-unresolved' | 'checkpoint-only' | 'journal-only' | 'zero-entry-child' | 'zero-entry-root';
+export type SessionClassification = {
+    sessionId: string;
+    shape: SessionShape;
+    eligible: boolean;
+    quarantine?: {
+        entryCount: number;
+        reasons: string[];
+    };
+    duplicateEntryCount?: number;
+};
+export type DistillCutoffs = {
+    retroCutoff: string;
+    sessionCutoff: string;
+};
+export declare function classifySession(session: Session, entries: SessionEntry[], cutoffs: DistillCutoffs): SessionClassification;

package/dist/retrospective-distill/shape.mjs

@@ -0,0 +1,111 @@
+import { isDeepStrictEqual } from 'node:util';
+import { validateFeedbackEnvelope } from "../agent-blackboard/index.mjs";
+import { isCheckpointEntry } from "./checkpoint-entry.mjs";
+import { isRetrospectiveEntry } from "./retrospective-entry.mjs";
+function quarantineReason(entry) {
+    if (entry.data.type !== 'journal' && entry.data.type !== 'retrospective')
+        return 'unknown-entry-type';
+    if (entry.data.schemaVersion !== undefined) {
+        try {
+            validateFeedbackEnvelope(entry.data);
+        }
+        catch {
+            return 'invalid-feedback-envelope';
+        }
+    }
+    return undefined;
+}
+function hasUnresolvedType(entry) {
+    return quarantineReason(entry) !== undefined;
+}
+function classifyShape(session, entries) {
+    if (entries.some(hasUnresolvedType))
+        return 'entry-type-unresolved';
+    if (entries.some(isRetrospectiveEntry))
+        return 'retrospective';
+    if (entries.length === 0) {
+        // Loose equality on purpose: a partition record missing `parentSessionId` entirely (the reader
+        // trusts the file on disk and does not re-validate every field against the Session interface —
+        // see partition-records.mts) must fall to zero-entry-root. This is a topology and capture-gap
+        // signal, never evidence of crash or clean completion. `=== null` would silently misroute
+        // `undefined` into the wrong, discarded bucket.
+        return session.parentSessionId == null ? 'zero-entry-root' : 'zero-entry-child';
+    }
+    return entries.every(isCheckpointEntry) ? 'checkpoint-only' : 'journal-only';
+}
+function newestRetrospectiveAt(entries) {
+    let newest;
+    for (const entry of entries) {
+        if (!isRetrospectiveEntry(entry))
+            continue;
+        if (newest === undefined || Date.parse(entry.createdAt) > Date.parse(newest))
+            newest = entry.createdAt;
+    }
+    return newest;
+}
+// Eligibility rule:
+// (has a retrospective entry AND retroAt < retroCutoff) OR (lastActive < sessionCutoff).
+// An entry-type-unresolved session gets no issue-filing or archival pass "this run, regardless of
+// its age", so it is never eligible — that check short-circuits before the formula.
+function isEligible(session, entries, shape, cutoffs) {
+    if (shape === 'entry-type-unresolved')
+        return false;
+    const retroAt = newestRetrospectiveAt(entries);
+    const staleRetro = retroAt !== undefined && Date.parse(retroAt) < Date.parse(cutoffs.retroCutoff);
+    const lastActive = entries.reduce((latest, entry) => Date.parse(entry.createdAt) > Date.parse(latest) ? entry.createdAt : latest, session.createdAt);
+    const staleSession = Date.parse(lastActive) < Date.parse(cutoffs.sessionCutoff);
+    return staleRetro || staleSession;
+}
+// An event is its session, `sourceEventId`, and content; the server assigns `timestamp` per attempt
+// (a retry or a late write beside it can store the same event twice), so it is not identity.
+function withoutTimestamp(data) {
+    return Object.fromEntries(Object.entries(data).filter(([key]) => key !== 'timestamp'));
+}
+function normalizeSourceEvents(entries) {
+    const events = new Map();
+    const unique = [];
+    let duplicateEntryCount = 0;
+    let conflictCount = 0;
+    for (const entry of entries) {
+        if (entry.data.schemaVersion !== 1 || quarantineReason(entry) !== undefined) {
+            unique.push(entry);
+            continue;
+        }
+        const key = `${entry.sessionId}:${String(entry.data.sourceEventId)}`;
+        const existing = events.get(key);
+        if (!existing) {
+            events.set(key, entry);
+            unique.push(entry);
+            continue;
+        }
+        if (!isDeepStrictEqual(withoutTimestamp(existing.data), withoutTimestamp(entry.data))) {
+            conflictCount++;
+            continue;
+        }
+        duplicateEntryCount++;
+        // At-least-once replay does not postpone a source event's distillation age.
+        if (Date.parse(entry.createdAt) < Date.parse(existing.createdAt)) {
+            unique[unique.indexOf(existing)] = entry;
+            events.set(key, entry);
+        }
+    }
+    return { unique, duplicateEntryCount, conflictCount };
+}
+export function classifySession(session, entries, cutoffs) {
+    const { unique, duplicateEntryCount, conflictCount } = normalizeSourceEvents(entries);
+    const shape = conflictCount ? 'entry-type-unresolved' : classifyShape(session, unique);
+    const reasons = entries
+        .map(quarantineReason)
+        .filter((reason) => reason !== undefined);
+    for (let index = 0; index < conflictCount; index++)
+        reasons.push('conflicting-source-event');
+    return {
+        sessionId: session.id,
+        shape,
+        eligible: isEligible(session, unique, shape, cutoffs),
+        ...(duplicateEntryCount ? { duplicateEntryCount } : {}),
+        ...(reasons.length === 0
+            ? {}
+            : { quarantine: { entryCount: reasons.length, reasons: [...new Set(reasons)].toSorted() } }),
+    };
+}

package/docs/mcp-server.md

@@ -278,7 +278,7 @@ with the repository's stack tooling instead.
 ### Tools
 
 - `pr_validate` (read-only): renders the body, runs the policy `validatePullRequest({ title, body,
-base, head, mode, pr? })` export and returns `{ body, errors, warnings }`. With `pr`, the live
+  base, head, mode, pr? })` export and returns `{ body, errors, warnings }`. With `pr`, the live
   body is read (never written) so its Shepherd Journal is preserved as in `pr_update`.
 - `pr_create` (additive): renders and validates (errors block), then calls the policy
   `pullRequestDefaults({ title, base, relatedIssues })` export for optional `labels`, `milestone`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -101,6 +101,11 @@
       "import": "./dist/require-up-to-date/index.mjs",
       "default": "./dist/require-up-to-date/index.mjs"
     },
+    "./fresh-base": {
+      "types": "./dist/fresh-base/index.d.mts",
+      "import": "./dist/fresh-base/index.mjs",
+      "default": "./dist/fresh-base/index.mjs"
+    },
     "./gitleaks-directory-scan": {
       "types": "./dist/gitleaks-directory-scan/index.d.mts",
       "import": "./dist/gitleaks-directory-scan/index.mjs",
@@ -136,6 +141,11 @@
       "import": "./dist/shared-context/index.mjs",
       "default": "./dist/shared-context/index.mjs"
     },
+    "./retrospective-distill": {
+      "types": "./dist/retrospective-distill/index.d.mts",
+      "import": "./dist/retrospective-distill/index.mjs",
+      "default": "./dist/retrospective-distill/index.mjs"
+    },
     "./source-module-graph": {
       "types": "./dist/source-module-graph/index.d.mts",
       "import": "./dist/source-module-graph/index.mjs",
@@ -321,6 +331,11 @@
       "import": "./dist/compiler-build/index.mjs",
       "default": "./dist/compiler-build/index.mjs"
     },
+    "./pull-request-diff": {
+      "types": "./dist/pull-request-diff/index.d.mts",
+      "import": "./dist/pull-request-diff/index.mjs",
+      "default": "./dist/pull-request-diff/index.mjs"
+    },
     "./github-projects": {
       "types": "./dist/github-projects/index.d.mts",
       "import": "./dist/github-projects/index.mjs",
@@ -364,7 +379,7 @@
   "dependencies": {
     "@types/mdast": "4.0.4",
     "@types/unist": "3.0.3",
-    "@typescript-eslint/parser": "^8.71.0",
+    "@typescript-eslint/parser": "^8.71.1",
     "csv-parse": "7.0.3",
     "csv-stringify": "6.9.0",
     "dockerfile-ast": "0.7.1",
@@ -377,7 +392,7 @@
   },
   "devDependencies": {
     "@ast-grep/cli": "0.45.3",
-    "@modelcontextprotocol/sdk": "1.32.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
     "agent-blackboard": "^0.6.1",

package/skills/agent-workflow/SKILL.md

@@ -22,10 +22,30 @@ evidence record.
 - Before handoff, use [evidence sweep](references/evidence-sweep.md).
 - For review, use [review](references/review.md).
 - For surfaced feedback, use [review response](references/review-response.md).
+- Before any rebase or lease push, use [four refs](references/four-refs.md).
 
 Load only the references required by the current phase. Keep scope changes explicit; a discovered
 blocker or follow-up does not authorize widening the task.
 
+## Close-out
+
+This section is the single home for the hand-off retrospective and merge-note rules.
+
+- Report actual validation, open pull requests, and remaining blockers.
+- **Hand-off retrospective.** When you hand a pull request to the human as ready, write one
+  [retrospective](../retrospective/SKILL.md) from the session that did the work, which reads that
+  session's transcripts and journal. A native stack gets one retrospective when the stack is handed
+  off, covering every layer; never one per layer or for an intermediate commit.
+- Give each hand-off its own `sourceEventId`, such as `handoff-pr<number>` (a stack uses its top
+  pull request's number), on both `retrospective_check` and `retrospective_save`. The default ID
+  fits only the first hand-off in a session; a second would be mistaken for it.
+- **Merge note.** If you are still running when the merge happens and it changes the outcome, such
+  as a merge-queue ejection and its fix, a follow-up push, or review comments addressed after
+  hand-off, append one short note with the [blackboard skill](../blackboard/SKILL.md). Name the
+  pull request and the retrospective's source event, and give the note its own `sourceEventId` (for
+  example `merge-pr<number>`): the writer rejects the retrospective's ID reused for different
+  content. Never write a second retrospective.
+
 ## Parallel by default
 
 Split work into independent units and run them concurrently, one worker and worktree each, within

package/skills/agent-workflow/references/four-refs.md

@@ -0,0 +1,74 @@
+# Reading the four refs
+
+Use before any rebase or lease push of a branch other agents or humans may also write. Publish this
+branch; do not open a replacement pull request.
+
+`origin` and `main` below stand for the consumer's remote and default branch; substitute the names
+local policy declares.
+
+## Setup
+
+- Run `git fetch origin main <branch>` as its own command. Never chain the fetch with a rebase,
+  reset, or merge.
+- HEAD must be the branch being updated. A stack checkout can leave the top layer checked out, so
+  check out the layer first. A missing stack field means membership is unknown, not unstacked.
+- A dirty worktree stops you before a fast-forward, reset, or rebase. Do not switch branches.
+- Continue a conflicted rebase with `GIT_EDITOR=true git rebase --continue`.
+
+## Read the refs
+
+- Print `git rev-parse` of HEAD, `origin/<branch>`, `origin/main`, and local `main` when it exists.
+  Local `main` is never the rebase target; when it exists, `git rev-list --left-right --count
+  main...origin/main` with a nonzero right count means local `main` is behind.
+- Print `git rev-list --left-right --count HEAD...origin/<branch>` (left: commits only on the
+  local branch; right: commits only on `origin/<branch>`) and
+  `git log --oneline --left-right HEAD...origin/<branch>`.
+- Print `git cherry -v origin/<branch> HEAD` and `git cherry -v HEAD origin/<branch>`. A leading `-`
+  is the same patch under another SHA; a leading `+` is a patch the other side lacks.
+- Treat `git range-diff` as a reading aid, not the rebase cut, and read it from the base those
+  commits were built on. Never run it from a new stack parent: after a stack rebase, old parent
+  commits look like unique local work.
+- Unmatched commits on `origin/<branch>` are new commits someone pushed.
+
+## Lease push
+
+- Capture `<sha>` with `git rev-parse origin/<branch>` after the fetch and before any rewrite. Push
+  a non-fast-forward with `git push --force-with-lease=<branch>:<sha> origin <branch>`, always
+  naming the remote and branch so a configured push remote cannot change the destination. With concurrent writers,
+  capture right after the setup fetch and before any later fetch, so a later fetch cannot silently
+  widen the lease.
+- If HEAD equals that SHA, do not push.
+- If a lease or non-force push is rejected, fetch again and re-read. It is still this branch.
+
+## Unstacked
+
+Before any move and after every move onto `origin/<branch>`, including when HEAD already equals it
+(`0 0`) but `origin/main` has advanced, run `git merge-base --is-ancestor origin/main HEAD`. Exit 0
+means the branch already contains `origin/main`; nonzero means rebase onto `origin/main`, then lease
+push.
+
+| Left/right                                                                                                                                                         | Action                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0 0`, `origin/main` already an ancestor                                                                                                                           | Stop.                                                                                                                                                                                                                                                                                                                                                   |
+| `0 0`, `origin/main` not an ancestor                                                                                                                               | Rebase onto `origin/main`, then lease push.                                                                                                                                                                                                                                                                                                             |
+| `0 N`                                                                                                                                                              | `git merge --ff-only origin/<branch>`, then the ancestor check.                                                                                                                                                                                                                                                                                         |
+| `N 0`                                                                                                                                                              | Read `git log --oneline origin/<branch>..HEAD`: those commits are what a push adds, including a remote rewind to an ancestor. Own unpushed work with `origin/main` an ancestor: `git push origin <branch>`. Otherwise rebase onto `origin/main`, then lease push. A rewind you did not make: stop and ask.                                              |
+| Diverged, local-only commits are rewritten copies (every local-only commit has cherry `-`; matching subjects alone do not prove equivalence), no unique local work | Clean tree, `git reset --hard origin/<branch>`, then the ancestor check.                                                                                                                                                                                                                                                                                |
+| Diverged, origin has new patches to keep and HEAD has unique local commits                                                                                         | `git rebase origin/<branch>` as its own command, then the ancestor check, then lease push whichever way the check exits (after another rebase onto `origin/main` if it is nonzero). This is the one added rebase target, not a license to rebase onto an arbitrary ref. If the rewrite changed patches and unique local work is mixed in, stop and ask. |
+
+## Stacked
+
+A stack rebase is the usual reason `origin/<branch>` was rewritten, but another agent or a human can
+rewrite an unstacked branch the same way.
+
+- On a diverged layer, adopt `origin/<branch>` with `git reset --hard` when the layer is checked
+  out, or `git branch -f` when it is not, if the left-right log shows pre-rebase copies: the same
+  layer subjects on both sides and old parent subjects only on the left. Require `git cherry`
+  patch equivalence (`-`) for every local layer commit first; matching subjects alone do not
+  prove it, and a `+` commit is unique local work.
+- Never `git rebase origin/<branch>` on a stack layer: it replays parent commits onto the layer.
+- Never run the plain rebase-onto-main procedure on a mid-stack branch; use its stack-aware form.
+- If the layer has unpushed commits that are not the old parent and not already on origin under a
+  new SHA, stop and ask.
+- After adopting the rewritten tip, run the stack-aware rebase only when the stack still needs to
+  move onto `origin/main`.

package/skills/blackboard/SKILL.md

@@ -50,7 +50,10 @@ human which case applies before continuing:
   registration and diagnosis steps.
 - Registered but disconnected: reconnect it through the harness's MCP controls, or restart the
   harness.
-- Automated runs with no human to ask: report "journaling unavailable" in the final report.
+- Automated runs with no human to ask: an unattended `interactive` run continues its primary work,
+  while an `autonomous` run keeps its admission gate below. The final report states why journaling
+  was unavailable, the `pendingCount` and `worktreePendingCount` (or that none was written), and
+  each unjournaled finding.
 
 Prefer restoring MCP over the CLI fallback below, and use the fallback only when the human asks or
 MCP cannot be restored for this session. Harness sandboxes commonly withhold
@@ -176,5 +179,22 @@ bounded structured facts or sanitized summaries, never raw command output, trans
 environment dumps, provider payloads, or secrets. Known-secret redaction supplements the author's
 minimization responsibility; it cannot prove arbitrary prose contains no undisclosed secret.
 
+## Credential failures
+
+- Never search shell profiles, `env`, or `.env*` files for a credential. Check presence only with
+  `[ -n "${VAR+x}" ] && echo SET || echo UNSET`; never copy the token around a sandbox denial.
+- A missing or stale credential blocks hosted delivery. In interactive mode the outbox keeps the
+  record visibly pending: do not drop it or invent a fallback. Ask the human to refresh the
+  connection, then restart the MCP client or call `outbox_flush`; an automated run reports.
+
+## Child identity for spawned agents
+
+- Pass the parent's own session id in the assignment prompt. The child resolves its own id from its
+  runtime through the consumer's identity policy, then calls `session_ensure` with it, the given
+  `parentSessionId`, its `agent`, and its version before other work. With no id or a failed ensure,
+  it stops and reports the blocker; never guess an id or pass a path, URL, or synthesized value.
+- A subagent sharing its parent's id must not `session_ensure` it as a child. It asks the parent
+  to append, or skips this protocol.
+
 Consumer wrappers own service configuration, server registration and approval rules, trusted mode
 selection, issue routing, and archival authorization. The server fixes the outbox location.

package/skills/github-issue/SKILL.md

@@ -99,5 +99,11 @@ For a batch, preflight every entry before writing any issue. One invalid entry f
 batch. A partial transport failure stops further creation and reports every issue already created.
 Do not retry an entry that succeeded.
 
+## Bounded output
+
+- A search returns at most five `#N: title -- url` lines.
+- A near-duplicate returns `Duplicate of #N: <url>`.
+- A mutation returns the action, URL, labels, and verification, plus milestone and project when set.
+
 Consumer wrapper owns: repository allowlist, taxonomy, issue template, credential, and CLI wrapper.
 It may tighten this gate and may not weaken it.