@opengsd/gsd-pi 1.2.0-dev.4813ead6 → 1.2.0-dev.5457a158

package/dist/resources/extensions/gsd/unit-closeout.js

@@ -0,0 +1,138 @@
+// Project/App: gsd-pi
+// File Purpose: Unit Closeout module — durable completion pipeline behind one seam (ADR-032).
+//
+// `closeUnit` owns what makes a Unit's completion durable. This pass ships the
+// **Interactive Closeout adapter** path: commit the work and compute the
+// Closeout Git Verdict, failing closed (loudly) instead of silently when a
+// non-`none` `git.isolation` preference was never honoured by the session.
+// Motivating failure (2026-06-10): an interactive session under
+// `git.isolation: worktree` completed a milestone with every source file
+// untracked on the integration branch — no commit, no merge, no warning.
+//
+// The interactive adapter only fires on milestone boundaries — the durability
+// gap is the milestone close, and committing at every task/slice would sweep a
+// developer's unrelated working-tree changes. `closeUnit` itself stays general
+// over all boundaries for the pending Auto Closeout adapter re-seat.
+//
+// The auto loop keeps its existing closeout pipeline for now (the Auto
+// Closeout adapter re-seat is the documented next step in ADR-032); the
+// interactive trigger in bootstrap/register-hooks.ts is a no-op while
+// `isAutoActive()`, so auto-mode behaviour is untouched.
+//
+// Re-entrancy is naturally safe: a re-fired completion commits an already-clean
+// tree, which yields `nothing-to-commit`, and `appendNotification` carries its
+// own dedup window — so `closeUnit` keeps no result cache of its own.
+import { appendNotification } from "./notification-store.js";
+import { readStringField } from "./auto-unit-tool-scope.js";
+import { MILESTONE_BRANCH_PREFIX } from "./branch-patterns.js";
+import { nativeGetCurrentBranch } from "./native-git-bridge.js";
+import { getIsolationMode } from "./preferences.js";
+import { autoCommitCurrentBranch } from "./worktree.js";
+import { logWarning } from "./workflow-logger.js";
+const defaultDeps = {
+    isolationMode: (basePath) => getIsolationMode(basePath),
+    currentBranch: (basePath) => {
+        try {
+            return nativeGetCurrentBranch(basePath);
+        }
+        catch {
+            return null;
+        }
+    },
+    commit: (basePath, unitType, unitId) => autoCommitCurrentBranch(basePath, unitType, unitId),
+    notify: (message, severity) => appendNotification(message, severity),
+};
+export function closeUnit(request, deps = defaultDeps) {
+    let commitMessage = null;
+    let gitVerdict;
+    let notice;
+    try {
+        commitMessage = deps.commit(request.basePath, request.unitType, request.unitId);
+        gitVerdict = commitMessage === null ? "nothing-to-commit" : "committed";
+    }
+    catch (err) {
+        gitVerdict = "commit-failed";
+        notice = `Unit closeout commit failed for ${request.unitId}: ${err instanceof Error ? err.message : String(err)}`;
+        logWarning("engine", notice);
+        deps.notify(notice, "error");
+    }
+    if (request.boundary === "milestone" && gitVerdict !== "commit-failed") {
+        const isolation = deps.isolationMode(request.basePath);
+        if (isolation !== "none") {
+            const branch = deps.currentBranch(request.basePath);
+            if (branch?.startsWith(MILESTONE_BRANCH_PREFIX)) {
+                gitVerdict = "milestone-branch";
+                notice =
+                    `Milestone ${request.unitId} completed on ${branch}. ` +
+                        `Merge it to the integration branch with the worktree tooling (/gsd worktree merge).`;
+                deps.notify(notice, "info");
+            }
+            else {
+                gitVerdict = "isolation-bypassed";
+                notice =
+                    `Needs attention: milestone ${request.unitId} completed outside a milestone worktree/branch ` +
+                        `while git.isolation is "${isolation}" — the isolation preference was not honoured this session. ` +
+                        (commitMessage
+                            ? `Work was committed directly on "${branch ?? "the current branch"}".`
+                            : `The working tree had nothing left to commit on "${branch ?? "the current branch"}".`);
+                logWarning("engine", notice);
+                deps.notify(notice, "warning");
+            }
+        }
+    }
+    return { gitVerdict, commitMessage, notice };
+}
+// ─── Interactive Closeout adapter (tool-observation trigger) ─────────────
+// Canonical closeout tool → boundary. Aliases are canonicalized by the hook.
+// Only the milestone boundary is wired interactively: it is the durability gap
+// that motivated ADR-032, and committing at every task/slice would sweep a
+// developer's unrelated working-tree changes. `closeUnit` still handles every
+// boundary for the pending Auto Closeout adapter re-seat.
+const CLOSEOUT_TOOL_BOUNDARIES = {
+    gsd_complete_milestone: "milestone",
+};
+// Commit attribution uses the canonical unit types so interactive closeout
+// commits carry the same GSD-Unit evidence trailers the verification prompts
+// look for.
+const BOUNDARY_UNIT_TYPES = {
+    task: "execute-task",
+    slice: "complete-slice",
+    milestone: "complete-milestone",
+};
+export function isUnitCloseoutTool(canonicalToolName) {
+    return canonicalToolName in CLOSEOUT_TOOL_BOUNDARIES;
+}
+function readId(input, camel, snake) {
+    const value = readStringField(input, camel, snake);
+    return value && value.length > 0 ? value : undefined;
+}
+/**
+ * Interactive Closeout adapter entry, called from the host's tool-observation
+ * hook for successful closeout tool calls when auto-mode is NOT active.
+ * Returns null when the tool input doesn't identify a unit.
+ */
+export function runInteractiveUnitCloseout(args, deps = defaultDeps) {
+    const boundary = CLOSEOUT_TOOL_BOUNDARIES[args.canonicalToolName];
+    if (!boundary)
+        return null;
+    const milestoneId = readId(args.input, "milestoneId", "milestone_id");
+    if (!milestoneId)
+        return null;
+    const sliceId = readId(args.input, "sliceId", "slice_id");
+    const taskId = readId(args.input, "taskId", "task_id");
+    let unitId = milestoneId;
+    if (boundary !== "milestone") {
+        if (!sliceId)
+            return null;
+        unitId = boundary === "slice" ? `${milestoneId}/${sliceId}` : `${milestoneId}/${sliceId}/${taskId ?? ""}`;
+        if (boundary === "task" && !taskId)
+            return null;
+    }
+    return closeUnit({
+        basePath: args.basePath,
+        unitType: BOUNDARY_UNIT_TYPES[boundary],
+        unitId,
+        boundary,
+        outcome: "complete",
+    }, deps);
+}

