@opengsd/gsd-pi 1.4.0 → 1.5.0

package/src/resources/extensions/gsd/tools/plan-task.ts

@@ -12,6 +12,7 @@ import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { validatePathOnlyPlanningFields, validatePlanningPathScope } from "../planning-path-scope.js";
+import { createRepositoryRegistryFromPreferences, defaultRepositoryTargets, type RepositoryRegistry } from "../repository-registry.js";
 import type { GateId } from "../types.js";
 
 export interface PlanTaskParams {
@@ -26,6 +27,8 @@ export interface PlanTaskParams {
   inputs: string[];
   expectedOutput: string[];
   observabilityImpact?: string;
+  /** Repository id(s) this task touches (parent workspace); omitted for single-repo projects. */
+  targetRepositories?: string[];
   fullPlanMd?: string;
   /** Optional caller-provided identity for audit trail */
   actorName?: string;
@@ -40,6 +43,63 @@ export interface PlanTaskResult {
   taskPlanPath: string;
 }
 
+function validateRepositoryTargetIds(field: string, value: unknown): string[] {
+  const ids = validateStringArray(value, field);
+  if (ids.length === 0) throw new Error(`${field} must include at least one repository id when provided`);
+  const deduped = Array.from(new Set(ids.map((id) => id.trim()).filter(Boolean)));
+  if (deduped.length === 0) throw new Error(`${field} must include at least one repository id when provided`);
+  return deduped;
+}
+
+function validateReferencedRepositories(
+  targetRepositories: string[] | undefined,
+  registry: RepositoryRegistry,
+): string | null {
+  if (!targetRepositories) return null;
+  const known = new Set(registry.repositories.map((repo) => repo.id));
+  const missing = targetRepositories.filter((id) => !known.has(id));
+  if (missing.length === 0) return null;
+  return `unknown targetRepositories: ${missing.join(", ")}. Declared repositories: ${Array.from(known).join(", ")}`;
+}
+
+function resolveAllowedRootsForPathScope(
+  targetRepositories: string[],
+  registry: RepositoryRegistry,
+): string[] {
+  if (targetRepositories.length === 0) return [registry.projectRoot];
+  const roots = targetRepositories
+    .map((id) => registry.byId.get(id)?.root)
+    .filter((root): root is string => typeof root === "string");
+  return roots.length > 0 ? roots : [registry.projectRoot];
+}
+
+function validatePathScopeForTargetRepositories(
+  params: PlanTaskParams,
+  basePath: string,
+  registry: RepositoryRegistry,
+  targetRepositories: string[],
+): string | null {
+  return validatePlanningPathScope(
+    basePath,
+    [
+      { field: "files", values: params.files },
+      { field: "inputs", values: params.inputs },
+      { field: "expectedOutput", values: params.expectedOutput },
+    ],
+    resolveAllowedRootsForPathScope(targetRepositories, registry),
+  );
+}
+
+function resolveEffectiveTargetRepositories(
+  taskTargetRepositories: string[] | undefined,
+  sliceTargetRepositories: string[] | undefined,
+  defaultTargets: string[],
+): string[] {
+  if (taskTargetRepositories) return taskTargetRepositories;
+  if (sliceTargetRepositories?.length) return sliceTargetRepositories;
+  return defaultTargets;
+}
+
 function validateParams(params: PlanTaskParams): PlanTaskParams {
   if (!isNonEmptyString(params?.milestoneId)) throw new Error("milestoneId is required");
   if (!isNonEmptyString(params?.sliceId)) throw new Error("sliceId is required");
@@ -57,6 +117,9 @@ function validateParams(params: PlanTaskParams): PlanTaskParams {
     files: validateStringArray(params.files, "files"),
     inputs: validateStringArray(params.inputs, "inputs"),
     expectedOutput: validateStringArray(params.expectedOutput, "expectedOutput"),
+    ...(params.targetRepositories !== undefined
+      ? { targetRepositories: validateRepositoryTargetIds("targetRepositories", params.targetRepositories) }
+      : {}),
   };
 }
 
@@ -84,23 +147,19 @@ export async function handlePlanTask(
     return { error: `validation failed: ${pathOnlyError}` };
   }
 
-  const pathScopeError = validatePlanningPathScope(basePath, [
-    { field: "files", values: params.files },
-    { field: "inputs", values: params.inputs },
-    { field: "expectedOutput", values: params.expectedOutput },
-  ]);
-  if (pathScopeError) {
-    return { error: `validation failed: ${pathScopeError}` };
-  }
-
   let taskGates: GateId[];
+  let repositoryRegistry: RepositoryRegistry;
   try {
     taskGates = resolveTaskGates(basePath);
+    const loaded = loadEffectiveGSDPreferences(basePath);
+    repositoryRegistry = createRepositoryRegistryFromPreferences(basePath, loaded?.preferences);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return { error: `validation failed: ${message}` };
   }
 
+  const defaultTargets = defaultRepositoryTargets(repositoryRegistry);
+
   // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   // Guards must be inside the transaction so the state they check cannot
   // change between the read and the write (#2723).
@@ -124,6 +183,44 @@ export async function handlePlanTask(
         return;
       }
 
+      let effectiveTargetRepositories = resolveEffectiveTargetRepositories(
+        params.targetRepositories,
+        parentSlice.target_repositories,
+        defaultTargets,
+      );
+      const repoValidationError = validateReferencedRepositories(effectiveTargetRepositories, repositoryRegistry);
+      if (repoValidationError) {
+        guardError = `validation failed: ${repoValidationError}`;
+        return;
+      }
+
+      let pathScopeError = validatePathScopeForTargetRepositories(
+        params,
+        basePath,
+        repositoryRegistry,
+        effectiveTargetRepositories,
+      );
+      const storedTaskTargets = existingTask?.target_repositories?.length
+        ? existingTask.target_repositories
+        : undefined;
+      // Omitted targetRepositories inherit the current slice default first.
+      // Fall back to the stored task target only when that inherited scope
+      // rejects the replan paths, preserving explicit per-task parent-root work.
+      if (pathScopeError && params.targetRepositories === undefined && storedTaskTargets) {
+        const storedRepoValidationError = validateReferencedRepositories(storedTaskTargets, repositoryRegistry);
+        const storedPathScopeError = storedRepoValidationError
+          ? storedRepoValidationError
+          : validatePathScopeForTargetRepositories(params, basePath, repositoryRegistry, storedTaskTargets);
+        if (!storedPathScopeError) {
+          effectiveTargetRepositories = storedTaskTargets;
+          pathScopeError = null;
+        }
+      }
+      if (pathScopeError) {
+        guardError = `validation failed: ${pathScopeError}`;
+        return;
+      }
+
       if (!existingTask) {
         insertTask({
           id: params.taskId,
@@ -143,6 +240,7 @@ export async function handlePlanTask(
         expectedOutput: params.expectedOutput,
         observabilityImpact: params.observabilityImpact ?? "",
         fullPlanMd: params.fullPlanMd,
+        targetRepositories: effectiveTargetRepositories,
       });
       for (const gid of taskGates) {
         insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: gid, scope: "task", taskId: params.taskId });

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -53,11 +53,13 @@ import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { parseProject } from "../schemas/parsers.js";
 import { autoSession, getAutoRuntimeSnapshot, isAutoActive } from "../auto-runtime-state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
+import { readUnitHarnessAbort, type UnitHarnessAbortRecord } from "../unit-runtime.js";
 import {
   prepareUatRun,
   saveUatAttemptArtifact,
   type UatResultSaveParams,
 } from "../uat-run.js";
+import { appendNotification } from "../notification-store.js";
 import { registerAutoWorker, markWorkerStopping, getAutoWorker } from "../db/auto-workers.js";
 import {
   claimMilestoneLease,
@@ -116,6 +118,48 @@ function blockIfWrongAutoUnit(requiredUnitType: string, operation: string): Tool
   };
 }
 
+function blockIfHarnessAbortedUnit(operation: string, basePath: string): ToolExecutionResult | null {
+  const snapshot = getAutoRuntimeSnapshot();
+  if (!snapshot.active || !snapshot.currentUnit) return null;
+
+  const abort = readUnitHarnessAbort(
+    snapshot.basePath || basePath,
+    snapshot.currentUnit.type,
+    snapshot.currentUnit.id,
+    snapshot.currentUnit.startedAt,
+  );
+  if (!abort) return null;
+
+  return harnessAbortResult(operation, snapshot.currentUnit.type, snapshot.currentUnit.id, abort);
+}
+
+function harnessAbortResult(
+  operation: string,
+  unitType: string,
+  unitId: string,
+  abort: UnitHarnessAbortRecord,
+): ToolExecutionResult {
+  const toolText = abort.toolName ? ` while calling ${abort.toolName}` : "";
+  const message =
+    `Retryable harness abort: ${unitType} ${unitId} was truncated by ${abort.kind}${toolText}. ` +
+    "This gate result was not saved; leave the gate pending so auto-mode can rerun it.";
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      operation,
+      error: "harness_aborted_needs_retry",
+      retryable: true,
+      unitType,
+      unitId,
+      harnessAbortKind: abort.kind,
+      harnessAbortReason: abort.reason,
+      harnessAbortToolName: abort.toolName,
+      harnessAbortCount: abort.count,
+    },
+    isError: true,
+  };
+}
+
 function milestoneLeaseConflictResult(
   milestoneId: string,
   byWorker: string,
@@ -1135,6 +1179,9 @@ export async function executeSaveGateResult(
   params: SaveGateResultParams,
   basePath: string = process.cwd(),
 ): Promise<ToolExecutionResult> {
+  const harnessAbort = blockIfHarnessAbortedUnit("save_gate_result", basePath);
+  if (harnessAbort) return harnessAbort;
+
   const dbAvailable = await ensureDbOpen(basePath);
   if (!dbAvailable) {
     return {
@@ -1206,6 +1253,9 @@ export async function executeUatResultSave(
   const unitGuard = blockIfWrongAutoUnit("run-uat", "save_uat_result");
   if (unitGuard) return unitGuard;
 
+  const harnessAbort = blockIfHarnessAbortedUnit("save_uat_result", basePath);
+  if (harnessAbort) return harnessAbort;
+
   const dbAvailable = await ensureDbOpen(basePath);
   if (!dbAvailable) return errorResult("save_uat_result", "GSD database is not available.", "db_unavailable");
 
@@ -1268,6 +1318,14 @@ export async function executeUatResultSave(
       evaluatedAt: run.evaluatedAt,
     });
     invalidateStateCache();
+    if (run.hasHuman) {
+      appendNotification(
+        `UAT for ${run.params.milestoneId}/${run.params.sliceId} has NEEDS-HUMAN checks awaiting human validation`,
+        "warning",
+        "notify",
+        { kind: "uat-needs-human", scope: `${run.params.milestoneId}/${run.params.sliceId}` },
+      );
+    }
     const savedText = `UAT result saved for ${run.params.milestoneId}/${run.params.sliceId}: ${run.params.verdict}`;
     return {
       content: [{

package/src/resources/extensions/gsd/unit-context-manifest.ts

@@ -140,6 +140,10 @@ export type ContextModePolicy =
  *                    restricted to .gsd/**. Subagent dispatch is denied unless
  *                    `allowedSubagents` opts a unit into controlled read-only
  *                    specialist delegation.
+ *   - "workflow-only"
+ *                  — Read tools + GSD workflow tools only. No generic writes
+ *                    and no generic shell; used by lanes whose durable output
+ *                    must be produced by a dedicated DB-backed workflow tool.
  *
  * The allowlist for "docs" is declared per-manifest rather than hardcoded so
  * projects with non-standard doc layouts can extend it without forking the
@@ -152,7 +156,8 @@ export type ToolsPolicy =
   | { readonly mode: "planning" }
   | { readonly mode: "planning-dispatch"; readonly allowedSubagents: readonly string[] }
   | { readonly mode: "docs"; readonly allowedPathGlobs: readonly string[] }
-  | { readonly mode: "verification"; readonly allowedSubagents?: readonly string[] };
+  | { readonly mode: "verification"; readonly allowedSubagents?: readonly string[] }
+  | { readonly mode: "workflow-only"; readonly allowedSubagents?: readonly string[] };
 
 // ─── Computed-artifact registry (#4924 v2 contract) ───────────────────────
 
@@ -405,9 +410,10 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     codebaseMap: false,
     preferences: "active-only",
     contextMode: "verification",
-    // Validation may need to run shell verification commands and apply source
-    // fixes before milestone closeout can proceed.
-    tools: TOOLS_ALL,
+    // Validation must persist its durable output through gsd_validate_milestone;
+    // generic write/bash tools can create filesystem artifacts that bypass DB
+    // state and trigger destructive recovery loops.
+    tools: { mode: "workflow-only", allowedSubagents: ["reviewer", "security", "tester"] },
     artifacts: {
       inline: ["roadmap", "requirements", "templates"],
       excerpt: ["slice-summary", "slice-assessment"],
@@ -774,7 +780,7 @@ export function compileSubagentPermissionContract(
     return { allowed: true, allowedSubagents: ["*"], toolsMode: policy.mode };
   }
   if (
-    (policy.mode === "planning-dispatch" || policy.mode === "verification") &&
+    (policy.mode === "planning-dispatch" || policy.mode === "verification" || policy.mode === "workflow-only") &&
     Array.isArray(policy.allowedSubagents)
   ) {
     return {

package/src/resources/extensions/gsd/unit-registry.ts

@@ -20,8 +20,9 @@
 //
 // 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).
+// against the registry's `UnitType`). Prompt-template association is declared
+// for direct one-template units; conditional/composite prompt selection stays
+// with the prompt builders until it has a richer registry shape.
 
 import type { CanonicalWorkflowToolName } from "@opengsd/contracts";
 import { BROWSER_CONTRACT_TOOL_NAMES } from "../shared/browser-contract.js";
@@ -61,6 +62,12 @@ export interface UnitDescriptor {
    * resolves against session defaults).
    */
   readonly phaseChain: readonly GSDModelPhaseKey[] | null;
+  /**
+   * Prompt template id passed to loadPrompt for units with a direct
+   * one-template builder. Omitted for conditional, composite, or not-yet
+   * verified prompt associations.
+   */
+  readonly promptTemplate?: string;
   /** `null` = the unit has no scoped gsd-tool contract. */
   readonly toolContract: UnitToolSurfaceContract | null;
 }
@@ -97,6 +104,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["research"],
+    promptTemplate: "research-milestone",
     toolContract: {
       allowedGsdTools: [
         "gsd_summary_save",
@@ -112,6 +120,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["planning"],
+    promptTemplate: "plan-milestone",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -160,6 +169,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "section-close",
     phaseChain: ["validation", "planning"],
+    promptTemplate: "validate-milestone",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -177,6 +187,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["completion"],
+    promptTemplate: "complete-milestone",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -200,6 +211,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["research"],
+    promptTemplate: "research-slice",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -216,6 +228,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["planning"],
+    promptTemplate: "plan-slice",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -234,6 +247,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["planning"],
+    promptTemplate: "refine-slice",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -250,6 +264,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["planning"],
+    promptTemplate: "replan-slice",
     toolContract: {
       allowedGsdTools: ["gsd_replan_slice", "gsd_decision_save"],
       requiredWorkflowTools: ["gsd_replan_slice"],
@@ -259,6 +274,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "section-close",
     phaseChain: ["completion"],
+    promptTemplate: "complete-slice",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -293,6 +309,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["validation", "planning"],
+    promptTemplate: "reassess-roadmap",
     toolContract: {
       allowedGsdTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
       requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
@@ -302,6 +319,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "execute-task",
     phaseChain: ["execution"],
+    promptTemplate: "execute-task",
     toolContract: {
       allowedGsdTools: [
         "gsd_task_complete",
@@ -346,6 +364,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "execute-task",
     phaseChain: ["execution"],
+    promptTemplate: "reactive-execute",
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
@@ -361,6 +380,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["uat", "completion"],
+    promptTemplate: "run-uat",
     toolContract: {
       allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],
       requiredWorkflowTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES],
@@ -375,6 +395,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["validation", "planning"],
+    promptTemplate: "gate-evaluate",
     toolContract: {
       allowedGsdTools: ["gsd_save_gate_result"],
       requiredWorkflowTools: ["gsd_save_gate_result"],
@@ -384,6 +405,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["validation", "planning"],
+    promptTemplate: "rewrite-docs",
     toolContract: {
       allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
       requiredWorkflowTools: [],
@@ -408,6 +430,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["discuss", "planning"],
+    promptTemplate: "guided-workflow-preferences",
     toolContract: {
       allowedGsdTools: ["gsd_summary_save"],
       requiredWorkflowTools: [],
@@ -417,6 +440,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["discuss", "planning"],
+    promptTemplate: "guided-discuss-project",
     toolContract: {
       allowedGsdTools: ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
       requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
@@ -426,6 +450,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["discuss", "planning"],
+    promptTemplate: "guided-discuss-requirements",
     toolContract: {
       allowedGsdTools: ["gsd_requirement_save", "gsd_summary_save"],
       requiredWorkflowTools: ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"],
@@ -435,6 +460,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["discuss", "planning"],
+    promptTemplate: "guided-research-decision",
     toolContract: {
       allowedGsdTools: ["gsd_summary_save"],
       requiredWorkflowTools: ["ask_user_questions"],
@@ -447,6 +473,7 @@ export const UNIT_REGISTRY = {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["research"],
+    promptTemplate: "guided-research-project",
     toolContract: {
       allowedGsdTools: [],
       requiredWorkflowTools: [],
@@ -494,3 +521,8 @@ export function getUnitDescriptor(unitType: string): UnitDescriptor | undefined
 export function getUnitPhaseChain(unitType: string): readonly GSDModelPhaseKey[] | null {
   return getUnitDescriptor(unitType)?.phaseChain ?? null;
 }
+
+/** Prompt template id for units with a direct one-template builder. */
+export function getUnitPromptTemplate(unitType: string): string | undefined {
+  return getUnitDescriptor(unitType)?.promptTemplate;
+}

package/src/resources/extensions/gsd/unit-runtime.ts

@@ -100,6 +100,14 @@ export interface ExecuteTaskRecoveryStatus {
   mustHavesMentionedInSummary: number;
 }
 
+export interface UnitHarnessAbortRecord {
+  kind: "tool-loop-guard" | "tool-error" | "turn-abort";
+  reason: string;
+  toolName?: string;
+  count?: number;
+  recordedAt: number;
+}
+
 export interface AutoUnitRuntimeRecord {
   version: 1;
   unitType: string;
@@ -116,6 +124,7 @@ export interface AutoUnitRuntimeRecord {
   recovery?: ExecuteTaskRecoveryStatus;
   recoveryAttempts?: number;
   lastRecoveryReason?: "idle" | "hard";
+  harnessAbort?: UnitHarnessAbortRecord;
 }
 
 function runtimeDir(basePath: string): string {
@@ -138,6 +147,8 @@ export function writeUnitRuntimeRecord(
   const path = runtimePath(basePath, unitType, unitId);
   return withRecordLock(path, () => {
     const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
+    const sameRun = prev?.startedAt === startedAt;
+    const updatesHarnessAbort = Object.prototype.hasOwnProperty.call(updates, "harnessAbort");
     const next: AutoUnitRuntimeRecord = {
       version: 1,
       unitType,
@@ -154,12 +165,32 @@ export function writeUnitRuntimeRecord(
       recovery: updates.recovery ?? prev?.recovery,
       recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
       lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
+      harnessAbort: updatesHarnessAbort
+        ? updates.harnessAbort
+        : (sameRun ? prev?.harnessAbort : undefined),
     };
     atomicWriteSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
     return next;
   });
 }
 
+export function recordUnitHarnessAbort(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  startedAt: number,
+  abort: Omit<UnitHarnessAbortRecord, "recordedAt"> & { recordedAt?: number },
+): AutoUnitRuntimeRecord {
+  return writeUnitRuntimeRecord(basePath, unitType, unitId, startedAt, {
+    harnessAbort: {
+      ...abort,
+      recordedAt: abort.recordedAt ?? Date.now(),
+    },
+    lastProgressAt: Date.now(),
+    lastProgressKind: `harness-abort:${abort.kind}`,
+  });
+}
+
 export function readUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): AutoUnitRuntimeRecord | null {
   const path = runtimePath(basePath, unitType, unitId);
   if (!existsSync(path)) return null;
@@ -170,6 +201,17 @@ export function readUnitRuntimeRecord(basePath: string, unitType: string, unitId
   }
 }
 
+export function readUnitHarnessAbort(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  startedAt: number,
+): UnitHarnessAbortRecord | null {
+  const record = readUnitRuntimeRecord(basePath, unitType, unitId);
+  if (!record || record.startedAt !== startedAt) return null;
+  return record.harnessAbort ?? null;
+}
+
 export function clearUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): void {
   const path = runtimePath(basePath, unitType, unitId);
   if (existsSync(path)) unlinkSync(path);

package/src/resources/extensions/gsd/workspace.ts

@@ -1,7 +1,17 @@
 // gsd-pi + Workspace handle: single source of truth for path resolution per milestone
 
-import { join, resolve } from "node:path";
-import { type GsdPathContract, resolveGsdPathContract, normalizeRealPath } from "./paths.js";
+import { dirname, join, resolve } from "node:path";
+import {
+  buildMilestoneFileName,
+  canonicalPhaseDirName,
+  isLegacyMilestonesLayout,
+  milestonesDir,
+  type GsdPathContract,
+  resolveGsdPathContract,
+  resolveMilestoneFile,
+  resolveMilestonePath,
+  normalizeRealPath,
+} from "./paths.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 
 export type GsdWorkspaceMode = "project" | "worktree";
@@ -31,6 +41,29 @@ function tryRealpath(p: string): string {
   return normalizeRealPath(p);
 }
 
+function isLegacyMilestoneDirectory(dir: string): boolean {
+  const parent = dirname(dir);
+  return parent.endsWith("/milestones") || parent.endsWith("\\milestones");
+}
+
+function scopeMilestoneDir(basePath: string, milestoneId: string): string {
+  return resolveMilestonePath(basePath, milestoneId) ?? join(
+    milestonesDir(basePath),
+    isLegacyMilestonesLayout(basePath) ? milestoneId : canonicalPhaseDirName(milestoneId),
+  );
+}
+
+function scopeMilestoneFile(basePath: string, milestoneId: string, suffix: string): string {
+  const existing = resolveMilestoneFile(basePath, milestoneId, suffix);
+  if (existing) return existing;
+
+  const dir = scopeMilestoneDir(basePath, milestoneId);
+  const filename = isLegacyMilestoneDirectory(dir)
+    ? `${milestoneId}-${suffix}.md`
+    : buildMilestoneFileName(milestoneId, suffix);
+  return join(dir, filename);
+}
+
 /**
  * Create an immutable GsdWorkspace handle from a raw base path.
  * Resolves both the project root and (when applicable) the worktree root,
@@ -73,22 +106,23 @@ export function createWorkspace(rawBasePath: string): GsdWorkspace {
  * Bind a milestoneId to a workspace, producing an immutable MilestoneScope
  * with path-returning closures for DB-authoritative project state.
  *
- * These scope paths intentionally route to contract.projectGsd. In-flight
- * markdown artifact readers outside this scope use the projection-aware
- * resolvers in paths.ts so worktree units can see worktree-local projections.
+ * DB paths route to contract.projectGsd. Milestone artifact paths resolve from
+ * the pinned project root with the layout-aware resolvers, so flat-phase and
+ * legacy projects use the same scope surface.
  */
 export function scopeMilestone(workspace: GsdWorkspace, milestoneId: string): MilestoneScope {
   const { contract } = workspace;
   const gsd = contract.projectGsd;
+  const basePath = workspace.projectRoot;
 
   const scope: MilestoneScope = Object.freeze({
     workspace,
     milestoneId,
-    contextFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-CONTEXT.md`),
-    roadmapFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-ROADMAP.md`),
+    contextFile: () => scopeMilestoneFile(basePath, milestoneId, "CONTEXT"),
+    roadmapFile: () => scopeMilestoneFile(basePath, milestoneId, "ROADMAP"),
     stateFile: () => join(gsd, "STATE.md"),
     dbPath: () => contract.projectDb,
-    milestoneDir: () => join(gsd, "milestones", milestoneId),
+    milestoneDir: () => scopeMilestoneDir(basePath, milestoneId),
     metaJson: () => join(gsd, `${milestoneId}-META.json`),
   });