@zq-silk/yui 0.11.1 → 0.11.3

package/README.md

@@ -294,6 +294,49 @@ files as dirty, preserves ignored files, and refuses missing remotes or refs and
 When the configured branch is `HEAD`, refresh resolves the remote's symbolic default branch for that
 operation and requires the checkout to be on that branch; detached or mismatched checkouts fail.
 
+### Project lifecycle
+
+Divergence and end-of-life are explicit, Operator-authority operations with fail-closed gates.
+Every destructive command refuses a managed Task Session (run it from an Operator or user
+terminal), an active Task binding, a dirty checkout, and an unreachable or unverified remote.
+
+```sh
+yui project diagnose app
+yui project reset app
+yui project reset app --discard-local
+yui project replace app --discard-local
+yui project retire app --reason "superseded by app-ng"
+yui project delete app --confirm app
+yui project delete app --checkout --confirm app
+```
+
+`project reset` handles the divergence `project refresh` refuses. Without `--discard-local` it is
+a dry run: it fetches and verifies the remote baseline, and when the checkout has diverged it
+refuses while listing the exact local commits that would be discarded. With `--discard-local` it
+hard-resets the clean checkout to the verified remote commit (a plain fast-forward when the
+checkout is merely behind). `project replace` goes further for Home-managed checkouts: it clones
+the remote into a staging directory, verifies both branches, copies the Yui-local refs
+(`refs/heads/yui/`, `refs/yui/archive/`) so historical evidence keeps resolving, then swaps the
+checkout on disk while the catalog record keeps its path. Replace refuses linked worktrees (Task
+or Integration workspaces) and dirty checkouts, and requires `--discard-local`. The swap is
+recoverable: the previous checkout is parked at a backup path and restored on any failure, a
+catalog refusal rolls the swap back, and a crash mid-swap is healed on the next run (a crash
+before the swap leaves only a removable staging clone).
+
+`project retire` is the auditable soft deprecation: it records who retired the Project, when, and
+why, while retaining the catalog record, checkout, and every historical
+Task/Run/Review/Integration/Publication reference. A retired Project cannot be refreshed,
+updated, migrated, reset, replaced, maintained through Knowledge writes (add/retire/propose/
+accept/reject), or bound to new Tasks, WorkItems, or Integrations; Knowledge reads (`list`,
+`show`, `proposals list/show`) stay open so the evidence stays auditable.
+`project delete` is the separate hard-removal decision: it requires a retired Project, an exact
+`--confirm <project-id>` acknowledgment, and fails closed while any Task record references the
+Project. `--checkout` additionally removes the Home-managed checkout (external checkouts are
+user-owned and must be removed manually): it first refuses linked worktrees and dirty checkouts,
+then moves the checkout to a tombstone before removing the catalog record, restoring it on any
+failure so the catalog and checkout never disagree unrecoverably. `project show` and
+`project list` display the lifecycle status and retirement record.
+
 Use `task context` as the first detailed read of an existing Task. It combines the Task, Brief, active Decisions, recent Milestones, Roles, current and recent WorkItems with their Runs, recent Messages, open and resolved InputRequests, and recent Events. Terminal output keeps histories and long text compact; `yui --json task context <task-id>` returns the complete records in the top-level `data` field.
 
 Leader wakeups stay deliberately small: the wake envelope carries only the
@@ -1011,6 +1054,7 @@ yui config completion [bash|zsh|fish]
 yui session enter|record|replace|reconcile
 yui session stop --all
 yui project add|clone|refresh|update|discover|list|show|knowledge