package/dist/resources/extensions/gsd/unit-context-composer.js

@@ -91,6 +91,14 @@ const CONTEXT_MODE_GUIDANCE_BY_LANE = {
     orchestration: "Use `gsd_resume` before resuming orchestration, `gsd_exec_search` to reuse prior runs, and `gsd_exec` for noisy coordination checks.",
     docs: "Use `gsd_resume` for prior context, `gsd_exec_search` for saved evidence, and `gsd_exec` for noisy doc validation commands.",
 };
+// Per-unit overrides win over the lane default. run-uat's tool contract
+// forbids `gsd_exec`/`gsd_exec_search` (acceptance evidence must flow through
+// `gsd_uat_exec`) and Claude Code dispatch strips the tools entirely, so the
+// shared verification-lane guidance would steer the agent into calling an
+// unavailable tool.
+const CONTEXT_MODE_GUIDANCE_BY_UNIT = {
+    "run-uat": "Use `gsd_uat_exec` for acceptance checks so evidence is typed as UAT-owned, and `gsd_resume` after compaction or resume.",
+};
 /**
  * Render the Context Mode instruction lane for a unit type. Unknown unit
  * types, disabled config, and explicit `contextMode: "none"` all omit the
@@ -103,7 +111,7 @@ export function composeContextModeInstructions(unitType, opts) {
     if (!manifest || manifest.contextMode === "none")
         return "";
     const lane = CONTEXT_MODE_LANE_LABELS[manifest.contextMode];
-    const guidance = CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
+    const guidance = CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType] ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
     if (opts.renderMode === "nested") {
         return `Context Mode (${lane} lane): ${guidance}`;
     }

package/dist/resources/extensions/gsd/unit-context-manifest.js

@@ -118,33 +118,10 @@ const TOOLS_DOCS = {
  * enumerates these against `UNIT_MANIFESTS` to catch manifest drift when
  * a new unit type lands.
  */
