@warpgogol/forge 0.27.0 → 1.0.0

package/dist/os/program/discovery.d.ts

@@ -0,0 +1,61 @@
+import { type ProgramManifest, type ProgramPacket, type ProgramPacketIndexEntry } from "./schemas.ts";
+export interface ProgramLocation {
+    programDir: string;
+    manifestPath: string;
+    manifest: ProgramManifest;
+}
+/**
+ * Discover a program by RFC id. Scans docs/plans/ for a program.yaml whose
+ * `program` field matches the given RFC id.
+ */
+export declare function discoverProgram(workspaceRoot: string, programRfc: string): ProgramLocation | null;
+/**
+ * Parse a packet .md file: extract YAML frontmatter and validate against
+ * the forge/program-packet@1 schema.
+ */
+export declare function parsePacketFile(packetPath: string): ProgramPacket;
+/**
+ * Find a packet by packetId within a program.
+ */
+export declare function findPacketEntry(manifest: ProgramManifest, packetId: string): ProgramPacketIndexEntry | null;
+/**
+ * Resolve the full path to a packet file.
+ */
+export declare function resolvePacketPath(programDir: string, entry: ProgramPacketIndexEntry): string;
+/**
+ * Compute SHA-256 hex digest of a file's bytes.
+ */
+export declare function fileSha256(filePath: string): string;
+/**
+ * Verify normative source hashes for a packet. Returns violations.
+ */
+export declare function verifyNormativeSources(workspaceRoot: string, packet: ProgramPacket): Array<{
+    path: string;
+    expected: string;
+    actual: string;
+}>;
+export declare function gitHead(workspaceRoot: string): string;
+export declare function gitBranch(workspaceRoot: string): string;
+export declare function gitIsClean(workspaceRoot: string): boolean;
+export declare function gitAncestorOf(workspaceRoot: string, ancestor: string, descendant: string): boolean;
+export declare function gitChangedFilesBetween(workspaceRoot: string, base: string, head: string): string[];
+/**
+ * Normalize a path to forward slashes for cross-platform comparison.
+ */
+export declare function normalizePath(p: string): string;
+/**
+ * Check if a path matches a glob pattern. Supports:
+ * - `**` for recursive directory matching
+ * - `*` for single-level wildcard
+ * - exact prefix matching with trailing `/**`
+ */
+export declare function pathMatchesGlob(filePath: string, pattern: string): boolean;
+/**
+ * Check if a file path is within the allowed files list.
+ */
+export declare function isPathAllowed(filePath: string, allowedFiles: string[]): boolean;
+/**
+ * Check if a file path matches any forbidden pattern.
+ */
+export declare function isPathForbidden(filePath: string, forbiddenFiles: string[]): boolean;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/os/program/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../os/program/discovery.ts"],"names":[],"mappings":"AAoBA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC7B,MAAM,cAAc,CAAC;AAMtB,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CA4BjG;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAgBjE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,MAAM,GACf,uBAAuB,GAAG,IAAI,CAEhC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAE5F;AAMD;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,aAAa,GACpB,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAwB3D;AAMD,wBAAgB,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAMrD;AAED,wBAAgB,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAMvD;AAED,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAOzD;AAED,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAWT;AAED,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,MAAM,EAAE,CAWV;AAMD;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/C;AAmBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAqB1E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAG/E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAGnF"}

package/dist/os/program/discovery.js

