specweave 1.0.585 → 1.0.587

package/dist/src/core/session/handoff-secret-scrub.js

@@ -0,0 +1,72 @@
+/**
+ * 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
+ */
+/**
+ * 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 const SECRET_PATTERNS = [
+    { type: 'openai-key', regex: /sk-[A-Za-z0-9_-]{16,}/g },
+    { type: 'github-token', regex: /ghp_[A-Za-z0-9]{20,}/g },
+    { type: 'github-oauth', regex: /gho_[A-Za-z0-9]{20,}/g },
+    { type: 'github-server', regex: /ghs_[A-Za-z0-9]{20,}/g },
+    { type: 'aws-key', regex: /AKIA[0-9A-Z]{12,}/g },
+    { type: 'aws-temp-key', regex: /ASIA[0-9A-Z]{12,}/g },
+    { type: 'private-key', regex: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/g },
+    { type: 'vskill-token', regex: /vsk_[A-Za-z0-9]{16,}/g },
+    { type: 'slack-token', regex: /xox[bap]-[A-Za-z0-9-]{10,}/g },
+    { type: 'bearer', regex: /Bearer\s+[A-Za-z0-9._~+/=-]{8,}/g },
+    { type: 'password', regex: /password=\S+/gi },
+    { type: 'api-key', regex: /api_key=\S+/gi },
+];
+/**
+ * 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 function scrubSecrets(text) {
+    const counts = {};
+    let scrubbed = text ?? '';
+    for (const { type, regex } of SECRET_PATTERNS) {
+        // Fresh lastIndex per call (regex literals are module-scoped + global).
+        regex.lastIndex = 0;
+        let matched = 0;
+        scrubbed = scrubbed.replace(regex, () => {
+            matched += 1;
+            return `[REDACTED-${type}]`;
+        });
+        if (matched > 0) {
+            counts[type] = matched;
+        }
+    }
+    return { scrubbed, counts };
+}
+/**
+ * Total number of redactions across all patterns.
+ */
+export function totalRedactions(counts) {
+    return Object.values(counts).reduce((sum, n) => sum + n, 0);
+}
+//# sourceMappingURL=handoff-secret-scrub.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-secret-scrub.js","sourceRoot":"","sources":["../../../../src/core/session/handoff-secret-scrub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAYH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAA6B;IACvD,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,wBAAwB,EAAE;IACvD,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,uBAAuB,EAAE;IACxD,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,uBAAuB,EAAE;IACxD,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,uBAAuB,EAAE;IACzD,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,oBAAoB,EAAE;IAChD,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,oBAAoB,EAAE;IACrD,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,wCAAwC,EAAE;IACxE,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,uBAAuB,EAAE;IACxD,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,6BAA6B,EAAE;IAC7D,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,kCAAkC,EAAE;IAC7D,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,gBAAgB,EAAE;IAC7C,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,EAAE;CACnC,CAAC;AAYX;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,IAAI,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC;IAE1B,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,eAAe,EAAE,CAAC;QAC9C,wEAAwE;QACxE,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;QACpB,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE;YACtC,OAAO,IAAI,CAAC,CAAC;YACb,OAAO,aAAa,IAAI,GAAG,CAAC;QAC9B,CAAC,CAAC,CAAC;QACH,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;QACzB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,MAA8B;IAC5D,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AAC9D,CAAC"}

package/dist/src/core/session/{handoff-context.d.ts → install-handoff-context.d.ts}

@@ -1,5 +1,9 @@
 /**
- * Handoff Context Generator
+ * Plugin-Install Handoff Context Generator
+ *
+ * NOTE: This is the legacy plugin-INSTALL handoff (renamed from
+ * `handoff-context.ts` in 0867 to free that name for the cross-tool work
+ * handoff). It is unrelated to `work-handoff.ts` / `handoff-doc-format.ts`.
  *
  * Generates context information for session handoff, enabling users
  * to continue their work in a new session after plugin installation.
@@ -11,7 +15,7 @@
  * - Available skills from those plugins
  * - Suggested continuation prompt
  *
- * @module core/session/handoff-context
+ * @module core/session/install-handoff-context
  */
 /**
  * A skill/command available from an installed plugin
@@ -96,4 +100,4 @@ export declare function generateHandoffContext(options: HandoffContextOptions):
  * ```
  */
 export declare function formatHandoffText(options: HandoffContextOptions): string;