+yui project reset|replace|retire|delete
 ```
 
 `yui update` stages the newly published package **side by side** — it never

package/dist/cli/commandCatalog.js

@@ -1260,7 +1260,10 @@ export const ROOT_COMMAND = buildNode({
         {
             name: "project",
             summary: "Manage Projects, stable checkouts, branches, and Yui knowledge.",
-            sections: [{ id: "manage", title: "Commands", entries: ["add", "clone", "refresh", "diagnose", "migrate", "update", "discover", "list", "show", "knowledge"] }],
+            sections: [
+                { id: "manage", title: "Commands", entries: ["add", "clone", "refresh", "diagnose", "migrate", "update", "discover", "list", "show", "knowledge"] },
+                { id: "lifecycle", title: "Lifecycle (Operator authority)", entries: ["reset", "replace", "retire", "delete"] }
+            ],
             children: [
                 {
                     name: "add",
@@ -1291,6 +1294,30 @@ export const ROOT_COMMAND = buildNode({
                     usage: "yui project migrate <project> [--preflight]",
                     options: ["--preflight"]
                 },
+                {
+                    name: "reset",
+                    summary: "Hard-reset a canonical checkout to its verified remote baseline (Operator authority).",
+                    usage: "yui project reset <project> [--discard-local]",
+                    options: ["--discard-local"]
+                },
+                {
+                    name: "replace",
+                    summary: "Re-clone a Home-managed checkout from its remote, preserving Yui refs (Operator authority).",
+                    usage: "yui project replace <project> --discard-local",
+                    options: ["--discard-local"]
+                },
+                {
+                    name: "retire",
+                    summary: "Soft-deprecate a Project; record and evidence are retained (Operator authority).",
+                    usage: "yui project retire <project> --reason <text>",
+                    options: ["--reason"]
+                },
+                {
+                    name: "delete",
+                    summary: "Remove a retired Project's catalog record and optionally its checkout (Operator authority).",
+                    usage: "yui project delete <project> [--checkout] --confirm <project-id>",
+                    options: ["--checkout", "--confirm"]
+                },
                 {
                     name: "update",
                     summary: "Update a bound Project's aliases, remote, or branch refs.",

package/dist/commands/projectCommands.js

@@ -1,11 +1,12 @@
 import { existsSync } from "node:fs";
-import { readdir, rm } from "node:fs/promises";
+import { readdir, rename, rm } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { usageError } from "../errors/cliError.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
+import { healCheckoutSwap, restoreCheckoutSwap, swapManagedCheckout } from "../repository/checkoutSwap.js";
 import { NodeGitWorkspace } from "../repository/gitWorkspace.js";
 import { acquireProjectMaintenanceLock } from "../repository/projectMaintenanceLock.js";
-import { addProjectKnowledge, addKnowledgeProposal, decideKnowledgeProposal, createProject, findKnowledgeProposal, findKnowledgeProposalByFingerprint, knowledgeEvidenceDigest, knowledgeProposalFingerprint, managedProjectPath, planKnowledgeAcceptance, retireProjectKnowledge, resolveProject, updateProjectKnowledge, updateProjectMetadata, validateProject, validateProjectName } from "../repository/project.js";
+import { addProjectKnowledge, addKnowledgeProposal, assertProjectActive, decideKnowledgeProposal, createProject, findKnowledgeProposal, findKnowledgeProposalByFingerprint, knowledgeEvidenceDigest, knowledgeProposalFingerprint, managedProjectPath, planKnowledgeAcceptance, retireProject, retireProjectKnowledge, resolveProject, updateProjectKnowledge, updateProjectMetadata, validateProject, validateProjectName } from "../repository/project.js";
 import { projectActor } from "./taskActor.js";
 export async function runProjectCommand(args, store, options = {}) {
     const [command, ...rest] = args;
@@ -46,6 +47,18 @@ export async function runProjectCommand(args, store, options = {}) {
             data: { project }
         };
     }
+    if (command === "reset") {
+        return resetProject(rest, store, options);
+    }
+    if (command === "replace") {
+        return replaceProject(rest, store, options);
+    }
+    if (command === "retire") {
+        return retireProjectCommand(rest, store, options);
+    }
+    if (command === "delete") {
+        return deleteProjectCommand(rest, store, options);
+    }
     if (command === "discover") {
         const discovered = await discoverProjects(rest, store, options);
         return { output: renderDiscoveredProjects(discovered), data: { projects: discovered } };
@@ -77,6 +90,7 @@ async function refreshProject(args, store, options) {
         throw usageError("Project refresh usage: yui project refresh <project>.");
     }
     const project = requireProject(store, args[0]);
+    assertProjectActive(project, "refresh");
     if (project.remoteUrl === undefined) {
         throw usageError(`Project refresh requires a remote URL: ${project.id}.`);
     }
@@ -280,6 +294,7 @@ async function migrateProject(args, store, options) {
     const usage = "Project migrate usage: yui project migrate <project> [--preflight].";
     const parsed = parseMigrateArguments(args, usage);
     const project = requireProject(store, parsed.project);
+    assertProjectActive(project, "migrate");
     if (project.ownership === "managed") {
         throw usageError(`Project is already Home-managed: ${project.id}.`);
     }
@@ -475,6 +490,7 @@ async function updateProject(args, store, options) {
     const usage = "Project update usage: yui project update <project> [--alias <name> ...|--clear-aliases] [--remote <url>|--clear-remote] [--stable <ref>] [--development <ref>].";
     const parsed = parseProjectUpdateArguments(args, usage);
     const current = requireProject(store, parsed.reference);
+    assertProjectActive(current, "update");
     const now = (options.now ?? (() => new Date()))();
     const patch = {
         ...(parsed.aliases === undefined ? {} : { aliases: parsed.aliases }),
@@ -514,6 +530,552 @@ async function updateProject(args, store, options) {
         return updated;
     });
 }
+/**
+ * Lifecycle commands (reset/replace/retire/delete) are Operator authority:
+ * they discard commits, replace checkouts, or remove catalog records, so a
+ * managed Task Session may never drive them. A plain terminal is the human
+ * Operator; a managed global Session must be the Operator role.
+ */
+function assertProjectOperator(options, action) {
+    const actor = projectActor(options.environment);
+    if (actor === "agent") {
+        throw usageError(`Project lifecycle commands are Operator authority; a managed Task Session cannot ${action} a Project. `
+            + "Run this command from an Operator or user terminal.");
+    }
+}
+/**
+ * Fail-closed gate for the destructive lifecycle commands: an active Task
+ * binding means the canonical checkout and catalog record are in active use,
+ * so reset/replace/retire refuse until the Task is settled. Historical
+ * (completed/retired/archived) bindings are reported but never block — their
+ * evidence lives in the Task records themselves.
+ */
+function assertNoActiveTaskBinding(store, project, action) {
+    const references = store.summarizeProjectReferences(project.id);
+    if (references.activeTaskIds.length > 0) {
+        const delivery = [
+            ...references.unresolvedWorkItemRefs,
+            ...references.activeRunRefs,
+            ...references.unresolvedIntegrationRefs
+        ];
+        throw usageError(`Project cannot be ${action} while an active Task binds it: ${project.id}. `
+            + `Active Tasks: ${references.activeTaskIds.join(", ")}.`
+            + (delivery.length === 0 ? "" : ` Unresolved delivery: ${delivery.join(", ")}.`)
+            + " Complete, retire, or archive those Tasks first.");
+    }
+    return references;
+}
+/**
+ * Controlled reset of a canonical Project checkout to its verified remote
+ * baseline. Handles the local/remote divergence that `project refresh`
+ * (clean fast-forward only) refuses: with `--discard-local` the checkout is
+ * hard-reset to the fetched remote commit, explicitly discarding the local
+ * commits listed in the refusal. Every destructive path is fail-closed:
+ * Operator authority, no active Task binding, clean checkout on its stable
+ * branch, reachable verified remote, and the per-Project maintenance fence.
+ */
+async function resetProject(args, store, options) {
+    const usage = "Project reset usage: yui project reset <project> [--discard-local].";
+    const parsed = parseResetArguments(args, usage);
+    const project = requireProject(store, parsed.project);
+    assertProjectOperator(options, "reset");
+    assertProjectActive(project, "reset");
+    if (project.remoteUrl === undefined) {
+        throw usageError(`Project reset requires a remote URL: ${project.id}.`);
+    }
+    if (project.stableBranch !== project.developmentBranch) {
+        throw usageError(`Project reset requires matching stable and development branches: ${project.id}.`);
+    }
+    const git = options.git ?? new NodeGitWorkspace();
+    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    try {
+        // Re-read under the fence so a concurrent catalog change can never drive
+        // a destructive Git effect from a stale snapshot.
+        const current = requireProject(store, project.id);
+        assertProjectActive(current, "reset");
+        if (current.path !== project.path
+            || current.remoteUrl !== project.remoteUrl
+            || current.stableBranch !== project.stableBranch
+            || current.developmentBranch !== project.developmentBranch) {
+            throw new Error(`Project changed while resetting: ${project.id}.`);
+        }
+        assertNoActiveTaskBinding(store, current, "reset");
+        const head = await git.inspect(current.path, "HEAD");
+        if (!await git.isClean(head.root)) {
+            throw usageError(`Project checkout must be clean before reset: ${current.id}. `
+                + "Commit, stash, or discard uncommitted changes first.");
+        }
+        const branch = await git.headRef(head.root);
+        if (branch !== current.stableBranch) {
+            const found = branch === "HEAD" ? "detached HEAD" : branch;
+            throw usageError(`Project checkout must be on its stable branch ${current.stableBranch} before reset (found ${found}).`);
+        }
+        // Fetch and verify the advertised remote baseline. An unreachable remote
+        // or a ref that moves mid-fetch fails closed here, before any local effect.
+        const remote = await git.resolveRemoteBaseline({
+            repositoryPath: head.root,
+            remoteUrl: current.remoteUrl,
+            developmentRef: current.stableBranch
+        });
+        const localCommit = head.baseCommit.toLowerCase();
+        const remoteCommit = remote.commit.toLowerCase();
+        if (localCommit === remoteCommit) {
+            return {
+                output: `Project ${current.id} is already at the remote baseline ${remoteCommit}.\n`,
+                data: {
+                    project: current,
+                    fromCommit: localCommit,
+                    toCommit: remoteCommit,
+                    changed: false,
+                    discarded: []
+                }
+            };
+        }
+        const isAncestor = await git.isAncestor(head.root, localCommit, remoteCommit);
+        if (!isAncestor) {
+            const discarded = await git.listCommitsBetween({
+                repositoryPath: head.root,
+                baseCommit: remoteCommit,
+                headCommit: localCommit
+            });
+            if (!parsed.discardLocal) {
+                throw usageError(`Project ${current.id} has diverged from ${current.remoteUrl}: local ${localCommit} `
+                    + `is not an ancestor of remote ${remoteCommit}.\n`
+                    + "Local commits that would be discarded:\n"
+                    + discarded.map((entry) => `  ${entry}`).join("\n")
+                    + "\nRe-run with --discard-local to hard-reset the checkout to the remote baseline.");
+            }
+            await git.resetToCommit({
+                repositoryPath: head.root,
+                expectedHead: localCommit,
+                targetCommit: remoteCommit
+            });
+            return {
+                output: `Reset project ${current.id}: ${localCommit} -> ${remoteCommit} `
+                    + `(discarded ${discarded.length} local commit(s)).\n`,
+                data: {
+                    project: current,
+                    fromCommit: localCommit,
+                    toCommit: remoteCommit,
+                    changed: true,
+                    discarded
+                }
+            };
+        }
+        // Behind only: the verified reset is a clean fast-forward.
+        await git.resetToCommit({
+            repositoryPath: head.root,
+            expectedHead: localCommit,
+            targetCommit: remoteCommit
+        });
+        return {
+            output: `Reset project ${current.id}: ${localCommit} -> ${remoteCommit} (fast-forward).\n`,
+            data: {
+                project: current,
+                fromCommit: localCommit,
+                toCommit: remoteCommit,
+                changed: true,
+                discarded: []
+            }
+        };
+    }
+    finally {
+        releaseMaintenance();
+    }
+}
+/**
+ * Replace a Home-managed canonical checkout with a fresh clone from its
+ * remote, preserving the catalog binding and Yui-local refs. For checkouts
+ * whose divergence or corruption is too severe for `project reset`. The
+ * discard is explicit (`--discard-local`), the remote is verified before the
+ * swap, and Task/Integration worktrees are protected by a linked-worktree
+ * gate. The swap itself is recoverable: the previous checkout is parked at a
+ * backup path and restored on any failure, and a crash mid-swap is healed on
+ * the next run (a crash before the swap leaves only a removable staging
+ * clone).
+ */
+async function replaceProject(args, store, options) {
+    const usage = "Project replace usage: yui project replace <project> --discard-local.";
+    const parsed = parseReplaceArguments(args, usage);
+    const project = requireProject(store, parsed.project);
+    assertProjectOperator(options, "replace");
+    assertProjectActive(project, "replace");
+    if (project.ownership !== "managed") {
+        throw usageError(`Project replace only applies to Home-managed checkouts: ${project.id}. `
+            + "External checkouts are user-owned; re-register or repair them with `yui project update`/`yui project add`.");
+    }
+    if (project.remoteUrl === undefined) {
+        throw usageError(`Project replace requires a remote URL: ${project.id}.`);
+    }
+    if (!parsed.discardLocal) {
+        throw usageError(`Project replace discards the current checkout and re-clones from ${project.remoteUrl}. `
+            + "Re-run with --discard-local to acknowledge that the checkout and any uncommitted state will be discarded.");
+    }
+    const git = options.git ?? new NodeGitWorkspace();
+    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    try {
+        const current = requireProject(store, project.id);
+        assertProjectActive(current, "replace");
+        if (current.path !== project.path
+            || current.remoteUrl !== project.remoteUrl
+            || current.ownership !== project.ownership
+            || current.stableBranch !== project.stableBranch
+            || current.developmentBranch !== project.developmentBranch) {
+            throw new Error(`Project changed while replacing: ${project.id}.`);
+        }
+        assertNoActiveTaskBinding(store, current, "replace");
+        const backup = join(store.rootDirectory(), "projects", `.replace-backup-${current.id}`);
+        // Heal a crashed earlier swap before any new destructive step, so the
+        // prechecks below always see a valid checkout.
+        await healCheckoutSwap({ currentPath: current.path, backupPath: backup });
+        // A linked worktree (Task/Integration workspace) shares this repository's
+        // object store and would be broken by a wholesale checkout replacement.
+        const worktrees = await git.listWorktrees(current.path);
+        const linked = worktrees.filter((path) => path !== current.path);
+        if (linked.length > 0) {
+            throw usageError(`Project checkout has linked worktrees that would break: ${current.id}.\n`
+                + linked.map((path) => `  ${path}`).join("\n")
+                + "\nClean up Task/Integration workspaces first (e.g. `yui task work cleanup`, `yui task integration cleanup`).");
+        }
+        if (!await git.isClean(current.path)) {
+            throw usageError(`Project checkout must be clean before replace: ${current.id}. `
+                + "Commit, stash, or discard uncommitted changes first.");
+        }
+        const staging = join(store.rootDirectory(), "projects", `.replace-${current.id}`);
+        if (existsSync(staging)) {
+            // A crashed earlier attempt can only leave its own staging clone behind.
+            await rm(staging, { recursive: true, force: true });
+        }
+        let prepared = false;
+        try {
+            const head = await git.clone({
+                remoteUrl: current.remoteUrl,
+                destination: staging,
+                ...(current.stableBranch === "HEAD" ? {} : { branch: current.stableBranch })
+            });
+            prepared = true;
+            const stable = current.stableBranch === "HEAD"
+                ? head
+                : await git.inspect(staging, current.stableBranch);
+            if (head.baseCommit !== stable.baseCommit) {
+                throw new Error(`Project checkout is not on its stable ref: ${current.stableBranch}.`);
+            }
+            if (current.developmentBranch !== current.stableBranch) {
+                await git.ensureLocalBranch(staging, current.developmentBranch);
+            }
+            await assertRemoteBranchesVerified(git, staging, current.remoteUrl, [
+                { ref: current.stableBranch, localCommit: head.baseCommit },
+                ...(current.developmentBranch === current.stableBranch
+                    ? []
+                    : [{
+                            ref: current.developmentBranch,
+                            localCommit: (await git.inspect(staging, current.developmentBranch)).baseCommit
+                        }])
+            ]);
+            // Preserve Yui-local refs (Task branches, archive refs) so historical
+            // evidence keeps resolving after the checkout is replaced.
+            const copyRefs = git.copyRefs;
+            if (typeof copyRefs !== "function") {
+                throw new Error(`Git workspace cannot preserve local Yui refs for Project: ${project.id}.`);
+            }
+            await copyRefs.call(git, {
+                sourceRepositoryPath: current.path,
+                destinationRepositoryPath: staging,
+                patterns: ["refs/heads/yui/", "refs/yui/archive/"]
+            });
+            const oldHead = (await git.inspect(current.path, "HEAD")).baseCommit;
+            // Swap the checkout on disk without ever leaving the registered path
+            // without a repository: the previous checkout is parked at the backup
+            // path first and restored on any failure. The backup is removed only
+            // after the catalog transaction commits, so a crash in between stays
+            // recoverable (healed at the top of the next run).
+            await swapManagedCheckout({ currentPath: current.path, stagingPath: staging, backupPath: backup });
+            let switched;
+            try {
+                switched = store.transaction((tx) => {
+                    const latest = requireProject(tx, current.id);
+                    if (latest.path !== current.path || latest.ownership !== current.ownership) {
+                        throw new Error(`Project changed while replacing: ${current.id}.`);
+                    }
+                    const next = validateProject({
+                        ...latest,
+                        updatedAt: (options.now ?? (() => new Date()))().toISOString()
+                    });
+                    tx.saveProject(next);
+                    return next;
+                });
+            }
+            catch (error) {
+                try {
+                    await restoreCheckoutSwap({ currentPath: current.path, backupPath: backup });
+                }
+                catch (rollbackError) {
+                    throw new Error(`Project replace failed and checkout rollback was incomplete: ${messageOf(error)}; `
+                        + `rollback failed: ${messageOf(rollbackError)}. `
+                        + `The previous checkout remains parked at ${backup}.`);
+                }
+                throw error;
+            }
+            let backupLeftover = false;
+            try {
+                await rm(backup, { recursive: true, force: true });
+            }
+            catch {
+                backupLeftover = true;
+            }
+            const newHead = (await git.inspect(current.path, "HEAD")).baseCommit;
+            return {
+                output: `Replaced project ${current.id} checkout: ${oldHead} -> ${newHead} `
+                    + `(re-cloned from ${current.remoteUrl}).\n`
+                    + (backupLeftover
+                        ? `The previous checkout could not be removed; delete it manually: ${backup}.\n`
+                        : ""),
+                data: { project: switched, fromCommit: oldHead, toCommit: newHead }
+            };
+        }
+        catch (error) {
+            if (prepared && existsSync(staging)) {
+                await rm(staging, { recursive: true, force: true });
+            }
+            throw error;
+        }
+    }
+    finally {
+        releaseMaintenance();
+    }
+}
+/**
+ * Auditable soft deprecation. The catalog record, checkout, and every
+ * historical Task/Run/Review/Integration/Publication reference are retained;
+ * the Project can no longer be bound to new work or maintained. Hard removal
+ * is a separate `project delete` decision.
+ */
+function retireProjectCommand(args, store, options) {
+    const usage = "Project retire usage: yui project retire <project> --reason <text>.";
+    const parsed = parseRetireArguments(args, usage);
+    const project = requireProject(store, parsed.project);
+    assertProjectOperator(options, "retire");
+    assertProjectActive(project, "retire");
+    const actor = projectActor(options.environment);
+    const retiredBy = actor === "operator" ? "operator" : "user";
+    const now = (options.now ?? (() => new Date()))();
+    const retired = store.transaction((tx) => {
+        const latest = requireProject(tx, project.id);
+        assertProjectActive(latest, "retire");
+        assertNoActiveTaskBinding(tx, latest, "retire");
+        const next = retireProject(latest, parsed.reason, retiredBy, now);
+        tx.saveProject(next);
+        return { project: next, references: tx.summarizeProjectReferences(next.id) };
+    });
+    const lines = [
+        `Retired project ${retired.project.id} (${retired.project.name})`,
+        `Reason: ${parsed.reason}`,
+        `Retired by: ${retiredBy} at ${retired.project.retirement?.retiredAt ?? "?"}`,
+        "The catalog record, checkout, and historical Task/Run/Review/Integration/Publication evidence are retained.",
+        ...(retired.references.boundTaskIds.length === 0
+            ? []
+            : [`Historical Task bindings retained: ${retired.references.boundTaskIds.join(", ")}.`]),
+        "Use `yui project delete` to remove the catalog record once no Task references it."
+    ];
+    return {
+        output: lines.join("\n").concat("\n"),
+        data: { project: retired.project, references: retired.references }
+    };
+}
+/**
+ * Hard removal of a retired Project catalog record, optionally including its
+ * Home-managed checkout. Deletion is deliberately two-phase (retire first)
+ * and doubly acknowledged (--confirm with the exact Project id), and it fails
+ * closed while any Task record references the Project so historical evidence
+ * stays resolvable. With `--checkout`, every fail-closed precheck (linked
+ * worktrees, dirty checkout) runs before any destruction, and the checkout is
+ * moved to a tombstone before the catalog record is removed; any failure
+ * restores it, so catalog and checkout never disagree unrecoverably.
+ */
+async function deleteProjectCommand(args, store, options) {
+    const usage = "Project delete usage: yui project delete <project> [--checkout] --confirm <project-id>.";
+    const parsed = parseDeleteArguments(args, usage);
+    const project = requireProject(store, parsed.project);
+    assertProjectOperator(options, "delete");
+    if (project.status !== "retired") {
+        throw usageError(`Project must be retired before it can be deleted: ${project.id}. `
+            + "Use `yui project retire <project> --reason <text>` first; retirement keeps the audit trail.");
+    }
+    if (parsed.confirm !== project.id) {
+        throw usageError(`Project delete requires --confirm ${project.id} to acknowledge removal of the catalog record`
+            + `${parsed.checkout ? " and the checkout" : ""}.`);
+    }
+    if (parsed.checkout && project.ownership !== "managed") {
+        throw usageError(`Project delete --checkout only applies to Home-managed checkouts: ${project.id}. `
+            + "External checkouts are user-owned; remove them manually after deleting the binding.");
+    }
+    if (!parsed.checkout) {
+        const removed = removeRetiredProjectRecord(store, project.id);
+        return {
+            output: `Deleted project ${removed.id} (catalog record; checkout retained at ${removed.path}).\n`,
+            data: { project: removed, checkoutRemoved: false }
+        };
+    }
+    // --checkout: prechecks first, then a rename/tombstone two-phase flow. The
+    // checkout moves to a tombstone before the catalog record is removed, and
+    // every failure restores it, so the catalog never loses its recoverable
+    // entry while a live checkout (or its failure) is still in play.
+    const tombstone = join(store.rootDirectory(), "projects", `.delete-${project.id}`);
+    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    try {
+        // Heal a crashed earlier attempt before the prechecks run.
+        await healCheckoutSwap({ currentPath: project.path, backupPath: tombstone });
+        if (existsSync(project.path)) {
+            const git = options.git ?? new NodeGitWorkspace();
+            const worktrees = await git.listWorktrees(project.path);
+            const linked = worktrees.filter((path) => path !== project.path);
+            if (linked.length > 0) {
+                throw usageError(`Project checkout has linked worktrees that would break: ${project.id}.\n`
+                    + linked.map((path) => `  ${path}`).join("\n")
+                    + "\nClean up Task/Integration workspaces first (e.g. `yui task work cleanup`, `yui task integration cleanup`).");
+            }
+            if (!await git.isClean(project.path)) {
+                throw usageError(`Project checkout must be clean before delete: ${project.id}. `
+                    + "Commit, stash, or discard uncommitted changes first, or delete the catalog record only without --checkout.");
+            }
+            // Phase 1: park the checkout. The catalog record still exists, so
+            // phase 2 must complete or roll the rename back.
+            await rename(project.path, tombstone);
+        }
+        // Phase 2: remove the catalog record, restoring the checkout on failure.
+        let removed;
+        try {
+            removed = removeRetiredProjectRecord(store, project.id);
+        }
+        catch (error) {
+            if (existsSync(tombstone) && !existsSync(project.path)) {
+                try {
+                    await rename(tombstone, project.path);
+                }
+                catch (rollbackError) {
+                    throw new Error(`Project delete failed and checkout rollback was incomplete: ${messageOf(error)}; `
+                        + `rollback failed: ${messageOf(rollbackError)}. `
+                        + `The checkout remains parked at ${tombstone}.`);
+                }
+            }
+            throw error;
+        }
+        // Phase 3: the catalog record is gone, so the tombstone is unreferenced
+        // garbage. Removal is best-effort; a leftover is reported, never silent.
+        let tombstoneLeftover = false;
+        if (existsSync(tombstone)) {
+            try {
+                await rm(tombstone, { recursive: true, force: true });
+            }
+            catch {
+                tombstoneLeftover = true;
+            }
+        }
+        return {
+            output: `Deleted project ${removed.id} and its checkout at ${removed.path}.\n`
+                + (tombstoneLeftover
+                    ? `The checkout tombstone could not be removed; delete it manually: ${tombstone}.\n`
+                    : ""),
+            data: { project: removed, checkoutRemoved: true }
+        };
+    }
+    finally {
+        releaseMaintenance();
+    }
+}
+/**
+ * The catalog side of `project delete`: re-read under a transaction, re-assert
+ * the retired state and the absence of any Task reference, then remove the
+ * record. Fails closed with the record intact on every refusal.
+ */
+function removeRetiredProjectRecord(store, projectId) {
+    return store.transaction((tx) => {
+        const latest = requireProject(tx, projectId);
+        if (latest.status !== "retired") {
+            throw new Error(`Project changed while deleting: ${projectId}.`);
+        }
+        const references = tx.summarizeProjectReferences(latest.id);
+        if (references.boundTaskIds.length > 0) {
+            throw usageError(`Project cannot be deleted while Task records reference it: ${latest.id}. `
+                + `Bound Tasks: ${references.boundTaskIds.join(", ")}. `
+                + "Historical Task/Run/Review/Integration/Publication evidence must stay resolvable; keep the Project retired instead.");
+        }
+        if (!tx.removeProject(latest.id)) {
+            throw new Error(`Project was already removed: ${latest.id}.`);
+        }
+        return latest;
+    });
+}
+function parseResetArguments(args, usage) {
+    const positionals = [];
+    let discardLocal = false;
+    for (const value of args) {
+        if (value === "--discard-local") {
+            discardLocal = true;
+            continue;
+        }
+        if (value.startsWith("--"))
+            throw usageError(`Unknown option: ${value}. ${usage}`);
+        positionals.push(value);
+    }
+    if (positionals.length !== 1)
+        throw usageError(usage);
+    return { project: requireText(positionals[0], "Project reference"), discardLocal };
+}
+function parseReplaceArguments(args, usage) {
+    return parseResetArguments(args, usage);
+}
+function parseRetireArguments(args, usage) {
+    const positionals = [];
+    let reason;
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value === "--reason") {
+            const next = args[index + 1];
+            if (next === undefined || next.startsWith("--"))
+                throw usageError(`--reason is required. ${usage}`);
+            reason = requireText(next, "--reason");
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("--"))
+            throw usageError(`Unknown option: ${value}. ${usage}`);
+        positionals.push(value);
+    }
+    if (positionals.length !== 1)
+        throw usageError(usage);
+    if (reason === undefined)
+        throw usageError(`--reason is required. ${usage}`);
+    return { project: requireText(positionals[0], "Project reference"), reason };
+}
+function parseDeleteArguments(args, usage) {
+    const positionals = [];
+    let checkout = false;
+    let confirm;
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value === "--checkout") {
+            checkout = true;
+            continue;
+        }
+        if (value === "--confirm") {
+            const next = args[index + 1];
+            if (next === undefined || next.startsWith("--"))
+                throw usageError(`--confirm is required. ${usage}`);
+            confirm = requireText(next, "--confirm");
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("--"))
+            throw usageError(`Unknown option: ${value}. ${usage}`);
+        positionals.push(value);
+    }
+    if (positionals.length !== 1)
+        throw usageError(usage);
+    if (confirm === undefined)
+        throw usageError(`--confirm is required. ${usage}`);
+    return { project: requireText(positionals[0], "Project reference"), checkout, confirm };
+}
 function renderAddedProject(created) {
     return [
         `Added project ${created.id}`,
@@ -559,6 +1121,7 @@ function listProjects(args, store) {
     return `${renderTable("Projects", [
         { header: "Project", minWidth: 8, maxWidth: 24 },
         { header: "Name", minWidth: 4, maxWidth: 28 },
+        { header: "Status", minWidth: 6, maxWidth: 8 },
         { header: "Ownership", minWidth: 9, maxWidth: 10 },
         { header: "Path", minWidth: 8, maxWidth: 64 },
         { header: "Stable", minWidth: 6, maxWidth: 24 },
@@ -566,6 +1129,7 @@ function listProjects(args, store) {
     ], projects.map((project) => [
         project.id,
         project.name,
+        project.status,
         project.ownership,
         project.path,
         project.stableBranch,
@@ -579,6 +1143,13 @@ function showProject(args, store) {
     return [
         `Project: ${project.id}`,
         `Name: ${project.name}`,
+        `Status: ${project.status}`,
+        ...(project.retirement === undefined
+            ? []
+            : [
+                `Retired by: ${project.retirement.retiredBy} at ${project.retirement.retiredAt}`,
+                `Retirement reason: ${project.retirement.reason}`
+            ]),
         `Ownership: ${project.ownership}`,
         `Aliases: ${project.aliases.length === 0 ? "-" : project.aliases.join(", ")}`,
         `Path: ${project.path}`,
@@ -599,6 +1170,7 @@ function projectKnowledge(args, store, options) {
         assertKnowledgeOperator(options, "add");
         const added = store.transaction((tx) => {
             const project = requireProject(tx, parsed.positionals[0]);
+            assertProjectActive(project, "add project knowledge");
             const id = nextKnowledgeId(project);
             tx.saveProject(addProjectKnowledge(project, id, parsed.positionals[1], parsed.value, (options.now ?? (() => new Date()))()));
             return { id, projectId: project.id };
@@ -685,6 +1257,7 @@ function projectKnowledge(args, store, options) {
         assertKnowledgeOperator(options, "retire");
         const updated = store.transaction((tx) => {
             const project = requireProject(tx, rest[0]);
+            assertProjectActive(project, "retire project knowledge");
             const next = retireProjectKnowledge(project, rest[1], (options.now ?? (() => new Date()))());
             tx.saveProject(next);
             return next;
@@ -823,6 +1396,7 @@ function proposeKnowledge(args, store, options) {
     const now = (options.now ?? (() => new Date()))();
     const result = store.transaction((tx) => {
         const project = requireProject(tx, parsed.project);
+        assertProjectActive(project, "propose project knowledge");
         const source = requireProposalEvidence(tx, parsed);
         const fingerprint = knowledgeProposalFingerprint({
             projectId: project.id,
@@ -1056,6 +1630,7 @@ function acceptKnowledgeProposal(args, store, options) {
     const now = (options.now ?? (() => new Date()))();
     const accepted = store.transaction((tx) => {
         const project = requireProject(tx, parsed.project);
+        assertProjectActive(project, "accept project knowledge");
         const proposal = findKnowledgeProposal(project, parsed.proposal);
         if (proposal === null) {
             throw usageError(`Knowledge proposal not found: ${parsed.proposal}.`);
@@ -1143,6 +1718,7 @@ function rejectKnowledgeProposal(args, store, options) {
     const decidedBy = actor === "operator" ? "operator" : "user";
     const rejected = store.transaction((tx) => {
         const project = requireProject(tx, parsed.positionals[0]);
+        assertProjectActive(project, "reject project knowledge");
         const proposal = findKnowledgeProposal(project, parsed.positionals[1]);
         if (proposal === null) {
             throw usageError(`Knowledge proposal not found: ${parsed.positionals[1]}.`);
@@ -1412,3 +1988,6 @@ function requireText(value, label) {
     }
     return normalized;
 }
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/commands/taskCommands.js

@@ -40,7 +40,7 @@ import { activateTask, addTaskProjectBinding, archiveTask, completeTask, createT
 import { resolveTaskRecordReference } from "../task/taskRecordReference.js";
 import { TASK_COMPLETION_PUBLISHED_TREE_AUTHORIZED_EVENT } from "../task/publicationReference.js";
 import { projectCompletionReadiness } from "../task/completionReadiness.js";
-import { resolveProject } from "../repository/project.js";
+import { assertProjectActive, resolveProject } from "../repository/project.js";
 import { acquireProjectMaintenanceLocks } from "../repository/projectMaintenanceLock.js";
 import { currentWorkItemCandidate, currentWorkItemExecutionGroup, workItemExecutionGroupById, createWorkItem, planWorkItemExplorationStage, attachWorkItemExecutionGroup, updateWorkItemExecutionGroup, retireWorkItem, retryFailedWorkItem, submitWorkItemCandidate, updateWorkItemWriteProjects, updateWorkItemStatus } from "../workItem/workItem.js";
 import { addExecutionLane, createExecutionGroup, queueExecutionLaneRetry, resolveExecutionGroup, restartExecutionLane, skipPendingExecutionLanes, updateExecutionLane, WORK_ITEM_EXECUTION_MODES } from "../execution/executionGroup.js";
@@ -385,6 +385,7 @@ function taskProjectCommand(args, store, options) {
         const project = resolveProject(tx.listProjects(), parsed.positionals[1]);
         if (project === null)
             throw usageError(`Project not found: ${parsed.positionals[1]}.`);
+        assertProjectActive(project, "bind to a Task");
         const next = addTaskProjectBinding(task, {
             projectId: project.id,
             directory: parsed.options.get("--directory") ?? project.name,
@@ -532,6 +533,7 @@ function parseTaskCreation(args, store) {
         const project = resolveProject(store.listProjects(), reference);
         if (project === null)
             throw usageError(`Project not found: ${reference}.`);
+        assertProjectActive(project, "bind to a Task");
         return project;
     });
     if (new Set(projects.map(({ id }) => id)).size !== projects.length) {
@@ -1857,6 +1859,7 @@ function createWork(args, store, options) {
             const project = resolveProject(task.projectBindings.map(({ projectId }) => requireProject(tx, projectId)), reference);
             if (project === null)
                 throw usageError(`Task Project not found: ${reference}.`);
+            assertProjectActive(project, "scope a Work Item");
             return project.id;
         });
         const baseRefs = parsed.baseRefs.map(({ project, baseRef }) => {
@@ -1914,6 +1917,7 @@ function updateWorkScope(args, store, options) {
             const project = resolveProject(task.projectBindings.map(({ projectId }) => requireProject(tx, projectId)), reference);
             if (project === null)
                 throw usageError(`Task Project not found: ${reference}.`);
+            assertProjectActive(project, "scope a Work Item");
             return project.id;
         });
         const requested = new Set(requestedProjectIds);

package/dist/commands/taskIntegrationCommands.js

@@ -1,5 +1,5 @@
 import { NodeGitWorkspace } from "../repository/gitWorkspace.js";
-import { resolveProject } from "../repository/project.js";
+import { assertProjectActive, resolveProject } from "../repository/project.js";
 import { workspaceProjectEntry } from "../worktree/managedWorkspace.js";
 import { usageError } from "../errors/cliError.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
@@ -114,6 +114,7 @@ async function start(args, store, home, now, options) {
         : resolveProject(store.listProjects(), requestedProject);
     if (project === null)
         throw usageError(`Project not found: ${requestedProject ?? projectIds[0]}.`);
+    assertProjectActive(project, "start an Integration");
     if (project.id !== projectIds[0]) {
         throw usageError(`ChangeSets belong to another Project: ${projectIds[0]}.`);
     }

package/dist/repository/checkoutSwap.js

@@ -0,0 +1,61 @@
+import { existsSync } from "node:fs";
+import { rename as defaultRename, rm as defaultRm } from "node:fs/promises";
+const realPorts = {
+    rename: (sourcePath, targetPath) => defaultRename(sourcePath, targetPath),
+    remove: (path) => defaultRm(path, { recursive: true, force: true })
+};
+/**
+ * Heal the on-disk state of a crashed earlier swap before any new destructive
+ * step runs. A backup next to a live checkout is a leftover from a completed
+ * swap whose cleanup crashed and is removed; a backup without a live checkout
+ * means the crash happened mid-swap, so the previous checkout is restored
+ * intact. With no backup there is nothing to heal.
+ */
+export async function healCheckoutSwap(request, ports = realPorts) {
+    if (!existsSync(request.backupPath))
+        return;
+    if (existsSync(request.currentPath)) {
+        await ports.remove(request.backupPath);
+        return;
+    }
+    await ports.rename(request.backupPath, request.currentPath);
+}
+/**
+ * Promote a prepared staging checkout into the registered path without ever
+ * leaving the registered path without a valid repository. The previous
+ * checkout is moved to the backup path first; if the promotion fails it is
+ * restored and the staging clone is removed. A crash between the two renames
+ * is healed by {@link healCheckoutSwap} on the next run.
+ */
+export async function swapManagedCheckout(request, ports = realPorts) {
+    await healCheckoutSwap(request, ports);
+    await ports.rename(request.currentPath, request.backupPath);
+    try {
+        await ports.rename(request.stagingPath, request.currentPath);
+    }
+    catch (error) {
+        try {
+            await ports.rename(request.backupPath, request.currentPath);
+        }
+        catch (rollbackError) {
+            throw new Error(`Checkout swap failed and rollback was incomplete: ${messageOf(error)}; `
+                + `rollback failed: ${messageOf(rollbackError)}. `
+                + `The previous checkout remains parked at ${request.backupPath}.`);
+        }
+        await ports.remove(request.stagingPath).catch(() => { });
+        throw error;
+    }
+}
+/**
+ * Restore the parked previous checkout after a committed swap had to be undone
+ * (for example because the catalog transaction refused the change). The
+ * promoted clone is discarded first; if the restore fails the parked checkout
+ * stays recoverable through {@link healCheckoutSwap}.
+ */
+export async function restoreCheckoutSwap(request, ports = realPorts) {
+    await ports.remove(request.currentPath);
+    await ports.rename(request.backupPath, request.currentPath);
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/repository/gitWorkspace.js

@@ -694,6 +694,42 @@ export class NodeGitWorkspace {
             throw new Error(`Git reset compensation failed for ${target}; Candidate materialization remains retained for diagnosis.`, { cause: error });
         }
     }
+    async resetToCommit(input) {
+        const root = await canonicalDirectory(input.repositoryPath, "Project");
+        const expectedHead = requireText(input.expectedHead, "Expected head");
+        const targetCommit = requireText(input.targetCommit, "Target commit");
+        if (!await this.isClean(root)) {
+            throw new Error(`Project checkout must be clean before reset: ${root}.`);
+        }
+        const currentHead = (await this.inspect(root, "HEAD")).baseCommit;
+        if (currentHead.toLowerCase() !== expectedHead.toLowerCase()) {
+            throw new Error(`Project checkout changed before reset: ${root} (${currentHead}).`);
+        }
+        // Verify the target commit resolves before moving the branch.
+        await gitLine(["-C", root, "rev-parse", "--verify", "--end-of-options", `${targetCommit}^{commit}`]);
+        await git(["-C", root, "reset", "--hard", targetCommit]);
+        const restoredHead = (await this.inspect(root, "HEAD")).baseCommit;
+        if (restoredHead.toLowerCase() !== targetCommit.toLowerCase() || !await this.isClean(root)) {
+            throw new Error(`Project checkout did not reset to the exact target commit: ${root}.`);
+        }
+    }
+    async listWorktrees(repositoryPath) {
+        const root = await canonicalDirectory(repositoryPath, "Project");
+        const output = await git(["-C", root, "worktree", "list", "--porcelain"]);
+        return output
+            .split(/\r?\n/u)
+            .filter((line) => line.startsWith("worktree "))
+            .map((line) => line.slice("worktree ".length).trim());
+    }
+    async listCommitsBetween(input) {
+        const root = await canonicalDirectory(input.repositoryPath, "Project");
+        const range = `${requireText(input.baseCommit, "Base commit")}..${requireText(input.headCommit, "Head commit")}`;
+        const output = await git(["-C", root, "log", "--oneline", range]);
+        return output
+            .split(/\r?\n/u)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+    }
     async #assertRefreshCheckout(repositoryPath, stableRef, expectedCommit) {
         if (stableRef !== "HEAD") {
             const currentBranch = await this.headRef(repositoryPath);

package/dist/repository/project.js

@@ -8,7 +8,7 @@ export function managedProjectPath(home, projectId) {
 export function createProject(id, name, path, branches, now, metadata = {}) {
     const timestamp = now.toISOString();
     return validateProject({
-        schemaVersion: 4,
+        schemaVersion: 5,
         id: requireIdentity(id, "Project id"),
         name: validateProjectName(name),
         aliases: normalizeAliases(metadata.aliases ?? [], name),
@@ -19,6 +19,7 @@ export function createProject(id, name, path, branches, now, metadata = {}) {
             : { remoteUrl: requireText(metadata.remoteUrl, "Project remote URL") }),
         stableBranch: requireGitRef(branches.stable, "Project stable branch"),
         developmentBranch: requireGitRef(branches.development, "Project development branch"),
+        status: "active",
         knowledge: [],
         knowledgeProposals: [],
         createdAt: timestamp,
@@ -28,6 +29,38 @@ export function createProject(id, name, path, branches, now, metadata = {}) {
 export function validateProjectName(value) {
     return requireIdentity(value, "Project name");
 }
+/**
+ * Soft-retire a Project: mark it retired and record the audit trail. The
+ * catalog record, checkout, and every historical Task/Run/Review/Integration/
+ * Publication reference are retained. Retiring an already-retired Project
+ * fails closed; a retired Project must be deleted (or kept) as-is.
+ */
+export function retireProject(project, reason, by, now) {
+    if (project.status === "retired") {
+        throw new Error(`Project is already retired: ${project.id}.`);
+    }
+    const timestamp = now.toISOString();
+    return validateProject({
+        ...project,
+        status: "retired",
+        retirement: {
+            reason: requireText(reason, "Project retirement reason"),
+            retiredBy: by,
+            retiredAt: timestamp
+        },
+        updatedAt: timestamp
+    });
+}
+/**
+ * Refuse a mutation or new binding against a retired Project. Read-only
+ * inspection (`project show`, `project diagnose`, knowledge reads) remains
+ * allowed, so historical evidence stays auditable.
+ */
+export function assertProjectActive(project, action) {
+    if (project.status === "retired") {
+        throw new Error(`Project is retired and cannot ${action}: ${project.id}.`);
+    }
+}
 export function addProjectKnowledge(project, id, title, body, now, provenance) {
     const timestamp = now.toISOString();
     const knowledge = {
@@ -243,8 +276,8 @@ export function assertProjectCatalog(projects) {
     }
 }
 export function validateProject(project) {
-    if (project.schemaVersion !== 4) {
-        throw new Error("Project must use schemaVersion 4.");
+    if (project.schemaVersion !== 5) {
+        throw new Error("Project must use schemaVersion 5.");
     }
     requireIdentity(project.id, "Project id");
     requireIdentity(project.name, "Project name");
@@ -252,6 +285,23 @@ export function validateProject(project) {
     if (project.ownership !== "managed" && project.ownership !== "external") {
         throw new Error(`Project ownership is invalid: ${String(project.ownership)}.`);
     }
+    if (project.status !== "active" && project.status !== "retired") {
+        throw new Error(`Project status is invalid: ${String(project.status)}.`);
+    }
+    if (project.status === "retired") {
+        const retirement = project.retirement;
+        if (retirement === undefined) {
+            throw new Error(`Retired Project must carry its retirement record: ${project.id}.`);
+        }
+        requireText(retirement.reason, "Project retirement reason");
+        if (retirement.retiredBy !== "user" && retirement.retiredBy !== "operator") {
+            throw new Error("Project retirement actor is invalid.");
+        }
+        requireTimestamp(retirement.retiredAt, "Project retirement retiredAt");
+    }
+    else if (project.retirement !== undefined) {
+        throw new Error(`Active Project must not carry a retirement record: ${project.id}.`);
+    }
     const references = new Set();
     for (const reference of [project.id, project.name, ...project.aliases]) {
         const folded = reference.toLocaleLowerCase();

package/dist/storage/migration/productionRegistry.js

@@ -18,6 +18,8 @@ const PROJECT_FROM_VERSION = 2;
 const PROJECT_TO_VERSION = 3;
 const PROJECT_KNOWLEDGE_PROPOSALS_FROM_VERSION = 3;
 const PROJECT_KNOWLEDGE_PROPOSALS_TO_VERSION = 4;
+const PROJECT_LIFECYCLE_FROM_VERSION = 4;
+const PROJECT_LIFECYCLE_TO_VERSION = 5;
 const TASK_FROM_VERSION = 3;
 const TASK_TO_VERSION = 4;
 const TASK_INTENT_FROM_VERSION = 4;
@@ -145,6 +147,7 @@ export function createProductionStorageRegistry() {
         .registerOfflineMigration(projectOwnershipStep())
         .registerOfflineMigration(configV2Step())
         .registerCompatible(projectKnowledgeProposalsStep())
+        .registerCompatible(projectLifecycleStep())
         .registerOfflineMigration(taskWorkspaceIdentityStep())
         .registerOfflineMigration(taskIntentStep())
         .registerOfflineMigration(recordFamilyStep("workItem", WORK_ITEM_FROM_VERSION, WORK_ITEM_TO_VERSION, "workItems"))
@@ -2761,6 +2764,91 @@ function normalizeProjectV3ToV4(snapshot) {
         state: { ...snapshot.state, projects: nextProjects }
     };
 }
+/**
+ * Project v5 adds the lifecycle status (`active`/`retired`) plus the
+ * retirement audit record. Historical Projects are all active; the step only
+ * defaults the new field, so it is a compatible adjacent migration.
+ */
+function projectLifecycleStep() {
+    return {
+        kind: "compatible",
+        axis: "record",
+        recordKind: "project",
+        fromVersion: PROJECT_LIFECYCLE_FROM_VERSION,
+        toVersion: PROJECT_LIFECYCLE_TO_VERSION,
+        defaults: [
+            "status defaults to active on every Project"
+        ],
+        validateSource: (snapshot) => requireProjectV4Shape(snapshot),
+        normalize: (snapshot) => normalizeProjectV4ToV5(snapshot)
+    };
+}
+function requireProjectV4Shape(snapshot) {
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (manifestVersions.project !== PROJECT_LIFECYCLE_FROM_VERSION) {
+        throw new Error(`Record project compatible step requires manifest version ${PROJECT_LIFECYCLE_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const projects = snapshot.state.projects;
+    if (projects === undefined)
+        return;
+    const map = asObject(projects, "project map");
+    const allowed = new Set(PROJECT_V4_FIELDS);
+    for (const [projectId, rawProject] of Object.entries(map)) {
+        const project = asObject(rawProject, `Project ${projectId}`);
+        if (project.schemaVersion !== PROJECT_LIFECYCLE_FROM_VERSION) {
+            throw new Error(`Project ${projectId} must use schemaVersion ${PROJECT_LIFECYCLE_FROM_VERSION}.`);
+        }
+        const unknown = Object.keys(project).find((key) => !allowed.has(key));
+        if (unknown !== undefined) {
+            throw new Error(`Project ${projectId} has an unknown v4 field: ${unknown}.`);
+        }
+    }
+}
+function normalizeProjectV4ToV5(snapshot) {
+    requireProjectV4Shape(snapshot);
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: { ...manifestVersions, project: PROJECT_LIFECYCLE_TO_VERSION }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const projects = snapshot.state.projects;
+    if (projects === undefined) {
+        return { schemaManifest, state: { ...snapshot.state } };
+    }
+    const map = asObject(projects, "project map");
+    const nextProjects = {};
+    for (const [projectId, rawProject] of Object.entries(map)) {
+        const project = asObject(rawProject, `Project ${projectId}`);
+        nextProjects[projectId] = {
+            ...project,
+            schemaVersion: PROJECT_LIFECYCLE_TO_VERSION,
+            status: "active"
+        };
+    }
+    return {
+        schemaManifest,
+        state: { ...snapshot.state, projects: nextProjects }
+    };
+}
+const PROJECT_V4_FIELDS = [
+    "schemaVersion",
+    "id",
+    "name",
+    "aliases",
+    "path",
+    "ownership",
+    "remoteUrl",
+    "stableBranch",
+    "developmentBranch",
+    "knowledge",
+    "knowledgeProposals",
+    "createdAt",
+    "updatedAt"
+];
 /**
  * Task v4 adds the optional durable workspace identity. Historical Tasks have
  * no identity; they keep working against their existing (legacy) refs until the

package/dist/storage/sqliteStore.js

@@ -596,7 +596,43 @@ export class SqliteTaskStore {
         return this.#getPayload("projects", "id = ?", [id]);
     }
     removeProject(id) {
-        return this.#mutate(() => this.#db.prepare("DELETE FROM projects WHERE id = ?").run(id).changes > 0);
+        return this.#mutate(() => {
+            if (this.listTasks().some((task) => task.projectBindings.some((binding) => binding.projectId === id))) {
+                throw new StorageRecordError(`Project is still used by a Task: ${id}`);
+            }
+            return this.#db.prepare("DELETE FROM projects WHERE id = ?").run(id).changes > 0;
+        });
+    }
+    summarizeProjectReferences(projectId) {
+        const boundTasks = this.listTasks().filter((task) => task.projectBindings.some((binding) => binding.projectId === projectId));
+        const activeTasks = boundTasks.filter((task) => task.status === "active");
+        const unresolvedWorkItemRefs = [];
+        const activeRunRefs = [];
+        const unresolvedIntegrationRefs = [];
+        for (const task of activeTasks) {
+            for (const workItem of this.listWorkItems(task.id)) {
+                if (workItem.status !== "completed" && workItem.status !== "retired") {
+                    unresolvedWorkItemRefs.push(`${task.id}/${workItem.id}`);
+                }
+            }
+            for (const run of this.listAgentRuns(task.id)) {
+                if (run.status === "active")
+                    activeRunRefs.push(`${task.id}/${run.id}`);
+            }
+            for (const attempt of this.listIntegrationAttempts(task.id)) {
+                if (attempt.status === "running" || attempt.status === "blocked") {
+                    unresolvedIntegrationRefs.push(`${task.id}/${attempt.id}`);
+                }
+            }
+        }
+        return {
+            projectId,
+            boundTaskIds: boundTasks.map(({ id }) => id),
+            activeTaskIds: activeTasks.map(({ id }) => id),
+            unresolvedWorkItemRefs,
+            activeRunRefs,
+            unresolvedIntegrationRefs
+        };
     }
     // -- agent profiles ---------------------------------------------------------
     saveAgentProfile(profile) {
@@ -1485,9 +1521,10 @@ export class SqliteTaskStore {
             if (round === null) {
                 throw new StorageRecordError(`Agent run ReviewRound not found: ${run.reviewRoundId}.`);
             }
+            const roundWorkItemId = round.workItemId ?? round.legacyAnchor?.workItemId;
             const laneRole = round.executionGroup?.lanes
                 .find(({ id }) => id === run.executionLaneId)?.roleName;
-            if (round.workItemId !== run.workItemId
+            if (roundWorkItemId !== run.workItemId
                 || (round.reviewerRoleName !== run.roleName && laneRole !== run.roleName)) {
                 throw new StorageRecordError(`Agent run does not match ReviewRound: ${run.id}.`);
             }

package/dist/storage/taskStore.js

@@ -58,7 +58,7 @@ export const CURRENT_ACTIVE_RUN_POINTER_SCHEMA_VERSION = 3;
  * below, but are not independent record-axis families.
  */
 export const CURRENT_CONFIGURED_AGENT_SCHEMA_VERSION = 2;
-export const CURRENT_PROJECT_SCHEMA_VERSION = 4;
+export const CURRENT_PROJECT_SCHEMA_VERSION = 5;
 export const CURRENT_AGENT_PROFILE_SCHEMA_VERSION = 2;
 export const CURRENT_GLOBAL_ROLE_SCHEMA_VERSION = 3;
 export const CURRENT_GLOBAL_ROLE_SESSION_SET_SCHEMA_VERSION = 3;
@@ -279,6 +279,37 @@ export class FileTaskStore {
             return this.#remove((state) => state.projects, id);
         });
     }
+    summarizeProjectReferences(projectId) {
+        const boundTasks = this.listTasks().filter((task) => task.projectBindings.some((binding) => binding.projectId === projectId));
+        const activeTasks = boundTasks.filter((task) => task.status === "active");
+        const unresolvedWorkItemRefs = [];
+        const activeRunRefs = [];
+        const unresolvedIntegrationRefs = [];
+        for (const task of activeTasks) {
+            for (const workItem of this.listWorkItems(task.id)) {
+                if (workItem.status !== "completed" && workItem.status !== "retired") {
+                    unresolvedWorkItemRefs.push(`${task.id}/${workItem.id}`);
+                }
+            }
+            for (const run of this.listAgentRuns(task.id)) {
+                if (run.status === "active")
+                    activeRunRefs.push(`${task.id}/${run.id}`);
+            }
+            for (const attempt of this.listIntegrationAttempts(task.id)) {
+                if (attempt.status === "running" || attempt.status === "blocked") {
+                    unresolvedIntegrationRefs.push(`${task.id}/${attempt.id}`);
+                }
+            }
+        }
+        return {
+            projectId,
+            boundTaskIds: boundTasks.map(({ id }) => id),
+            activeTaskIds: activeTasks.map(({ id }) => id),
+            unresolvedWorkItemRefs,
+            activeRunRefs,
+            unresolvedIntegrationRefs
+        };
+    }
     saveAgentProfile(profile) {
         const stored = identified(profile, CURRENT_AGENT_PROFILE_SCHEMA_VERSION, "id", profile.id, "Agent Profile");
         validateAgentProfile(stored);
@@ -998,8 +1029,9 @@ export class FileTaskStore {
             if (round === undefined) {
                 throw new StorageRecordError(`Agent run ReviewRound not found: ${stored.reviewRoundId}.`);
             }
+            const roundWorkItemId = round.workItemId ?? round.legacyAnchor?.workItemId;
             const laneRole = round.executionGroup?.lanes.find(({ id }) => id === stored.executionLaneId)?.roleName;
-            if (round.workItemId !== stored.workItemId
+            if (roundWorkItemId !== stored.workItemId
                 || (round.reviewerRoleName !== stored.roleName && laneRole !== stored.roleName)) {
                 throw new StorageRecordError(`Agent run does not match ReviewRound: ${stored.id}.`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,