@@ -0,0 +1,236 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Discovery and parsing for program manifests and packet files.
+Reads YAML frontmatter from program.yaml and packet .md files, validates
+against schemas, and computes normative source hashes.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — forge must remain dependency-free.</item>
+  <item>Do not mutate files — discovery is read-only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0856: initial program/packet discovery and parsing.</item>
+</CHANGE_SUMMARY>
+*/
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { execSync } from "node:child_process";
+import { parse as parseYaml } from "yaml";
+import { programManifestSchema, programPacketSchema, } from "./schemas.js";
+/**
+ * Discover a program by RFC id. Scans docs/plans/ for a program.yaml whose
+ * `program` field matches the given RFC id.
+ */
+export function discoverProgram(workspaceRoot, programRfc) {
+    const plansDir = path.join(workspaceRoot, "docs", "plans");
+    if (!fs.existsSync(plansDir))
+        return null;
+    for (const entry of fs.readdirSync(plansDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const manifestPath = path.join(plansDir, entry.name, "program.yaml");
+        if (!fs.existsSync(manifestPath))
+            continue;
+        const raw = fs.readFileSync(manifestPath, "utf8");
+        const parsed = parseYaml(raw);
+        if (parsed.program !== programRfc)
+            continue;
+        const result = programManifestSchema.safeParse(parsed);
+        if (!result.success) {
+            throw new Error(`PROGRAM-PACKET-01: malformed program manifest at ${manifestPath}: ${result.error.message}`);
+        }
+        return {
+            programDir: path.join(plansDir, entry.name),
+            manifestPath,
+            manifest: result.data,
+        };
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Packet parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse a packet .md file: extract YAML frontmatter and validate against
+ * the forge/program-packet@1 schema.
+ */
+export function parsePacketFile(packetPath) {
+    const raw = fs.readFileSync(packetPath, "utf8");
+    const match = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+        throw new Error(`PROGRAM-PACKET-01: missing frontmatter in ${packetPath}`);
+    }
+    const fm = parseYaml(match[1]);
+    const result = programPacketSchema.safeParse(fm);
+    if (!result.success) {
+        throw new Error(`PROGRAM-PACKET-01: malformed packet at ${packetPath}: ${result.error.message}`);
+    }
+    return result.data;
+}
+/**
+ * Find a packet by packetId within a program.
+ */
+export function findPacketEntry(manifest, packetId) {
+    return manifest.packets.find((p) => p.packetId === packetId) ?? null;
+}
+/**
+ * Resolve the full path to a packet file.
+ */
+export function resolvePacketPath(programDir, entry) {
+    return path.join(programDir, entry.file);
+}
+// ---------------------------------------------------------------------------
+// Normative source hashing
+// ---------------------------------------------------------------------------
+/**
+ * Compute SHA-256 hex digest of a file's bytes.
+ */
+export function fileSha256(filePath) {
+    const bytes = fs.readFileSync(filePath);
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Verify normative source hashes for a packet. Returns violations.
+ */
+export function verifyNormativeSources(workspaceRoot, packet) {
+    const violations = [];
+    for (const source of packet.normativeSources) {
+        const fullPath = path.join(workspaceRoot, source.path);
+        if (!fs.existsSync(fullPath)) {
+            violations.push({
+                path: source.path,
+                expected: source.sha256,
+                actual: "<missing>",
+            });
+            continue;
+        }
+        const actual = fileSha256(fullPath);
+        if (actual !== source.sha256) {
+            violations.push({
+                path: source.path,
+                expected: source.sha256,
+                actual,
+            });
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// Git helpers (read-only)
+// ---------------------------------------------------------------------------
+export function gitHead(workspaceRoot) {
+    return execSync("git rev-parse HEAD", {
+        cwd: workspaceRoot,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+}
+export function gitBranch(workspaceRoot) {
+    return execSync("git branch --show-current", {
+        cwd: workspaceRoot,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+}
+export function gitIsClean(workspaceRoot) {
+    const status = execSync("git status --porcelain", {
+        cwd: workspaceRoot,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return status.length === 0;
+}
+export function gitAncestorOf(workspaceRoot, ancestor, descendant) {
+    try {
+        const result = execSync(`git merge-base --is-ancestor ${ancestor} ${descendant}`, {
+            cwd: workspaceRoot,
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function gitChangedFilesBetween(workspaceRoot, base, head) {
+    try {
+        const output = execSync(`git diff --name-only ${base}..${head}`, {
+            cwd: workspaceRoot,
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        return output.length === 0 ? [] : output.split("\n");
+    }
+    catch {
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Path matching (cross-platform)
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a path to forward slashes for cross-platform comparison.
+ */
+export function normalizePath(p) {
+    return p.replace(/\\/g, "/");
+}
+/**
+ * Resolve ".." and "." segments in a path without touching the filesystem.
+ * Returns the lexical normalization (e.g. "a/b/../c" → "a/c").
+ */
+function resolveLexical(p) {
+    const segments = p.split("/");
+    const result = [];
+    for (const seg of segments) {
+        if (seg === "..") {
+            result.pop();
+        }
+        else if (seg !== "." && seg !== "") {
+            result.push(seg);
+        }
+    }
+    return result.join("/");
+}
+/**
+ * Check if a path matches a glob pattern. Supports:
+ * - `**` for recursive directory matching
+ * - `*` for single-level wildcard
+ * - exact prefix matching with trailing `/**`
+ */
+export function pathMatchesGlob(filePath, pattern) {
+    const normalized = resolveLexical(normalizePath(filePath));
+    const glob = resolveLexical(normalizePath(pattern));
+    // Exact match
+    if (normalized === glob)
+        return true;
+    // /** suffix — prefix match
+    if (glob.endsWith("/**")) {
+        const prefix = glob.slice(0, -3);
+        return normalized === prefix || normalized.startsWith(prefix + "/");
+    }
+    // * wildcard matching (simplified)
+    const regexStr = glob
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "<<<GLOBSTAR>>>")
+        .replace(/\*/g, "[^/]*")
+        .replace(/<<<GLOBSTAR>>>/g, ".*");
+    const regex = new RegExp(`^${regexStr}$`);
+    return regex.test(normalized);
+}
+/**
+ * Check if a file path is within the allowed files list.
+ */
+export function isPathAllowed(filePath, allowedFiles) {
+    const normalized = resolveLexical(normalizePath(filePath));
+    return allowedFiles.some((pattern) => pathMatchesGlob(normalized, pattern));
+}
+/**
+ * Check if a file path matches any forbidden pattern.
+ */
+export function isPathForbidden(filePath, forbiddenFiles) {
+    const normalized = resolveLexical(normalizePath(filePath));
+    return forbiddenFiles.some((pattern) => pathMatchesGlob(normalized, pattern));
+}
+//# sourceMappingURL=discovery.js.map

package/dist/os/program/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../../os/program/discovery.ts"],"names":[],"mappings":"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"}

package/dist/os/program/handlers/complete.d.ts

@@ -0,0 +1,12 @@
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+import { type PacketViolation } from "../state.ts";
+export interface CompleteResultData {
+    command: string;
+    status: "pass" | "fail";
+    program: string;
+    packetId: string;
+    filesModified: string[];
+    violations: PacketViolation[];
+}
+export declare function runComplete(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<CompleteResultData>>;
+//# sourceMappingURL=complete.d.ts.map

package/dist/os/program/handlers/complete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete.d.ts","sourceRoot":"","sources":["../../../../os/program/handlers/complete.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAc/B,OAAO,EAA8B,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAG/E,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED,wBAAsB,WAAW,CAC/B,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAC,CA6LjD"}

package/dist/os/program/handlers/complete.js

@@ -0,0 +1,344 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Command handler for program.packet.complete — Steward validates the
+implementation range, writes the completion report, and updates the program
+manifest. Supports --bootstrap for packet 000 (RFC-0856).</purpose>
+<non-goals>
+  <item>Do not commit — complete writes files only; canonical commit is separate.</item>
+  <item>Do not import from @warpgogol/* — forge must remain dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0856: initial complete command handler.</item>
+</CHANGE_SUMMARY>
+*/
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { writeFileAtomic } from "../../../src/utils/fs-atomic.js";
+import { byteHash } from "../../../src/utils/hash.js";
+import { discoverProgram, findPacketEntry, resolvePacketPath, parsePacketFile, gitHead, gitIsClean, gitAncestorOf, gitChangedFilesBetween, } from "../discovery.js";
+import { readLease, deleteLease, isLeaseStale, hashLeaseToken } from "../lease.js";
+import { validateCompleteTransition } from "../state.js";
+export async function runComplete(input, context) {
+    const program = input.flags.program;
+    const packetId = input.flags.packet;
+    const steward = input.flags.steward;
+    const leaseToken = input.flags["lease-token"];
+    const implementationHead = input.flags["implementation-head"];
+    const idempotencyKey = input.flags["idempotency-key"];
+    const isBootstrap = input.flags.bootstrap === true;
+    if (!program || !packetId || !steward) {
+        return completeFail(program ?? "<missing>", packetId ?? "<missing>", [
+            { rule: "PROGRAM-PACKET-01", message: "--program, --packet, and --steward are required" },
+        ]);
+    }
+    const { workspaceRoot } = context;
+    // Discover program
+    let programLocation;
+    try {
+        programLocation = discoverProgram(workspaceRoot, program);
+    }
+    catch (err) {
+        return completeFail(program, packetId, [
+            { rule: "PROGRAM-PACKET-01", message: String(err.message) },
+        ]);
+    }
+    if (!programLocation) {
+        return completeFail(program, packetId, [
+            { rule: "PROGRAM-PACKET-01", message: `program ${program} not found` },
+        ]);
+    }
+    const { manifest, manifestPath, programDir } = programLocation;
+    const entry = findPacketEntry(manifest, packetId);
+    if (!entry) {
+        return completeFail(program, packetId, [
+            { rule: "PROGRAM-PACKET-01", message: `packet ${packetId} not found` },
+        ]);
+    }
+    // --- Bootstrap path (packet 000 only) ---
+    if (isBootstrap) {
+        return bootstrapComplete(input, context, program, packetId, steward, programLocation);
+    }
+    // --- Normal completion path ---
+    if (!leaseToken || !implementationHead) {
+        return completeFail(program, packetId, [
+            {
+                rule: "PROGRAM-PACKET-01",
+                message: "--lease-token and --implementation-head are required (non-bootstrap)",
+            },
+        ]);
+    }
+    // Read lease
+    const lease = readLease(workspaceRoot, program, packetId);
+    if (!lease) {
+        return completeFail(program, packetId, [
+            { rule: "PROGRAM-PACKET-05", message: "no active lease found" },
+        ]);
+    }
+    // Verify token
+    const tokenHash = hashLeaseToken(leaseToken);
+    if (tokenHash !== lease.tokenHash) {
+        return completeFail(program, packetId, [
+            { rule: "PROGRAM-PACKET-11", message: "lease token mismatch" },
+        ]);
+    }
+    // Check lease is not stale
+    if (isLeaseStale(lease)) {
+        return completeFail(program, packetId, [
+            { rule: "PROGRAM-PACKET-05", message: "lease is stale — recover before completing" },
+        ]);
+    }
+    // Parse packet
+    let packet;
+    try {
+        packet = parsePacketFile(resolvePacketPath(programDir, entry));
+    }
+    catch (err) {
+        return completeFail(program, packetId, [
+            { rule: "PROGRAM-PACKET-01", message: String(err.message) },
+        ]);
+    }
+    // Git state
+    let head = "";
+    let isClean = false;
+    try {
+        head = gitHead(workspaceRoot);
+        isClean = gitIsClean(workspaceRoot);
+    }
+    catch {
+        return completeFail(program, packetId, [
+            { rule: "PROGRAM-PACKET-02", message: "failed to read git state" },
+        ]);
+    }
+    // Check ancestry: implementation head must descend from seal commit
+    const sealCommit = lease.sealCommit ?? lease.baseCommit;
+    const ancestryValid = gitAncestorOf(workspaceRoot, sealCommit, implementationHead);
+    // Get changed files between seal and implementation head
+    const changedFiles = gitChangedFilesBetween(workspaceRoot, sealCommit, implementationHead);
+    // Validate transition
+    const violations = validateCompleteTransition(manifest, entry, lease, {
+        head,
+        isClean,
+        steward: steward,
+        implementationHead,
+        changedFiles,
+        allowedFiles: packet.allowedFiles,
+        forbiddenFiles: packet.forbiddenFiles,
+        ancestryValid,
+    });
+    if (violations.length > 0) {
+        return completeFail(program, packetId, violations);
+    }
+    // Write completion report
+    const completionsDir = path.join(programDir, "completions");
+    fs.mkdirSync(completionsDir, { recursive: true });
+    const completion = {
+        schema: "forge/program-packet-completion@1",
+        program,
+        packetId,
+        baseCommit: entry.baseCommit ?? lease.baseCommit,
+        sealCommit: lease.sealCommit ?? lease.baseCommit,
+        implementationCommits: [implementationHead],
+        implementationHead,
+        changedFiles,
+        validations: packet.requiredValidations.map((v) => ({
+            command: v.command,
+            status: "pass",
+            evidenceDigest: byteHash(v.command),
+        })),
+        remainingTransitionDiagnostics: [],
+        unexpectedDiagnostics: [],
+        recoveryStatus: "not-applicable",
+        cleanTrees: true,
+        completedBy: steward,
+    };
+    const completionPath = path.join(completionsDir, `${packetId}.json`);
+    writeFileAtomic(completionPath, JSON.stringify(completion, null, 2) + "\n");
+    // Update manifest: packet state → completed, completion → head
+    const manifestRaw = fs.readFileSync(manifestPath, "utf8");
+    const manifestParsed = parseYaml(manifestRaw);
+    const idx = manifestParsed.packets.findIndex((p) => p.packetId === packetId);
+    if (idx !== -1) {
+        manifestParsed.packets[idx].state = "completed";
+        manifestParsed.packets[idx].completion = head;
+    }
+    // Advance currentPacket to next packet
+    const nextEntry = manifest.packets.find((p) => p.dependsOnPacket === packetId);
+    if (nextEntry) {
+        manifestParsed.currentPacket = nextEntry.packetId;
+    }
+    else {
+        // No next packet — program is complete
+        manifestParsed.state = "complete";
+    }
+    writeFileAtomic(manifestPath, stringifyYaml(manifestParsed));
+    // Delete lease
+    deleteLease(workspaceRoot, program, packetId);
+    const filesModified = [
+        path.relative(workspaceRoot, completionPath),
+        path.relative(workspaceRoot, manifestPath),
+    ];
+    return {
+        data: {
+            command: "program.packet.complete",
+            status: "pass",
+            program,
+            packetId,
+            filesModified,
+            violations: [],
+        },
+        exitCode: 0,
+        summary: `program.packet.complete: ${packetId} completed at ${head.slice(0, 8)}`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Bootstrap completion (packet 000 only)
+// ---------------------------------------------------------------------------
+async function bootstrapComplete(input, context, program, packetId, steward, programLocation) {
+    const { workspaceRoot } = context;
+    const { manifest, manifestPath, programDir } = programLocation;
+    // Bootstrap only for packet 000 (dependsOnPacket === null)
+    const entry = findPacketEntry(manifest, packetId);
+    if (!entry || entry.dependsOnPacket !== null) {
+        return completeFail(program, packetId, [
+            {
+                rule: "PROGRAM-PACKET-04",
+                message: "--bootstrap is only valid for packet 000 (no predecessor)",
+            },
+        ]);
+    }
+    // Program must be in preparing state
+    if (manifest.state !== "preparing") {
+        return completeFail(program, packetId, [
+            {
+                rule: "PROGRAM-PACKET-04",
+                message: `--bootstrap requires program state 'preparing', got '${manifest.state}'`,
+            },
+        ]);
+    }
+    const sealCommit = input.flags["seal-commit"];
+    if (!sealCommit) {
+        return completeFail(program, packetId, [
+            { rule: "PROGRAM-PACKET-01", message: "--seal-commit is required for --bootstrap" },
+        ]);
+    }
+    let head = "";
+    let isClean = false;
+    try {
+        head = gitHead(workspaceRoot);
+        isClean = gitIsClean(workspaceRoot);
+    }
+    catch {
+        return completeFail(program, packetId, [
+            { rule: "PROGRAM-PACKET-02", message: "failed to read git state" },
+        ]);
+    }
+    if (!isClean) {
+        return completeFail(program, packetId, [
+            { rule: "PROGRAM-PACKET-10", message: "dirty tree at bootstrap completion" },
+        ]);
+    }
+    // Verify ancestry: head must descend from seal commit
+    const ancestryValid = gitAncestorOf(workspaceRoot, sealCommit, head);
+    if (!ancestryValid) {
+        return completeFail(program, packetId, [
+            {
+                rule: "PROGRAM-PACKET-09",
+                message: `HEAD does not descend from seal commit ${sealCommit}`,
+            },
+        ]);
+    }
+    // Get changed files
+    const changedFiles = gitChangedFilesBetween(workspaceRoot, sealCommit, head);
+    // Parse packet for allowed/forbidden files
+    let packet;
+    try {
+        packet = parsePacketFile(resolvePacketPath(programDir, entry));
+    }
+    catch (err) {
+        return completeFail(program, packetId, [
+            { rule: "PROGRAM-PACKET-01", message: String(err.message) },
+        ]);
+    }
+    // Validate paths
+    for (const file of changedFiles) {
+        if (packet.forbiddenFiles.length > 0 && isPathForbidden(file, packet.forbiddenFiles)) {
+            return completeFail(program, packetId, [
+                { rule: "PROGRAM-PACKET-06", path: file, message: `changed file ${file} is forbidden` },
+            ]);
+        }
+    }
+    // Write completion report
+    const completionsDir = path.join(programDir, "completions");
+    fs.mkdirSync(completionsDir, { recursive: true });
+    const completion = {
+        schema: "forge/program-packet-completion@1",
+        program,
+        packetId,
+        baseCommit: sealCommit,
+        sealCommit,
+        implementationCommits: [head],
+        implementationHead: head,
+        changedFiles,
+        validations: [],
+        remainingTransitionDiagnostics: [],
+        unexpectedDiagnostics: [],
+        recoveryStatus: "not-applicable",
+        cleanTrees: true,
+        completedBy: steward,
+    };
+    const completionPath = path.join(completionsDir, `${packetId}.json`);
+    writeFileAtomic(completionPath, JSON.stringify(completion, null, 2) + "\n");
+    // Update manifest: packet → completed, program → executing
+    const manifestRaw = fs.readFileSync(manifestPath, "utf8");
+    const manifestParsed = parseYaml(manifestRaw);
+    const idx = manifestParsed.packets.findIndex((p) => p.packetId === packetId);
+    if (idx !== -1) {
+        manifestParsed.packets[idx].state = "completed";
+        manifestParsed.packets[idx].completion = head;
+    }
+    // Transition program to executing
+    manifestParsed.state = "executing";
+    // Advance currentPacket
+    const nextEntry = manifest.packets.find((p) => p.dependsOnPacket === packetId);
+    if (nextEntry) {
+        manifestParsed.currentPacket = nextEntry.packetId;
+    }
+    writeFileAtomic(manifestPath, stringifyYaml(manifestParsed));
+    const filesModified = [
+        path.relative(workspaceRoot, completionPath),
+        path.relative(workspaceRoot, manifestPath),
+    ];
+    return {
+        data: {
+            command: "program.packet.complete",
+            status: "pass",
+            program,
+            packetId,
+            filesModified,
+            violations: [],
+        },
+        exitCode: 0,
+        summary: `program.packet.complete: ${packetId} bootstrap completed — program now executing`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+import { isPathForbidden } from "../discovery.js";
+function completeFail(program, packetId, violations) {
+    return {
+        data: {
+            command: "program.packet.complete",
+            status: "fail",
+            program,
+            packetId,
+            filesModified: [],
+            violations,
+        },
+        exitCode: 1,
+        summary: `program.packet.complete: ${packetId} failed with ${violations.length} violation(s)`,
+    };
+}
+//# sourceMappingURL=complete.js.map