-//# sourceMappingURL=handoff-context.d.ts.map
+//# sourceMappingURL=install-handoff-context.d.ts.map

package/dist/src/core/session/install-handoff-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-handoff-context.d.ts","sourceRoot":"","sources":["../../../../src/core/session/install-handoff-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,gCAAgC;IAChC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gCAAgC;IAChC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wBAAwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,eAAe,EAAE,KAAK,EAAE,CAAC;IACzB,kDAAkD;IAClD,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAgRD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAwBhB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAiExE"}

package/dist/src/core/session/{handoff-context.js → install-handoff-context.js}

@@ -1,5 +1,9 @@
 /**
- * Handoff Context Generator
+ * Plugin-Install Handoff Context Generator
+ *
+ * NOTE: This is the legacy plugin-INSTALL handoff (renamed from
+ * `handoff-context.ts` in 0867 to free that name for the cross-tool work
+ * handoff). It is unrelated to `work-handoff.ts` / `handoff-doc-format.ts`.
  *
  * Generates context information for session handoff, enabling users
  * to continue their work in a new session after plugin installation.
@@ -11,7 +15,7 @@
  * - Available skills from those plugins
  * - Suggested continuation prompt
  *
- * @module core/session/handoff-context
+ * @module core/session/install-handoff-context
  */
 // ============================================================================
 // Constants - Formatting
@@ -371,4 +375,4 @@ export function formatHandoffText(options) {
     lines.push(HEAVY_SEPARATOR);
     return lines.join('\n');
 }
-//# sourceMappingURL=handoff-context.js.map
+//# sourceMappingURL=install-handoff-context.js.map

package/dist/src/core/session/install-handoff-context.js.map

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

package/dist/src/core/session/work-handoff.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Work Handoff Builder
+ *
+ * Assembles a portable, secret-scrubbed handoff document (+ a full diff of
+ * uncommitted edits) from durable on-disk state, so a developer can stop work
+ * in one AI tool and resume in another. This is the single deterministic engine
+ * behind the `specweave handoff` CLI, the `/sw:handoff` command, and the
+ * PreCompact hook — all of which call {@link buildWorkHandoff}.
+ *
+ * Workspace detection is intentionally NOT a raw `.specweave/` directory test:
+ * a stale child-repo `.specweave/` (no real state) would misclassify. We resolve
+ * the effective root then require an `active-increment.json` that actually
+ * lists increments. Metadata reads are gated with `MetadataManager.exists()`
+ * because `MetadataManager.read()` LAZILY CREATES default metadata — a side
+ * effect a read-only handoff must never trigger.
+ *
+ * All increment/task/AC/workspace logic is REUSED from existing modules (DRY):
+ * `parseTasksWithUSLinks`, `calculateProgressFromTasksFile`,
+ * `ActiveIncrementManager.getActive()`, `MetadataManager`, `resolveEffectiveRoot`.
+ *
+ * Part of increment 0867: Cross-Tool Work Handoff
+ * (AC-US1-03..07, AC-US3-01..05, AC-US4-*, AC-US6-01/02/05).
+ *
+ * @module core/session/work-handoff
+ */
+/**
+ * Options controlling a handoff build. All fields are optional; the agent /
+ * CLI supplies only the short free-text strings + flags.
+ */
+export interface WorkHandoffOptions {
+    /** Required disambiguator when 2+ increments are active. */
+    incrementId?: string;
+    /** "Why I'm handing off" (e.g. "out of tokens"). */
+    reason?: string;
+    /** Where things stand. */
+    summary?: string;
+    /** The exact next step. */
+    next?: string;
+    /** A gotcha / warning for the next agent. */
+    gotcha?: string;
+    /** Agent-supplied decisions; merged OVER plan.md decisions. */
+    decisions?: string[];
+    /** Embed the full body in the paste-prompt (cross-machine). */
+    inline?: boolean;
+    /** Override the doc output path. */
+    out?: string;
+    /** Force the non-SpecWeave `.handoff/` fallback even in a workspace. */
+    nonSpecweave?: boolean;
+}
+/**
+ * Result of a handoff build.
+ */
+export interface WorkHandoffResult {
+    /** Absolute path of the written doc (the CLI prints this FIRST). */
+    docPath: string;
+    /** Absolute path of the sibling full-diff file. */
+    diffPath: string;
+    /** The full rendered + scrubbed doc markdown. */
+    docMarkdown: string;
+    /** The copy-paste resume prompt. */
+    pastePrompt: string;
+    /** Whether the high-fidelity SpecWeave path was taken. */
+    isSpecWeave: boolean;
+}
+/**
+ * Thrown when 2+ increments are active and no explicit id was supplied.
+ * Carries the candidate ids so the CLI can list them.
+ */
+export declare class AmbiguousActiveIncrementError extends Error {
+    readonly candidates: string[];
+    constructor(candidates: string[]);
+}
+/**
+ * Build a handoff for `repoRoot`.
+ *
+ * @param repoRoot - Where to start workspace resolution from (usually cwd).
+ * @param opts - {@link WorkHandoffOptions}.
+ * @returns {@link WorkHandoffResult}.
+ * @throws {AmbiguousActiveIncrementError} when 2+ active increments + no id.
+ */
+export declare function buildWorkHandoff(repoRoot: string, opts?: WorkHandoffOptions): Promise<WorkHandoffResult>;
+/**
+ * Ownership sentinel: is a root `./HANDOFF.md` a foreign file (lacks the
+ * `Doc format v1` marker)? Exposed for the builder + tests. When foreign, the
+ * caller must NOT overwrite it.
+ */
+export declare function isForeignHandoffFile(handoffPath: string): boolean;
+//# sourceMappingURL=work-handoff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"work-handoff.d.ts","sourceRoot":"","sources":["../../../../src/core/session/work-handoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAoBH;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oCAAoC;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;aAC1B,UAAU,EAAE,MAAM,EAAE;gBAApB,UAAU,EAAE,MAAM,EAAE;CAMjD;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAmG5B;AAwOD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAIjE"}