-export const KNOWN_UNIT_TYPES = [
-    "research-milestone",
-    "plan-milestone",
-    "discuss-milestone",
-    "validate-milestone",
-    "complete-milestone",
-    "research-slice",
-    "plan-slice",
-    "refine-slice",
-    "replan-slice",
-    "complete-slice",
-    "reassess-roadmap",
-    "execute-task",
-    "reactive-execute",
-    "run-uat",
-    "gate-evaluate",
-    "rewrite-docs",
-    // Sidecar units (triage, quick-task)
-    "triage-captures",
-    "quick-task",
-    // Deep planning mode (project-level) units
-    "workflow-preferences",
-    "discuss-project",
-    "discuss-requirements",
-    "research-decision",
-    "research-project",
-];
+// Unit-type vocabulary is owned by the Unit Registry (ADR-033); re-exported
+// here so established import paths keep working.
+import { KNOWN_UNIT_TYPES } from "./unit-registry.js";
+export { KNOWN_UNIT_TYPES };
 export const UNIT_MANIFESTS = {
     // ─── Milestone-scoped ────────────────────────────────────────────────
     "research-milestone": {

package/dist/resources/extensions/gsd/unit-registry.js

@@ -0,0 +1,350 @@
+// Project/App: gsd-pi
+// File Purpose: Unit Registry — the single declaration point for what a Unit type is (ADR-033).
+//
+// One Unit Descriptor per Unit type. The previously independent tables —
+// `KNOWN_UNIT_TYPES`/`UnitType` (unit-context-manifest.ts), `UNIT_TOOL_CONTRACTS`
+// (unit-tool-contracts.ts), the scope-class Sets (auto-unit-tool-scope.ts), and
+// the unit→phase switch (preferences-models.ts) — are derived views over this
+// registry. Import paths stay stable: each former home re-exports its view
+// (the `gsd-db.ts` barrel discipline).
+//
+// Behaviour-neutral by construction. The registry preserves the asymmetries the
+// old tables had drifted into, explicitly instead of accidentally:
+//   - `discuss-slice` and `execute-task-simple` had tool contracts and scope-Set
+//     membership but were absent from `KNOWN_UNIT_TYPES` → declared here as
+//     `kind: "variant"` (excluded from the derived `KNOWN_UNIT_TYPES`/`UnitType`).
+//   - `triage-captures` and `quick-task` had manifests but no tool contract and
+//     no phase routing → `toolContract: null`, `phaseChain: null`.
+// The parity test (tests/unit-registry.test.ts) pins every derived view to the
+// pre-registry values.
+//
+// Not yet declared here (remaining ADR-033 steps): the manifest data
+// (`UNIT_MANIFESTS` stays in unit-context-manifest.ts, already type-enforced
+// against the registry's `UnitType`) and prompt-template association (still
+// implicit in auto-prompts.ts builders).
+// ─── Shared tool-name constants (used by registry rows) ──────────────────
+export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
+    "gsd_uat_exec",
+    "gsd_uat_result_save",
+    "gsd_resume",
+    "gsd_milestone_status",
+    "gsd_journal_query",
+];
+export const RUN_UAT_READ_ONLY_TOOL_NAMES = [
+    "find",
+    "glob",
+    "grep",
+    "ls",
+    "read",
+];
+export const RUN_UAT_BROWSER_TOOL_NAMES = [
+    "browser_navigate",
+    "browser_click",
+    "browser_type",
+    "browser_fill_form",
+    "browser_click_ref",
+    "browser_fill_ref",
+    "browser_wait_for",
+    "browser_assert",
+    "browser_verify",
+    "browser_screenshot",
+    "browser_snapshot_refs",
+    "browser_find",
+    "browser_get_console_logs",
+    "browser_get_network_logs",
+    "browser_evaluate",
+    "browser_reload",
+    "browser_batch",
+    "browser_act",
+];
+// ─── The registry ─────────────────────────────────────────────────────────
+export const UNIT_REGISTRY = {
+    "research-milestone": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["research"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_summary_save"],
+        },
+    },
+    "plan-milestone": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["planning"],
+        toolContract: {
+            allowedGsdTools: [
+                "gsd_milestone_status",
+                "gsd_plan_milestone",
+                "gsd_plan_slice",
+                "gsd_decision_save",
+                "gsd_requirement_update",
+            ],
+            requiredWorkflowTools: ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice"],
+        },
+    },
+    "discuss-milestone": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["discuss", "planning"],
+        toolContract: {
+            allowedGsdTools: [
+                "gsd_summary_save",
+                "gsd_decision_save",
+                "gsd_requirement_save",
+                "gsd_requirement_update",
+                "gsd_plan_milestone",
+                "gsd_milestone_generate_id",
+            ],
+            requiredWorkflowTools: [
+                "ask_user_questions",
+                "gsd_summary_save",
+                "gsd_requirement_save",
+                "gsd_requirement_update",
+                "gsd_plan_milestone",
+                "gsd_milestone_generate_id",
+            ],
+        },
+    },
+    "discuss-slice": {
+        kind: "variant",
+        scopeClass: "standard",
+        phaseChain: ["discuss", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+            requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
+        },
+    },
+    "validate-milestone": {
+        kind: "primary",
+        scopeClass: "section-close",
+        phaseChain: ["validation", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
+            requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
+        },
+    },
+    "complete-milestone": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["completion"],
+        toolContract: {
+            allowedGsdTools: [
+                "gsd_milestone_status",
+                "gsd_requirement_update",
+                "gsd_summary_save",
+                "gsd_complete_milestone",
+                "subagent",
+            ],
+            requiredWorkflowTools: [
+                "gsd_milestone_status",
+                "gsd_requirement_update",
+                "gsd_summary_save",
+                "gsd_complete_milestone",
+            ],
+        },
+    },
+    "research-slice": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["research"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_summary_save"],
+        },
+    },
+    "plan-slice": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_plan_slice", "gsd_reassess_roadmap", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_plan_slice", "gsd_reassess_roadmap"],
+        },
+    },
+    "refine-slice": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_plan_slice", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_plan_slice"],
+        },
+    },
+    "replan-slice": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_replan_slice", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_replan_slice"],
+        },
+    },
+    "complete-slice": {
+        kind: "primary",
+        scopeClass: "section-close",
+        phaseChain: ["completion"],
+        toolContract: {
+            allowedGsdTools: [
+                "gsd_slice_complete",
+                "gsd_task_reopen",
+                "gsd_replan_slice",
+                "gsd_decision_save",
+                "gsd_requirement_update",
+                "gsd_summary_save",
+                "subagent",
+            ],
+            requiredWorkflowTools: [
+                "gsd_slice_complete",
+                "gsd_task_reopen",
+                "gsd_replan_slice",
+                "gsd_requirement_update",
+                "gsd_summary_save",
+            ],
+            forbiddenGsdTools: {
+                gsd_uat_result_save: "Run UAT owns persisted UAT Assessment.",
+            },
+        },
+    },
+    "reassess-roadmap": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["validation", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
+            requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
+        },
+    },
+    "execute-task": {
+        kind: "primary",
+        scopeClass: "execute-task",
+        phaseChain: ["execution"],
+        toolContract: {
+            allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_task_complete"],
+        },
+    },
+    "execute-task-simple": {
+        kind: "variant",
+        scopeClass: "execute-task",
+        phaseChain: ["execution_simple", "execution"],
+        toolContract: {
+            allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_task_complete"],
+        },
+    },
+    "reactive-execute": {
+        kind: "primary",
+        scopeClass: "execute-task",
+        phaseChain: ["execution"],
+        toolContract: {
+            allowedGsdTools: ["gsd_task_complete", "gsd_summary_save", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_task_complete", "gsd_summary_save"],
+        },
+    },
+    "run-uat": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["uat", "completion"],
+        toolContract: {
+            allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],
+            requiredWorkflowTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES],
+            forbiddenGsdTools: {
+                gsd_exec: "Use gsd_uat_exec so acceptance evidence is typed as UAT-owned.",
+                gsd_save_gate_result: "gsd_uat_result_save owns the aggregate UAT gate.",
+                gsd_summary_save: "gsd_uat_result_save owns persisted UAT Assessment writes.",
+            },
+        },
+    },
+    "gate-evaluate": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["validation", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_save_gate_result"],
+            requiredWorkflowTools: ["gsd_save_gate_result"],
+        },
+    },
+    "rewrite-docs": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["validation", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+            requiredWorkflowTools: [],
+        },
+    },
+    // Sidecar units (triage, quick-task) — manifests exist, but no scoped tool
+    // contract and no phase routing (today's behaviour, preserved explicitly).
+    "triage-captures": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: null,
+        toolContract: null,
+    },
+    "quick-task": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: null,
+        toolContract: null,
+    },
+    // Deep planning mode (project-level) units
+    "workflow-preferences": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["discuss", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save"],
+            requiredWorkflowTools: [],
+        },
+    },
+    "discuss-project": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["discuss", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
+            requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
+        },
+    },
+    "discuss-requirements": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["discuss", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_requirement_save", "gsd_summary_save"],
+            requiredWorkflowTools: ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"],
+        },
+    },
+    "research-decision": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["discuss", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save"],
+            requiredWorkflowTools: ["ask_user_questions"],
+        },
+    },
+    "research-project": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["research"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+            requiredWorkflowTools: [],
+        },
+    },
+};
+const ALL_UNIT_KEYS = Object.keys(UNIT_REGISTRY);
+export const KNOWN_UNIT_TYPES = Object.freeze(ALL_UNIT_KEYS.filter((t) => UNIT_REGISTRY[t].kind === "primary"));
+export const EXECUTE_TASK_UNIT_TYPES = new Set(ALL_UNIT_KEYS.filter((t) => UNIT_REGISTRY[t].scopeClass === "execute-task"));
+// Execute-task units close gates via summary sections too, so the section-close
+// gate Set is every non-"standard" scope class.
+export const SECTION_CLOSE_GATE_UNIT_TYPES = new Set(ALL_UNIT_KEYS.filter((t) => UNIT_REGISTRY[t].scopeClass !== "standard"));
+export function getUnitDescriptor(unitType) {
+    return UNIT_REGISTRY[unitType];
+}
+/** Phase-bucket fallback chain for a unit type, or null when the registry has no routing for it. */
+export function getUnitPhaseChain(unitType) {
+    return getUnitDescriptor(unitType)?.phaseChain ?? null;
+}