specweave 1.0.586 → 1.0.587

package/dist/src/core/session/handoff-doc-format.js

@@ -0,0 +1,292 @@
+/**
+ * Handoff Doc Format — single source of truth
+ *
+ * Renders BOTH the durable handoff document and the copy-paste resume prompt
+ * from one {@link HandoffDocInput}. The CLI command, the PreCompact hook
+ * handler, and the vitest parity test all render through this module, so the
+ * doc format and paste-prompt cannot drift between code paths. The vskill
+ * self-contained skill inlines a byte-compatible template that references the
+ * same canonical section order + footer marker exported here.
+ *
+ * Design rules:
+ * - This module is PURE rendering. It does no IO, no git, no workspace
+ *   detection — callers pass already-captured + already-scrubbed data in.
+ * - The absolute doc path, the `.diff` path, and the per-tool resume matrix are
+ *   inputs/constants so the renderer is deterministic and testable.
+ * - The `Doc format v1` footer marker (DOC_FORMAT_MARKER) is the ownership
+ *   sentinel that lets the builder know a file is a prior handoff it may
+ *   overwrite, and the version handle for future format migrations.
+ *
+ * Part of increment 0867: Cross-Tool Work Handoff
+ * (AC-US1-02, AC-US2-04, AC-US5-01..04, AC-US6-02, AC-US6-05).
+ *
+ * @module core/session/handoff-doc-format
+ */
+/**
+ * Footer marker stamped at the bottom of every handoff doc.
+ *
+ * Doubles as the ownership sentinel: a root `./HANDOFF.md` containing this
+ * string is treated as a prior handoff (safe to overwrite); one lacking it is a
+ * foreign file the builder must not clobber.
+ */
+export const DOC_FORMAT_MARKER = 'Doc format v1';
+/**
+ * Delimiters wrapping the self-contained body in `--inline` paste-prompts.
+ * A resuming agent reads everything between these markers as the handoff.
+ */
+export const INLINE_BEGIN_MARKER = 'BEGIN HANDOFF';
+export const INLINE_END_MARKER = 'END HANDOFF';
+/**
+ * Canonical section headers, in render order. Exported so the vskill inlined
+ * template and the format-parity test (T-017) reference ONE source and fail at
+ * build time if either side reorders or renames a section.
+ */
+export const HANDOFF_SECTION_ORDER = [
+    'Where I Left Off',
+    'Done / Pending',
+    'Key Decisions & Gotchas',
+    'Files Touched',
+    'Exact Next Steps',
+    'How To Resume',
+    'Redaction',
+];
+/**
+ * The cross-tool resume matrix (AC-US5-01, AC-US5-02).
+ *
+ * NOTE on Claude: session files live under
+ * `~/.claude/projects/<munged-cwd>/<uuid>.jsonl`, where the cwd is munged by
+ * replacing EVERY non-alphanumeric char with `-` and NOT collapsing runs — so a
+ * leading slash and adjacent separators each become their own dash. Example:
+ *   /Users/.../specweave-umb/.claude-worktrees/x
+ *   → -Users-...-specweave-umb--claude-worktrees-x
+ * (the `/.` between `umb` and `claude-worktrees` yields a double dash).
+ */
+export const CLAUDE_MUNGE_EXAMPLE = '/Users/antonabyzov/Projects/github/specweave-umb/.claude-worktrees/x ' +
+    '→ -Users-antonabyzov-Projects-github-specweave-umb--claude-worktrees-x';
+export const TOOL_RESUME_MATRIX = [
+    {
+        tool: 'Claude Code',
+        findSession: 'ls ~/.claude/projects/<munged-cwd>/ (munge: every non-alphanumeric char → "-", runs NOT collapsed; e.g. ' +
+            CLAUDE_MUNGE_EXAMPLE + ')',
+        resumeCmd: 'claude -r <uuid>',
+    },
+    {
+        tool: 'Codex',
+        findSession: 'ls ~/.codex/sessions/ (newest dir = most recent session)',
+        resumeCmd: 'codex resume <uuid>   (or: codex resume --last)',
+    },
+    {
+        tool: 'OpenCode',
+        findSession: 'opencode sessions list',
+        resumeCmd: 'opencode -s <id>   (long form: opencode --session <id>)',
+    },
+    {
+        tool: 'Gemini CLI',
+        findSession: 'run /chat list inside the Gemini session to see saved tags',
+        resumeCmd: '/chat resume <tag>',
+    },
+    {
+        tool: 'Antigravity',
+        findSession: 'open the Antigravity Agent Manager and pick the prior task thread',
+        resumeCmd: 'resume the thread from the Antigravity Agent Manager',
+    },
+    {
+        tool: 'Aider',
+        findSession: 'aider keeps .aider.chat.history.md in the repo root',
+        resumeCmd: 'aider --restore-chat-history',
+    },
+];
+function fmtCount(counts) {
+    const entries = Object.entries(counts);
+    if (entries.length === 0) {
+        return '_No token-like strings were detected._';
+    }
+    return entries
+        .map(([type, n]) => `- ${n} \`${type}\` ${n === 1 ? 'string' : 'strings'} masked`)
+        .join('\n');
+}
+/**
+ * Render the per-tool "find your source session" block.
+ */
+export function renderResumeMatrix() {
+    const lines = ['## How To Resume', ''];
+    lines.push('If the doc path above does NOT exist on the machine you are reading this on, ' +
+        'STOP and ask the user to paste the handoff — do not improvise context.');
+    lines.push('');
+    lines.push('To recover the ORIGINAL transcript (optional), find your source session per tool:');
+    lines.push('');
+    for (const e of TOOL_RESUME_MATRIX) {
+        lines.push(`### ${e.tool}`);
+        lines.push(`- Find session: ${e.findSession}`);
+        lines.push(`- Resume: \`${e.resumeCmd}\``);
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+}
+/**
+ * Render the full handoff document body (markdown).
+ *
+ * Section order is locked to {@link HANDOFF_SECTION_ORDER}; the `Doc format v1`
+ * footer marker is always last.
+ */
+export function renderHandoffDoc(input) {
+    const L = [];
+    // ── Header ──────────────────────────────────────────────────────────────
+    const titleBit = input.increment?.title ? `: ${input.increment.title}` : '';
+    L.push(`# Work Handoff${titleBit}`);
+    L.push('');
+    L.push(`- Doc path: ${input.docPath}`);
+    L.push(`- Doc link: [${input.docPath}](${input.docPath})`);
+    L.push(`- Diff file: ${input.diffPath}`);
+    L.push(`- Generated: ${input.generatedAt}`);
+    L.push(`- Workspace: ${input.repoRoot} ${input.isSpecWeave ? '(SpecWeave)' : '(non-SpecWeave)'}`);
+    if (input.git.isGitRepo) {
+        L.push(`- Git: branch \`${input.git.branch || '(detached)'}\` @ \`${input.git.shortSha || '(no commits)'}\``);
+    }
+    L.push('');
+    // ── Where I Left Off ──────────────────────────────────────────────────────
+    L.push('## Where I Left Off');
+    L.push('');
+    if (input.reason)
+        L.push(`**Why handing off:** ${input.reason}`);
+    if (input.summary)
+        L.push(`**Summary:** ${input.summary}`);
+    if (input.increment) {
+        L.push(`**Increment:** ${input.increment.id} (status: ${input.increment.status})`);
+        if (input.increment.currentTask)
+            L.push(`**Current task:** ${input.increment.currentTask}`);
+        if (input.increment.nextTask)
+            L.push(`**Next task:** ${input.increment.nextTask}`);
+    }
+    else {
+        L.push('_No active SpecWeave increment — this is a git + interview handoff._');
+    }
+    L.push('');
+    // ── Done / Pending ──────────────────────────────────────────────────────
+    L.push('## Done / Pending');
+    L.push('');
+    if (input.increment) {
+        const inc = input.increment;
+        L.push(`- Tasks: ${inc.doneTasks}/${inc.totalTasks} done (${inc.taskPercentage}%), ` +
+            `${inc.totalTasks - inc.doneTasks} pending`);
+        L.push(`- ACs: ${inc.doneAcs}/${inc.totalAcs} checked`);
+        if (inc.acSyncEvents.length > 0) {
+            L.push('- AC/task drift (recent sync events):');
+            for (const ev of inc.acSyncEvents)
+                L.push(`  - ${ev}`);
+        }
+    }
+    else {
+        L.push('_No increment task/AC state available._');
+    }
+    L.push('');
+    // ── Key Decisions & Gotchas ───────────────────────────────────────────────
+    L.push('## Key Decisions & Gotchas');
+    L.push('');
+    if (input.decisions.length > 0) {
+        for (const d of input.decisions)
+            L.push(`- ${d}`);
+    }
+    else {
+        L.push('_No decisions recorded._');
+    }
+    if (input.gotcha) {
+        L.push('');
+        L.push(`**Gotcha:** ${input.gotcha}`);
+    }
+    if (input.ambient && (input.ambient.testMode || input.ambient.coverageTarget != null || input.ambient.wipLimit != null)) {
+        L.push('');
+        L.push('**Ambient rules (config.json):**');
+        if (input.ambient.testMode)
+            L.push(`- Test mode: ${input.ambient.testMode}`);
+        if (input.ambient.coverageTarget != null)
+            L.push(`- Coverage target: ${input.ambient.coverageTarget}%`);
+        if (input.ambient.wipLimit != null)
+            L.push(`- WIP limit: ${input.ambient.wipLimit}`);
+    }
+    L.push('');
+    // ── Files Touched ─────────────────────────────────────────────────────────
+    L.push('## Files Touched');
+    L.push('');
+    if (input.git.hasUncommittedChanges) {
+        L.push('**UNCOMMITTED** — commit, stash, or keep editing BEFORE doing anything destructive.');
+        L.push('');
+        L.push('```');
+        L.push(input.git.statusPorcelain || '(no porcelain output)');
+        L.push('```');
+        if (input.git.diffStat) {
+            L.push('');
+            L.push('```');
+            L.push(input.git.diffStat);
+            L.push('```');
+        }
+        L.push('');
+        L.push(`Full uncommitted diff: \`${input.diffPath}\` — read it or run ` +
+            '`git apply --check` against it to see the exact edits.');
+    }
+    else if (input.git.isGitRepo) {
+        L.push('_Working tree clean — no uncommitted edits._');
+    }
+    else {
+        L.push('_Not a git repository — no diff captured._');
+    }
+    L.push('');
+    // ── Exact Next Steps ──────────────────────────────────────────────────────
+    L.push('## Exact Next Steps');
+    L.push('');
+    if (input.next) {
+        L.push(input.next);
+    }
+    else if (input.increment?.nextTask) {
+        L.push(`Continue with: ${input.increment.nextTask}`);
+    }
+    else {
+        L.push('_No explicit next step recorded — review the summary above._');
+    }
+    L.push('');
+    // ── How To Resume (+ per-tool matrix) ─────────────────────────────────────
+    L.push(renderResumeMatrix());
+    L.push('');
+    // ── Redaction ─────────────────────────────────────────────────────────────
+    L.push('## Redaction');
+    L.push('');
+    L.push(fmtCount(input.redactionCounts));
+    L.push('');
+    L.push('_Scrubbing is heuristic (regex baseline). An empty redaction list is NOT a ' +
+        'guarantee this file is clean — review before sharing or committing._');
+    L.push('');
+    // ── Footer marker ─────────────────────────────────────────────────────────
+    L.push('---');
+    L.push(`<!-- ${DOC_FORMAT_MARKER} -->`);
+    return L.join('\n');
+}
+/**
+ * Render the copy-paste resume prompt.
+ *
+ * Default (file-reachable) mode points the next agent at the doc path. The
+ * `inline` mode embeds the FULL doc body between BEGIN/END markers for
+ * cross-machine resume where the file is unreachable (AC-US5-04).
+ */
+export function renderPastePrompt(input, opts = {}) {
+    const P = [];
+    if (opts.inline) {
+        P.push('Resume my work using the self-contained handoff below.');
+        P.push('This is a full handoff doc — treat everything between the markers as ground truth. ' +
+            'If it references a `.diff` path that does not exist on this machine, ask me to paste the diff.');
+        P.push('');
+        P.push(INLINE_BEGIN_MARKER);
+        P.push(renderHandoffDoc(input));
+        P.push(INLINE_END_MARKER);
+    }
+    else {
+        P.push(`Resume my work. Read the handoff doc at: ${input.docPath}`);
+        P.push('If that path does NOT exist on this machine, STOP and ask me to paste the handoff — ' +
+            'do not improvise context.');
+        P.push(`The exact uncommitted edits are in: ${input.diffPath}`);
+        if (input.increment) {
+            P.push(`Active increment: ${input.increment.id}. Pick up at the next pending task.`);
+        }
+    }
+    return P.join('\n');
+}
+//# sourceMappingURL=handoff-doc-format.js.map

package/dist/src/core/session/handoff-doc-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-doc-format.js","sourceRoot":"","sources":["../../../../src/core/session/handoff-doc-format.ts"],"names":[],"mappings":"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"}

package/dist/src/core/session/handoff-git-state.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Handoff Git State Capture
+ *
+ * Captures the cheap, deterministic git facts the handoff doc needs (branch,
+ * short sha, porcelain status, diff --stat) AND dumps the FULL working-tree +
+ * staged diff to a sibling `.diff` file. The full diff is captured for free via
+ * git — no LLM tokens are spent — and is the key in-flight-fidelity artifact:
+ * it lets the resuming agent see exactly what was changed but not yet committed.
+ *
+ * In a non-git directory every field degrades to empty and no error is thrown,
+ * so the non-SpecWeave fallback path still works on plain folders.
+ *
+ * Part of increment 0867: Cross-Tool Work Handoff (AC-US4-01..04).
+ *
+ * @module core/session/handoff-git-state
+ */
+/**
+ * Captured git state for the handoff doc.
+ */
+export interface GitState {
+    /** Whether `repoRoot` is inside a git work tree at all. */
+    isGitRepo: boolean;
+    /** Current branch name (empty if detached or non-git). */
+    branch: string;
+    /** Short commit SHA of HEAD (empty if no commits / non-git). */
+    shortSha: string;
+    /** `git status --porcelain` output (empty when clean or non-git). */
+    statusPorcelain: string;
+    /** Combined `git diff --stat` (working) + `git diff --cached --stat` (staged). */
+    diffStat: string;
+    /** True when there are working-tree or staged changes. */
+    hasUncommittedChanges: boolean;
+}
+/**
+ * Capture git state for `repoRoot` and dump the full uncommitted diff to
+ * `diffOutputPath`.
+ *
+ * The diff file always contains `git diff HEAD` (working-tree vs last commit)
+ * concatenated with `git diff --cached` (staged vs HEAD). When the repo is
+ * clean — or before the first commit — the file is written empty so callers can
+ * unconditionally link to it.
+ *
+ * @param repoRoot - Absolute path to the candidate repository root.
+ * @param diffOutputPath - Absolute path where the full diff is written.
+ * @returns The captured {@link GitState}; all-empty + `isGitRepo:false` when
+ *          `repoRoot` is not a git work tree (no throw).
+ */
+export declare function captureGitState(repoRoot: string, diffOutputPath: string): GitState;
+//# sourceMappingURL=handoff-git-state.d.ts.map

package/dist/src/core/session/handoff-git-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-git-state.d.ts","sourceRoot":"","sources":["../../../../src/core/session/handoff-git-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,2DAA2D;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,qBAAqB,EAAE,OAAO,CAAC;CAChC;AAqBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,QAAQ,CA6DlF"}

package/dist/src/core/session/handoff-git-state.js

@@ -0,0 +1,164 @@
+/**
+ * Handoff Git State Capture
+ *
+ * Captures the cheap, deterministic git facts the handoff doc needs (branch,
+ * short sha, porcelain status, diff --stat) AND dumps the FULL working-tree +
+ * staged diff to a sibling `.diff` file. The full diff is captured for free via
+ * git — no LLM tokens are spent — and is the key in-flight-fidelity artifact:
+ * it lets the resuming agent see exactly what was changed but not yet committed.
+ *
+ * In a non-git directory every field degrades to empty and no error is thrown,
+ * so the non-SpecWeave fallback path still works on plain folders.
+ *
+ * Part of increment 0867: Cross-Tool Work Handoff (AC-US4-01..04).
+ *
+ * @module core/session/handoff-git-state
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Run a git command, returning trimmed stdout or `null` on any failure.
+ *
+ * Uses execFileSync with an argument array (no shell) so paths and refs are
+ * never re-interpreted by a shell.
+ */
+function git(repoRoot, args) {
+    try {
+        return execFileSync('git', args, {
+            cwd: repoRoot,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            maxBuffer: 64 * 1024 * 1024, // diffs can be large
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Capture git state for `repoRoot` and dump the full uncommitted diff to
+ * `diffOutputPath`.
+ *
+ * The diff file always contains `git diff HEAD` (working-tree vs last commit)
+ * concatenated with `git diff --cached` (staged vs HEAD). When the repo is
+ * clean — or before the first commit — the file is written empty so callers can
+ * unconditionally link to it.
+ *
+ * @param repoRoot - Absolute path to the candidate repository root.
+ * @param diffOutputPath - Absolute path where the full diff is written.
+ * @returns The captured {@link GitState}; all-empty + `isGitRepo:false` when
+ *          `repoRoot` is not a git work tree (no throw).
+ */
+export function captureGitState(repoRoot, diffOutputPath) {
+    const empty = {
+        isGitRepo: false,
+        branch: '',
+        shortSha: '',
+        statusPorcelain: '',
+        diffStat: '',
+        hasUncommittedChanges: false,
+    };
+    const insideWorkTree = git(repoRoot, ['rev-parse', '--is-inside-work-tree']);
+    if (insideWorkTree !== 'true') {
+        // Still write an empty diff file so the doc's link target exists.
+        safeWriteDiff(diffOutputPath, '');
+        return empty;
+    }
+    const branch = git(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD']) ?? '';
+    const shortSha = git(repoRoot, ['rev-parse', '--short', 'HEAD']) ?? '';
+    const statusPorcelain = git(repoRoot, ['status', '--porcelain']) ?? '';
+    // Intent-to-add every untracked file so `git diff` includes its FULL body,
+    // not just a `??` porcelain line. Without this, brand-new uncommitted files —
+    // the most common in-flight-work case — would be captured as a filename only,
+    // breaking the spec's "exact uncommitted edits" promise (AC-US4-01/02).
+    // `add -N` records intent only (no content staged) but it DOES add an index
+    // entry, so we MUST revert it afterward to leave the user's real index exactly
+    // as we found it — a handoff is a read-only capture and must not silently
+    // change `git status`, `git stash`, or `git commit -a` behavior.
+    const intentAdded = stageIntentToAddUntracked(repoRoot, statusPorcelain);
+    // `git diff HEAD` covers working-tree vs HEAD; if there is no HEAD yet
+    // (no commits), fall back to plain `git diff` so brand-new repos still work.
+    const hasHead = shortSha !== '';
+    const workingDiff = (hasHead ? git(repoRoot, ['diff', 'HEAD']) : git(repoRoot, ['diff'])) ?? '';
+    const stagedDiff = (hasHead ? git(repoRoot, ['diff', '--cached']) : '') ?? '';
+    const workingStat = (hasHead ? git(repoRoot, ['diff', '--stat', 'HEAD']) : git(repoRoot, ['diff', '--stat'])) ?? '';
+    const stagedStat = (hasHead ? git(repoRoot, ['diff', '--cached', '--stat']) : '') ?? '';
+    // Restore the index: drop the intent-to-add entries we created so the user's
+    // staging area is byte-identical to its pre-handoff state.
+    unstageIntentToAdd(repoRoot, hasHead, intentAdded);
+    const diffStat = [workingStat, stagedStat].filter(Boolean).join('\n');
+    const fullDiff = [workingDiff, stagedDiff].filter(Boolean).join('\n');
+    safeWriteDiff(diffOutputPath, fullDiff);
+    const hasUncommittedChanges = statusPorcelain.length > 0;
+    return {
+        isGitRepo: true,
+        branch,
+        shortSha,
+        statusPorcelain,
+        diffStat,
+        hasUncommittedChanges,
+    };
+}
+/**
+ * Intent-to-add every untracked file from a porcelain status so its content
+ * shows up in `git diff`. Parses `??`-prefixed porcelain lines and runs a
+ * single `git add -N -- <paths...>`. Never throws — a failure here only means
+ * untracked bodies are omitted, which must not abort the handoff.
+ *
+ * `add -N` (intent-to-add) records that a path will be tracked but stages NO
+ * content. It DOES create an index entry, so the caller MUST pass the returned
+ * paths to {@link unstageIntentToAdd} once the diff has been captured to leave
+ * the user's real index untouched.
+ *
+ * @returns The untracked paths that were intent-to-added (empty if none).
+ */
+function stageIntentToAddUntracked(repoRoot, statusPorcelain) {
+    if (!statusPorcelain)
+        return [];
+    const untracked = statusPorcelain
+        .split('\n')
+        .filter((line) => line.startsWith('??'))
+        // Porcelain format is `XY <path>`; for untracked the path starts at col 3.
+        .map((line) => line.slice(3).trim())
+        .filter(Boolean);
+    if (untracked.length === 0)
+        return [];
+    // `--` guards against any path that looks like a flag.
+    git(repoRoot, ['add', '-N', '--', ...untracked]);
+    return untracked;
+}
+/**
+ * Revert the intent-to-add entries created by {@link stageIntentToAddUntracked}
+ * so the user's index is restored to its pre-handoff state. After this the
+ * affected files are untracked (`??`) again, exactly as before the capture.
+ *
+ * `git reset -- <paths>` clears the index entries when a HEAD exists. Before the
+ * first commit there is no HEAD, so `git reset` would fail; `git rm --cached
+ * --force -- <paths>` removes the intent entries in that case. Never throws — a
+ * failed revert must not abort the handoff (worst case: the index keeps the
+ * intent entries, which is the pre-fix behavior).
+ */
+function unstageIntentToAdd(repoRoot, hasHead, paths) {
+    if (paths.length === 0)
+        return;
+    if (hasHead) {
+        git(repoRoot, ['reset', '--quiet', '--', ...paths]);
+    }
+    else {
+        git(repoRoot, ['rm', '--cached', '--force', '--quiet', '--', ...paths]);
+    }
+}
+/**
+ * Write the diff file, creating the parent dir; never throws.
+ */
+function safeWriteDiff(diffOutputPath, content) {
+    try {
+        fs.mkdirSync(path.dirname(diffOutputPath), { recursive: true });
+        fs.writeFileSync(diffOutputPath, content, 'utf-8');
+    }
+    catch {
+        // Best-effort: a failed diff dump must not abort the handoff.
+    }
+}
+//# sourceMappingURL=handoff-git-state.js.map

package/dist/src/core/session/handoff-git-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-git-state.js","sourceRoot":"","sources":["../../../../src/core/session/handoff-git-state.ts"],"names":[],"mappings":"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"}

package/dist/src/core/session/handoff-secret-scrub.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Handoff Secret Scrub
+ *
+ * Regex-based redaction over both the handoff doc's free-text fields AND the
+ * captured git diff. This is a HEURISTIC baseline (regex only) — an empty
+ * redaction list is NOT a guarantee the content is clean. Opportunistic
+ * scanner support (gitleaks/trufflehog) is a deferred enhancement.
+ *
+ * Each match is replaced with a `[REDACTED-<type>]` marker, and the function
+ * returns a per-pattern counts map so the doc's "Redaction" section can report
+ * how many token-like strings were masked.
+ *
+ * Part of increment 0867: Cross-Tool Work Handoff (AC-US6-01, AC-US6-02).
+ *
+ * @module core/session/handoff-secret-scrub
+ */
+/**
+ * A single secret-detection pattern.
+ */
+export interface SecretPattern {
+    /** Stable type slug used in the `[REDACTED-<type>]` marker + counts map. */
+    type: string;
+    /** Regex matching the secret. MUST use the global flag for replace + count. */
+    regex: RegExp;
+}
+/**
+ * The 12 redaction patterns (AC-US6-01).
+ *
+ * Patterns are intentionally conservative: they match the well-known token
+ * prefixes plus enough trailing characters to avoid masking the prefix alone.
+ * Assignment-style secrets (`password=`, `api_key=`) capture the value up to
+ * whitespace.
+ */
+export declare const SECRET_PATTERNS: readonly SecretPattern[];
+/**
+ * Result of a scrub: the redacted text plus per-pattern occurrence counts.
+ */
+export interface ScrubResult {
+    /** Text with every matched secret replaced by `[REDACTED-<type>]`. */
+    scrubbed: string;
+    /** Map of pattern `type` → number of redactions (only non-zero entries). */
+    counts: Record<string, number>;
+}
+/**
+ * Scrub secrets from a block of text.
+ *
+ * Runs each declared pattern in order. Patterns are applied sequentially over
+ * the progressively-scrubbed text, so an already-redacted span cannot be
+ * matched a second time by a later pattern.
+ *
+ * @param text - Free-text or diff content to scrub.
+ * @returns Scrubbed text + per-pattern counts (only patterns that fired).
+ */
+export declare function scrubSecrets(text: string): ScrubResult;
+/**
+ * Total number of redactions across all patterns.
+ */
+export declare function totalRedactions(counts: Record<string, number>): number;
+//# sourceMappingURL=handoff-secret-scrub.d.ts.map

package/dist/src/core/session/handoff-secret-scrub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-secret-scrub.d.ts","sourceRoot":"","sources":["../../../../src/core/session/handoff-secret-scrub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAa1C,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAkBtD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEtE"}