package/dist/src/core/session/work-handoff.js

@@ -0,0 +1,412 @@
+/**
+ * Work Handoff Builder
+ *
+ * Assembles a portable, secret-scrubbed handoff document (+ a full diff of
+ * uncommitted edits) from durable on-disk state, so a developer can stop work
+ * in one AI tool and resume in another. This is the single deterministic engine
+ * behind the `specweave handoff` CLI, the `/sw:handoff` command, and the
+ * PreCompact hook — all of which call {@link buildWorkHandoff}.
+ *
+ * Workspace detection is intentionally NOT a raw `.specweave/` directory test:
+ * a stale child-repo `.specweave/` (no real state) would misclassify. We resolve
+ * the effective root then require an `active-increment.json` that actually
+ * lists increments. Metadata reads are gated with `MetadataManager.exists()`
+ * because `MetadataManager.read()` LAZILY CREATES default metadata — a side
+ * effect a read-only handoff must never trigger.
+ *
+ * All increment/task/AC/workspace logic is REUSED from existing modules (DRY):
+ * `parseTasksWithUSLinks`, `calculateProgressFromTasksFile`,
+ * `ActiveIncrementManager.getActive()`, `MetadataManager`, `resolveEffectiveRoot`.
+ *
+ * Part of increment 0867: Cross-Tool Work Handoff
+ * (AC-US1-03..07, AC-US3-01..05, AC-US4-*, AC-US6-01/02/05).
+ *
+ * @module core/session/work-handoff
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { resolveEffectiveRoot } from '../../utils/find-project-root.js';
+import { ActiveIncrementManager } from '../increment/active-increment-manager.js';
+import { MetadataManager } from '../increment/metadata-manager.js';
+import { parseTasksWithUSLinks } from '../../generators/spec/task-parser.js';
+import { calculateProgressFromTasksFile } from '../../progress/us-progress-tracker.js';
+import { captureGitState } from './handoff-git-state.js';
+import { scrubSecrets } from './handoff-secret-scrub.js';
+import { renderHandoffDoc, renderPastePrompt, DOC_FORMAT_MARKER, } from './handoff-doc-format.js';
+/**
+ * Thrown when 2+ increments are active and no explicit id was supplied.
+ * Carries the candidate ids so the CLI can list them.
+ */
+export class AmbiguousActiveIncrementError extends Error {
+    constructor(candidates) {
+        super(`Multiple active increments — pass an explicit id. Candidates: ${candidates.join(', ')}`);
+        this.candidates = candidates;
+        this.name = 'AmbiguousActiveIncrementError';
+    }
+}
+/**
+ * Build a handoff for `repoRoot`.
+ *
+ * @param repoRoot - Where to start workspace resolution from (usually cwd).
+ * @param opts - {@link WorkHandoffOptions}.
+ * @returns {@link WorkHandoffResult}.
+ * @throws {AmbiguousActiveIncrementError} when 2+ active increments + no id.
+ */
+export async function buildWorkHandoff(repoRoot, opts = {}) {
+    // Resolve the effective workspace root. `resolveEffectiveRoot` returns
+    // process.cwd() as a last resort when the start dir is not inside any
+    // SpecWeave/umbrella tree — which would wrongly anchor a plain repo to the
+    // caller's cwd. So we only ACCEPT the resolved root when it actually carries
+    // SpecWeave state; otherwise we anchor to the passed `repoRoot` itself.
+    const resolved = resolveEffectiveRoot(repoRoot);
+    const resolvedHasState = fs.existsSync(path.join(resolved, '.specweave', 'state', 'active-increment.json'));
+    const passedRoot = path.resolve(repoRoot);
+    const effectiveRoot = !opts.nonSpecweave && resolvedHasState ? resolved : passedRoot;
+    // ── Workspace classification ──────────────────────────────────────────────
+    // SpecWeave only if (a) not forced off and (b) a real active-increment.json
+    // exists at the effective root. A stale .specweave/ with empty/missing
+    // active-increment.json classifies as non-SpecWeave.
+    const hasSpecweaveState = opts.nonSpecweave
+        ? false
+        : fs.existsSync(path.join(effectiveRoot, '.specweave', 'state', 'active-increment.json'));
+    const activeIds = hasSpecweaveState ? readActiveIds(effectiveRoot) : [];
+    // ── Resolve which increment (if any) ──────────────────────────────────────
+    let incrementId;
+    if (hasSpecweaveState && activeIds.length > 0) {
+        if (activeIds.length === 1) {
+            incrementId = activeIds[0];
+        }
+        else {
+            // 2+ active.
+            if (!opts.incrementId)
+                throw new AmbiguousActiveIncrementError(activeIds);
+            incrementId = opts.incrementId;
+        }
+    }
+    // A workspace is "SpecWeave" for doc purposes when it has SpecWeave state.
+    // (0 active still uses the SpecWeave write paths but with a git+config doc.)
+    const isSpecWeave = hasSpecweaveState && !opts.nonSpecweave;
+    // ── Assemble increment facts (gated, no side effects) ─────────────────────
+    let increment;
+    let planDecisions = [];
+    if (incrementId && MetadataManager.exists(incrementId, effectiveRoot)) {
+        const incDir = path.join(effectiveRoot, '.specweave', 'increments', incrementId);
+        increment = await assembleIncrementInfo(incDir, incrementId, effectiveRoot);
+        planDecisions = readPlanDecisions(path.join(incDir, 'plan.md'));
+    }
+    // ── Ambient rules from config.json ────────────────────────────────────────
+    const ambient = isSpecWeave ? readAmbientRules(effectiveRoot) : undefined;
+    // ── Decide write paths (ownership sentinel for non-SpecWeave) ─────────────
+    const { docPath, diffPath } = resolveWritePaths(effectiveRoot, isSpecWeave, incrementId, opts.out);
+    // ── Git state + full diff dump (free, no tokens) ──────────────────────────
+    const git = captureGitState(effectiveRoot, diffPath);
+    // ── Scrub free-text + the captured diff before any write ──────────────────
+    const mergedDecisions = [...planDecisions, ...(opts.decisions ?? [])];
+    const scrubbedText = scrubFields({
+        reason: opts.reason,
+        summary: opts.summary,
+        next: opts.next,
+        gotcha: opts.gotcha,
+        decisions: mergedDecisions,
+    });
+    const redactionCounts = scrubbedText.counts;
+    // Re-scrub the diff file in place (captureGitState wrote the raw diff).
+    scrubDiffFileInPlace(diffPath, redactionCounts);
+    // ── Render ────────────────────────────────────────────────────────────────
+    const docInput = {
+        docPath,
+        diffPath,
+        repoRoot: effectiveRoot,
+        generatedAt: new Date().toISOString(),
+        isSpecWeave,
+        reason: scrubbedText.reason,
+        summary: scrubbedText.summary,
+        next: scrubbedText.next,
+        gotcha: scrubbedText.gotcha,
+        decisions: scrubbedText.decisions,
+        increment,
+        ambient,
+        git,
+        redactionCounts,
+    };
+    const docMarkdown = renderHandoffDoc(docInput);
+    const pastePrompt = renderPastePrompt(docInput, { inline: opts.inline });
+    // ── Write doc(s) ──────────────────────────────────────────────────────────
+    writeDoc(docPath, docMarkdown);
+    // SpecWeave + active increment: also write the stable convenience copy.
+    if (isSpecWeave && incrementId && !opts.out) {
+        const latest = path.join(effectiveRoot, '.specweave', 'state', 'handoff-latest.md');
+        writeDoc(latest, docMarkdown);
+    }
+    return { docPath, diffPath, docMarkdown, pastePrompt, isSpecWeave };
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Internals
+// ───────────────────────────────────────────────────────────────────────────
+/** Read active increment ids straight from the state file (no lazy create). */
+function readActiveIds(effectiveRoot) {
+    try {
+        const mgr = new ActiveIncrementManager(effectiveRoot);
+        return mgr.getActive();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Assemble per-increment facts: status, current/next task, task% and AC counts,
+ * acSyncEvents drift. Reuses the shared parsers; never lazily creates metadata.
+ */
+async function assembleIncrementInfo(incDir, incrementId, effectiveRoot) {
+    // Status comes from the already-existing metadata file (exists()-gated by caller).
+    let status = 'unknown';
+    let acSyncEvents = [];
+    try {
+        const metaRaw = JSON.parse(fs.readFileSync(path.join(incDir, 'metadata.json'), 'utf-8'));
+        if (metaRaw.status)
+            status = metaRaw.status;
+        // acSyncEvents is stored dynamically (not in the typed interface) — read defensively.
+        if (Array.isArray(metaRaw.acSyncEvents)) {
+            acSyncEvents = metaRaw.acSyncEvents.slice(0, 5).map((ev) => {
+                const updated = ev.updated?.length ?? ev.changesCount ?? 0;
+                const conflicts = ev.conflicts?.length ?? 0;
+                return `${ev.timestamp}: ${updated} ACs updated, ${conflicts} conflicts`;
+            });
+        }
+    }
+    catch {
+        // Metadata unreadable — leave defaults.
+    }
+    const title = readSpecTitle(path.join(incDir, 'spec.md'));
+    // Tasks: counts/% via the shared progress fn; current = first non-completed,
+    // next = the one after it (from the same parser's status — fixed in 0867 to
+    // read the canonical one-line `… | **Status**: [x] …` format correctly).
+    const tasksPath = path.join(incDir, 'tasks.md');
+    let currentTask;
+    let nextTask;
+    let doneTasks = 0;
+    let totalTasks = 0;
+    let taskPercentage = 0;
+    if (fs.existsSync(tasksPath)) {
+        const progress = await calculateProgressFromTasksFile(tasksPath);
+        doneTasks = progress.completedTasks;
+        totalTasks = progress.totalTasks;
+        taskPercentage = progress.percentage;
+        const allTasks = Object.values(parseTasksWithUSLinks(tasksPath)).flat();
+        const pending = allTasks
+            .filter((t) => t.status !== 'completed' && t.status !== 'canceled')
+            // parseTasksWithUSLinks groups by user story, so the flattened order is
+            // US-major, not T-id order. Sort by numeric T-id so "current"/"next"
+            // reflect real task sequence even with interleaved per-US numbering.
+            .sort((a, b) => taskIdNum(a.id) - taskIdNum(b.id));
+        if (pending.length > 0)
+            currentTask = `${pending[0].id}: ${pending[0].title}`;
+        if (pending.length > 1)
+            nextTask = `${pending[1].id}: ${pending[1].title}`;
+    }
+    // ACs from spec.md checkboxes.
+    const { doneAcs, totalAcs } = countSpecAcs(path.join(incDir, 'spec.md'));
+    return {
+        id: incrementId,
+        status,
+        title,
+        currentTask,
+        nextTask,
+        doneTasks,
+        totalTasks,
+        taskPercentage,
+        doneAcs,
+        totalAcs,
+        acSyncEvents,
+    };
+}
+/** Numeric portion of a `T-007` / `T-012E` task id, for ordering. */
+function taskIdNum(id) {
+    const m = id.match(/T-(\d+)/);
+    return m ? parseInt(m[1], 10) : Number.MAX_SAFE_INTEGER;
+}
+/** Count `- [ ] AC-...` / `- [x] AC-...` checkboxes in spec.md. */
+function countSpecAcs(specPath) {
+    if (!fs.existsSync(specPath))
+        return { doneAcs: 0, totalAcs: 0 };
+    const acRegex = /^-\s+\[([ x])\]\s+\*{0,2}(AC-[A-Z0-9-]+)\*{0,2}/;
+    let done = 0;
+    let total = 0;
+    for (const line of fs.readFileSync(specPath, 'utf-8').split('\n')) {
+        const m = line.match(acRegex);
+        if (m) {
+            total += 1;
+            if (m[1] === 'x')
+                done += 1;
+        }
+    }
+    return { doneAcs: done, totalAcs: total };
+}
+/** Read the `title:` from spec.md frontmatter, if present. */
+function readSpecTitle(specPath) {
+    if (!fs.existsSync(specPath))
+        return undefined;
+    const content = fs.readFileSync(specPath, 'utf-8');
+    const m = content.match(/^title:\s*["']?(.+?)["']?\s*$/m);
+    return m ? m[1] : undefined;
+}
+/**
+ * Extract decision-ish bullets from plan.md `## Approach`, `## Components`,
+ * `## Risks` sections. Best-effort: each bullet line becomes a decision.
+ */
+function readPlanDecisions(planPath) {
+    if (!fs.existsSync(planPath))
+        return [];
+    const lines = fs.readFileSync(planPath, 'utf-8').split('\n');
+    const wanted = new Set(['approach', 'risks', 'key decisions', 'decisions']);
+    const decisions = [];
+    let capture = false;
+    for (const line of lines) {
+        const heading = line.match(/^##\s+(.+?)\s*$/);
+        if (heading) {
+            capture = wanted.has(heading[1].trim().toLowerCase());
+            continue;
+        }
+        if (capture) {
+            const bullet = line.match(/^[-*]\s+(.+)/);
+            if (bullet)
+                decisions.push(bullet[1].trim());
+        }
+    }
+    return decisions.slice(0, 10);
+}
+/** Read ambient rules (test mode / coverage target / WIP limit) from config.json. */
+function readAmbientRules(effectiveRoot) {
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(effectiveRoot, '.specweave', 'config.json'), 'utf-8'));
+        return {
+            testMode: cfg.testing?.defaultTestMode,
+            coverageTarget: cfg.testing?.defaultCoverageTarget,
+            wipLimit: cfg.limits?.maxActiveIncrements,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Decide doc + diff paths.
+ *
+ * - explicit `out`: use it (diff is a sibling `.diff`).
+ * - SpecWeave + active increment: `reports/handoff.md` (the stable copy is
+ *   written separately by the caller).
+ * - SpecWeave, no active increment: `state/handoff-latest.md`.
+ * - non-SpecWeave: `.handoff/HANDOFF.md`, unless a foreign root `./HANDOFF.md`
+ *   without the marker exists (ownership sentinel still routes to `.handoff/`).
+ */
+function resolveWritePaths(effectiveRoot, isSpecWeave, incrementId, out) {
+    if (out) {
+        const abs = path.isAbsolute(out) ? out : path.join(effectiveRoot, out);
+        return { docPath: abs, diffPath: siblingDiff(abs) };
+    }
+    if (isSpecWeave && incrementId) {
+        const docPath = path.join(effectiveRoot, '.specweave', 'increments', incrementId, 'reports', 'handoff.md');
+        const diffPath = path.join(effectiveRoot, '.specweave', 'state', 'handoff-latest.diff');
+        return { docPath, diffPath };
+    }
+    if (isSpecWeave) {
+        const docPath = path.join(effectiveRoot, '.specweave', 'state', 'handoff-latest.md');
+        const diffPath = path.join(effectiveRoot, '.specweave', 'state', 'handoff-latest.diff');
+        return { docPath, diffPath };
+    }
+    // Non-SpecWeave. Default target is the repo-root ./HANDOFF.md, but only if it
+    // is OURS: a root ./HANDOFF.md that already carries the Doc format v1 marker
+    // is a prior handoff we may overwrite in-place. A root ./HANDOFF.md WITHOUT
+    // the marker is a foreign file (a project's own HANDOFF) — the ownership
+    // sentinel refuses to clobber it and routes to .handoff/ instead.
+    const rootHandoff = path.join(effectiveRoot, 'HANDOFF.md');
+    if (fs.existsSync(rootHandoff) && !isForeignHandoffFile(rootHandoff)) {
+        return { docPath: rootHandoff, diffPath: siblingDiff(rootHandoff) };
+    }
+    // No (safe) root file → write under .handoff/ (also the foreign-file case).
+    ensureHandoffDir(effectiveRoot);
+    const docPath = path.join(effectiveRoot, '.handoff', 'HANDOFF.md');
+    const diffPath = path.join(effectiveRoot, '.handoff', 'handoff.diff');
+    return { docPath, diffPath };
+}
+/** Sibling `<name>.diff` for an arbitrary doc path. */
+function siblingDiff(docPath) {
+    const ext = path.extname(docPath);
+    return docPath.slice(0, docPath.length - ext.length) + '.diff';
+}
+/**
+ * Create `.handoff/` + a `.gitignore` containing `*` so the doc, diff, and any
+ * scrubbed-but-still-sensitive content never enter git by default.
+ */
+function ensureHandoffDir(effectiveRoot) {
+    const dir = path.join(effectiveRoot, '.handoff');
+    fs.mkdirSync(dir, { recursive: true });
+    const gi = path.join(dir, '.gitignore');
+    if (!fs.existsSync(gi))
+        fs.writeFileSync(gi, '*\n', 'utf-8');
+}
+/**
+ * Ownership sentinel: is a root `./HANDOFF.md` a foreign file (lacks the
+ * `Doc format v1` marker)? Exposed for the builder + tests. When foreign, the
+ * caller must NOT overwrite it.
+ */
+export function isForeignHandoffFile(handoffPath) {
+    if (!fs.existsSync(handoffPath))
+        return false;
+    const content = fs.readFileSync(handoffPath, 'utf-8');
+    return !content.includes(DOC_FORMAT_MARKER);
+}
+/** Write a doc, creating parent dirs. */
+function writeDoc(docPath, markdown) {
+    fs.mkdirSync(path.dirname(docPath), { recursive: true });
+    fs.writeFileSync(docPath, markdown, 'utf-8');
+}
+/** Scrub the free-text fields, accumulating per-pattern counts. */
+function scrubFields(fields) {
+    const counts = {};
+    const add = (c) => {
+        for (const [k, v] of Object.entries(c))
+            counts[k] = (counts[k] ?? 0) + v;
+    };
+    const one = (s) => {
+        if (s == null)
+            return s;
+        const r = scrubSecrets(s);
+        add(r.counts);
+        return r.scrubbed;
+    };
+    const decisions = fields.decisions.map((d) => {
+        const r = scrubSecrets(d);
+        add(r.counts);
+        return r.scrubbed;
+    });
+    return {
+        reason: one(fields.reason),
+        summary: one(fields.summary),
+        next: one(fields.next),
+        gotcha: one(fields.gotcha),
+        decisions,
+        counts,
+    };
+}
+/**
+ * Re-read the raw diff file captureGitState wrote, scrub it, write it back, and
+ * fold its redaction counts into the running totals.
+ */
+function scrubDiffFileInPlace(diffPath, counts) {
+    try {
+        if (!fs.existsSync(diffPath))
+            return;
+        const raw = fs.readFileSync(diffPath, 'utf-8');
+        if (!raw)
+            return;
+        const { scrubbed, counts: diffCounts } = scrubSecrets(raw);
+        fs.writeFileSync(diffPath, scrubbed, 'utf-8');
+        for (const [k, v] of Object.entries(diffCounts))
+            counts[k] = (counts[k] ?? 0) + v;
+    }
+    catch {
+        // Best-effort.
+    }
+}
+//# sourceMappingURL=work-handoff.js.map