@opengsd/gsd-core 1.11.0 → 1.13.0

package/gsd-core/bin/lib/init.cjs

@@ -34,6 +34,9 @@ const phaseId = require("./phase-id.cjs");
 const worktreeSafety = require("./worktree-safety.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
 const planningWorkspace = require("./planning-workspace.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
 const secrets_cjs_1 = require("./secrets.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- plan-scan.cjs is an export= CommonJS module
 const scanPhasePlans = require("./plan-scan.cjs");
@@ -74,13 +77,16 @@ const resolution_cjs_1 = require("./resolution.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- onboard-projection.cjs is an export= CommonJS module
 const onboardProjection = require("./onboard-projection.cjs");
 const { REQUIRED_CODEBASE_MAP_FILES, buildOnboardProjection, hasCodeFilesInternal, hasPackageFileInternal, listCodebaseMapFiles, } = onboardProjection;
-const { output, error, ERROR_REASON } = io;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- verify-command-grounding.cjs is an export= CommonJS module
+const verifyCommandGrounding = require("./verify-command-grounding.cjs");
+const { harvestPriorVerifyCommands } = verifyCommandGrounding;
+const { output, error, ERROR_REASON, formatDiagnosticToken } = io;
 const { loadConfig, loadConfigResolved } = configLoader;
 const { resolveModelInternal, resolveGranularityInternal, assertValidGranularityOverride } = modelResolver;
-const { findPhaseInternal, listMilestonePhaseDirs } = phaseLocator;
+const { findPhaseInternal, listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocator;
 const { getRoadmapPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, } = roadmapParser;
 const { pathExistsInternal, generateSlugInternal, toPosixPath } = coreUtils;
-const { normalizePhaseName, matchPhaseDirs, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, isForeignPrefixedPhaseQuery, isSentinelPhaseId, extractPhaseToken, scopeToPhase } = phaseId;
+const { comparePhaseNum, normalizePhaseName, matchPhaseDirs, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, isForeignPrefixedPhaseQuery, isSentinelPhaseId, extractPhaseToken, scopeToPhase } = phaseId;
 const { pruneOrphanedWorktrees } = worktreeSafety;
 const { planningPaths, planningDir, planningRoot, listAvailableWorkstreams, peekActiveWorkstream, diagnoseUnresolvedActiveWorkstream, describeUnresolvedWorkstreamReason, findContextMdIn, } = planningWorkspace;
 const { determinePhaseStatus } = commandsMod;
@@ -129,9 +135,12 @@ function guardedGetRoadmapPhase(cwd, phase, projectCode) {
 // directory exists yet) identically at every synthetic-fallback call site
 // below — factored out once so the slugification formula itself cannot drift.
 function slugifyPhaseName(phaseName) {
-    return phaseName
-        ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
-        : null;
+    // #3883 (ADR-3473 §8.3): delegate to the canonical slug formula
+    // (generateSlugInternal, core-utils.cts) rather than re-implementing it.
+    // `maxLen: null` preserves this site's pre-migration untruncated contract —
+    // the 60-char default would collapse two distinct >60-char phase names onto
+    // the same reported phase_slug.
+    return phaseName ? coreUtils.generateSlugInternal(phaseName, null) : null;
 }
 /**
  * #2994 (review finding, DEFECT.GENERATIVE-FIX): shared archived/not-found
@@ -765,7 +774,6 @@ function cmdInitExecutePhase(cwd, phase, raw, options = {}) {
         ? reqMatch[1].replace(/[\[\]]/g, '').split(',').map((s) => s.trim()).filter(Boolean).join(', ')
         : null;
     const phase_req_ids = reqExtracted && reqExtracted !== 'TBD' ? reqExtracted : null;
-    const wf = (config.workflow ?? {});
     // #3188: these paths are null when the file is absent, matching the contract
     // the conditional sibling fields (context_path, patterns_path, ...) already
     // honour and that ultraplan-phase.md / execute-phase.md gate on. Hoisted so
@@ -776,7 +784,7 @@ function cmdInitExecutePhase(cwd, phase, raw, options = {}) {
     const result = {
         executor_model: resolveModelInternal(cwd, 'gsd-executor'),
         verifier_model: resolveModelInternal(cwd, 'gsd-verifier'),
-        tdd_mode: options['tdd'] || Boolean(wf['tdd_mode']) || false,
+        tdd_mode: options['tdd'] || Boolean(config.tdd_mode) || false,
         commit_docs: config.commit_docs,
         sub_repos: config.sub_repos,
         parallelization: config.parallelization,
@@ -918,7 +926,6 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
     const granularityOverride = options['granularity'];
     assertValidGranularityOverride(granularityOverride, error);
     const granularity = resolveGranularityInternal(cwd, 'planning', granularityOverride || undefined);
-    const wf = (config.workflow ?? {});
     // #3188: see cmdInitExecutePhase — null when absent, parity with the
     // conditional sibling fields in this same result object.
     const statePath = node_path_1.default.join(planningDir(cwd), 'STATE.md');
@@ -928,11 +935,11 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
         researcher_model: resolveModelInternal(cwd, 'gsd-phase-researcher'),
         planner_model: resolveModelInternal(cwd, 'gsd-planner'),
         checker_model: resolveModelInternal(cwd, 'gsd-plan-checker'),
-        tdd_mode: options['tdd'] || Boolean(wf['tdd_mode']) || false,
+        tdd_mode: options['tdd'] || Boolean(config.tdd_mode) || false,
         granularity,
-        research_enabled: wf['research'],
+        research_enabled: config.research,
         plan_checker_enabled: config.plan_checker,
-        nyquist_validation_enabled: wf['nyquist_validation'],
+        nyquist_validation_enabled: config.nyquist_validation,
         commit_docs: config.commit_docs,
         text_mode: config.text_mode,
         auto_advance: !!(config.auto_advance),
@@ -954,6 +961,11 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
             : 'Pending',
         has_research: phaseInfo?.['has_research'] || false,
         has_context: phaseInfo?.['has_context'] || false,
+        // #4014 (epic #3473 B4-unreadable): additive scope signal adjacent to
+        // has_context — SCOPE.COMPLETE by default (no phase directory to read is
+        // a genuine, not-unreadable answer), overwritten below to whatever
+        // findContextMdIn(phaseDirFull) reports once a directory is known.
+        context_scope: SCOPE.COMPLETE,
         has_reviews: phaseInfo?.['has_reviews'] || false,
         has_plans: (phaseInfo?.['plans']?.length || 0) > 0,
         plan_count: phaseInfo?.['plans']?.length || 0,
@@ -968,6 +980,13 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
     };
     if (phaseInfo?.['directory']) {
         const phaseDirFull = node_path_1.default.join(cwd, phaseInfo['directory']);
+        // #4014 (epic #3473 B4-unreadable): findContextMdIn's directory-string
+        // form never throws, so this can record the real scope BEFORE the
+        // pre-existing `fs.readdirSync(phaseDirFull)` immediately below
+        // (unchanged) throws on the same unreadable directory and is caught
+        // exactly as before — additive only, the failure control-flow for
+        // context_path/research_path/etc. is untouched.
+        result['context_scope'] = findContextMdIn(phaseDirFull).scope;
         try {
             const files = node_fs_1.default.readdirSync(phaseDirFull);
             const phaseDirName = node_path_1.default.basename(phaseDirFull);
@@ -1028,8 +1047,21 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
                 result['patterns_path'] = toPosixPath(node_path_1.default.join(phaseDirFull, patternsFile));
             }
         }
-        catch {
-            /* intentionally empty */
+        catch (err) {
+            // #3885 (ADR-3473 §8.5): this branch means `phaseInfo['directory']` was
+            // set (the phase was already resolved to an on-disk directory) yet
+            // `readdirSync` still failed — ENOENT here would be a genuine race
+            // (the directory vanished between resolution and this read) and stays
+            // a silent degrade like the prior behavior; any other errno
+            // (EACCES/EIO/...) is an unreadable-not-absent directory and must be
+            // named, or every conditional field this block sets (context_path,
+            // research_path, verification_path, uat_path, reviews_path,
+            // patterns_path) silently reads as "none of these exist".
+            const code = err?.code;
+            if (code !== 'ENOENT') {
+                result['context_read_error'] =
+                    `Could not read phase directory ${formatDiagnosticToken(phaseDirFull)}: ${formatDiagnosticToken(err?.message ?? String(err))}`;
+            }
         }
     }
     if (options['validate']) {
@@ -1056,8 +1088,59 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
     }
     // #2992 (Phase 6.1): additive, optional field — degrades to null, never throws.
     result['section_manifest'] = buildSectionManifestField(cwd, phaseInfo, options, 'plan-phase');
+    // #2401: prior-phase verify commands, surfaced UNGATED — additive field, never
+    // conditioned on context_window. Before this, the planner only inherited
+    // prior-phase verify-command context when context_window >= 500000, so at
+    // lower context windows it re-invented (and mis-resolved) the command. The
+    // harvest already degrades to `{commands: [], readError}` rather than
+    // throwing; the try/catch is defense-in-depth so init never breaks on this.
+    let priorVerifyCommands = [];
+    try {
+        // #2401 review fix: harvestPriorVerifyCommands accepts a phase-id token
+        // (string) directly, so a decimal phase like '2.1' is no longer silently
+        // dropped by `Number('2.1')` producing a value the old `number`-only
+        // parameter mishandled for lettered/decimal tokens.
+        if (phaseNumberPlan !== null) {
+            priorVerifyCommands = harvestPriorVerifyCommands({
+                planningDir: planningPaths(cwd).phases,
+                beforePhase: phaseNumberPlan,
+            }).commands;
+        }
+    }
+    catch {
+        priorVerifyCommands = [];
+    }
+    result['prior_verify_commands'] = priorVerifyCommands;
     output(withProjectRoot(cwd, result), raw);
 }
+// #4040: shared partial-init discriminator for the init.progress / init.resume /
+// init.new-project payloads. A bootstrap interrupted before the core quartet
+// (PROJECT.md / REQUIREMENTS.md / ROADMAP.md / STATE.md) all landed is a
+// DISTINCT routing state from "new project" and from "between milestones";
+// pre-#4040 the payloads could not express it, so progress.md mis-routed it to
+// Route F and resume-project.md offered STATE.md reconstruction.
+//
+// Negative-space guard: `milestone.complete` archives ROADMAP.md (and
+// REQUIREMENTS.md) but always leaves MILESTONES.md behind — so MILESTONES.md
+// present proves missing core files are archival (between-milestones), never an
+// unfinished bootstrap. REQUIREMENTS.md is written by new-project BEFORE
+// ROADMAP/STATE, so its absence also proves init never finished.
+function buildInitCompletenessFields(cwd) {
+    const dir = planningDir(cwd);
+    const planningExists = node_fs_1.default.existsSync(dir);
+    const requirementsExists = node_fs_1.default.existsSync(node_path_1.default.join(dir, 'REQUIREMENTS.md'));
+    const milestonesExists = node_fs_1.default.existsSync(node_path_1.default.join(dir, 'MILESTONES.md'));
+    const coreComplete = node_fs_1.default.existsSync(node_path_1.default.join(dir, 'PROJECT.md')) &&
+        requirementsExists &&
+        node_fs_1.default.existsSync(node_path_1.default.join(dir, 'ROADMAP.md')) &&
+        node_fs_1.default.existsSync(node_path_1.default.join(dir, 'STATE.md'));
+    return {
+        planning_exists: planningExists,
+        requirements_exists: requirementsExists,
+        milestones_exists: milestonesExists,
+        init_incomplete: planningExists && !coreComplete && !milestonesExists,
+    };
+}
 function cmdInitNewProject(cwd, raw, options = {}) {
     const config = loadConfig(cwd);
     const homedir = node_os_1.default.homedir();
@@ -1077,7 +1160,12 @@ function cmdInitNewProject(cwd, raw, options = {}) {
         synthesizer_model: resolveModelInternal(cwd, 'gsd-research-synthesizer'),
         roadmapper_model: resolveModelInternal(cwd, 'gsd-roadmapper'),
         commit_docs: config.commit_docs,
-        project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'),
+        // #4040: partial-init discriminator (see buildInitCompletenessFields).
+        // Spread BEFORE this literal's own planning_exists so the existing
+        // root-scoped (`pathExistsInternal(cwd, '.planning')`) semantics for that
+        // one key stay byte-identical for existing consumers.
+        ...buildInitCompletenessFields(cwd),
+        project_exists: pathExistsInternal(cwd, toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'PROJECT.md')))),
         has_codebase_map: hasCodebaseMap,
         planning_exists: pathExistsInternal(cwd, '.planning'),
         has_existing_code: hasCode,
@@ -1116,13 +1204,12 @@ function cmdInitNewMilestone(cwd, raw, options = {}) {
     // owns — routed through it instead of a local readdirSync + hand-rolled
     // window filter (which also never excluded sentinels, unlike the owner).
     const phaseDirCount = listMilestonePhaseDirs(phasesDir, { cwd }).value.length;
-    const wf = (config.workflow ?? {});
     const result = {
         researcher_model: resolveModelInternal(cwd, 'gsd-project-researcher'),
         synthesizer_model: resolveModelInternal(cwd, 'gsd-research-synthesizer'),
         roadmapper_model: resolveModelInternal(cwd, 'gsd-roadmapper'),
         commit_docs: config.commit_docs,
-        research_enabled: wf['research'],
+        research_enabled: config.research,
         // #3216 review Finding 2: `?? null` so an unresolved milestone still emits
         // the key with an explicit `null` rather than letting JSON.stringify drop
         // it — an omitted key reaches the prompt layer's `{current_milestone}`
@@ -1136,7 +1223,7 @@ function cmdInitNewMilestone(cwd, raw, options = {}) {
         phase_archive_path: latestCompleted
             ? toPosixPath(node_path_1.default.join(planningRoot(cwd), 'milestones', `${latestCompleted.version}-phases`))
             : null,
-        project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'),
+        project_exists: pathExistsInternal(cwd, toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'PROJECT.md')))),
         roadmap_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md')),
         state_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'STATE.md')),
         project_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'PROJECT.md')),
@@ -1204,6 +1291,10 @@ function cmdInitQuick(cwd, description, raw, options = {}) {
         executor_model: resolveModelInternal(cwd, 'gsd-executor'),
         checker_model: resolveModelInternal(cwd, 'gsd-plan-checker'),
         verifier_model: resolveModelInternal(cwd, 'gsd-verifier'),
+        // #3936: Step 4.75 dispatches gsd-phase-researcher; resolve its own tier
+        // (parity with cmdInitPlanPhase) so the research spawn stops pinning
+        // planner_model.
+        researcher_model: resolveModelInternal(cwd, 'gsd-phase-researcher'),
         // #2072: the quick review step spawns gsd-code-reviewer; resolve its own model
         // so model_overrides / models.verification apply (was reusing executor_model).
         reviewer_model: resolveModelInternal(cwd, 'gsd-code-reviewer'),
@@ -1239,10 +1330,49 @@ function cmdInitQuick(cwd, description, raw, options = {}) {
     result['section_manifest'] = buildSectionManifestField(cwd, null, sectionManifestOptions, 'quick');
     output(withProjectRoot(cwd, result), raw);
 }
+/**
+ * `init.quick-batch` (#3676, Phase 4 of epic #3344, ADR-1239 "Quick-batch
+ * binding"). Unlike `cmdInitQuick`, this init bundle does NOT allocate a
+ * quick id / slug / task directory itself — batch-level id allocation and
+ * `BATCH.json` creation is the job of the `quick-batch create` CLI verb
+ * (`src/quick-batch-command-router.cts`, wrapping `createBatch` in
+ * `src/quick-batch.cts`). This bundle supplies the per-role model profiles,
+ * `commit_docs`, the roadmap/planning existence checks `quick-batch.md`'s
+ * ROADMAP.md gate needs (same check `cmdInitQuick` runs), the `.planning/quick`
+ * directory path, and the `section_manifest` field gating the optional
+ * `--research`/`--validate` step fragments — the same `flag:--research`/
+ * `flag:--validate` atoms `quick`'s own section manifest already uses
+ * (`WHEN_VOCABULARY` is workflow-agnostic; no new atom is needed). `--discuss`/
+ * `--full` are rejected by `quick-batch-dispatch.cts`'s `parseQuickBatchArgs`
+ * before this init bundle is ever reached, so no `discuss`/`full` flag key is
+ * accepted here (unlike `cmdInitQuick`, which still supports both).
+ */
+function cmdInitQuickBatch(cwd, raw, options = {}) {
+    const config = loadConfig(cwd);
+    const result = {
+        planner_model: resolveModelInternal(cwd, 'gsd-planner'),
+        executor_model: resolveModelInternal(cwd, 'gsd-executor'),
+        checker_model: resolveModelInternal(cwd, 'gsd-plan-checker'),
+        verifier_model: resolveModelInternal(cwd, 'gsd-verifier'),
+        researcher_model: resolveModelInternal(cwd, 'gsd-phase-researcher'),
+        reviewer_model: resolveModelInternal(cwd, 'gsd-code-reviewer'),
+        commit_docs: config.commit_docs,
+        // #2376: absolute — see comment on phase_dir in cmdInitExecutePhase; a
+        // per-item task_dir is re-derived by the workflow itself (quick_id +
+        // generate-slug over that item's description), never allocated here.
+        quick_dir: toPosixPath(node_path_1.default.join(planningDir(cwd), 'quick')),
+        quick_batches_dir: toPosixPath(node_path_1.default.join(planningDir(cwd), 'quick-batches')),
+        roadmap_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md')),
+        planning_exists: node_fs_1.default.existsSync(planningRoot(cwd)),
+    };
+    // #2992 (Phase 6.1): additive, optional field — degrades to null, never throws.
+    result['section_manifest'] = buildSectionManifestField(cwd, null, options, 'quick-batch');
+    output(withProjectRoot(cwd, result), raw);
+}
 function cmdInitIngestDocs(cwd, raw) {
     const config = loadConfig(cwd);
     const result = {
-        project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'),
+        project_exists: pathExistsInternal(cwd, toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'PROJECT.md')))),
         planning_exists: node_fs_1.default.existsSync(planningRoot(cwd)),
         ...getInitGitState(cwd),
         // #2376: absolute — see comment on phase_dir in cmdInitExecutePhase. The
@@ -1263,12 +1393,11 @@ function cmdInitIngestDocs(cwd, raw) {
 }
 function cmdInitOnboard(cwd, raw, options = {}) {
     const config = loadConfig(cwd);
-    const workflowConfig = (config.workflow ?? {});
     const result = {
         ...buildOnboardProjection(cwd, {
             commitDocs: !!config.commit_docs,
             fast: options['fast'] === true,
-            textMode: options['text'] === true || !!config.text_mode || !!workflowConfig['text_mode'],
+            textMode: options['text'] === true || !!config.text_mode,
         }),
         ...getInitGitState(cwd),
     };
@@ -1281,9 +1410,14 @@ function cmdInitResume(cwd, raw) {
     if (agentIdRaw !== null)
         interruptedAgentId = agentIdRaw.trim();
     const result = {
+        // #4040: partial-init discriminator (see buildInitCompletenessFields).
+        // Spread FIRST so this literal's own root-scoped planning_exists
+        // (planningRoot) keeps its existing semantics; init_incomplete itself
+        // keys off the artifact dir (planningDir) where the core docs live.
+        ...buildInitCompletenessFields(cwd),
         state_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'STATE.md')),
         roadmap_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md')),
-        project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'),
+        project_exists: pathExistsInternal(cwd, toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'PROJECT.md')))),
         planning_exists: node_fs_1.default.existsSync(planningRoot(cwd)),
         // #2376: absolute — see comment on phase_dir in cmdInitExecutePhase.
         state_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'STATE.md')),
@@ -1600,9 +1734,11 @@ function cmdInitPhaseOp(cwd, phase, raw) {
                 directory: null,
                 phase_number: roadmapPhase['phase_number'],
                 phase_name: phaseName,
-                phase_slug: phaseName
-                    ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
-                    : null,
+                // #3883 (ADR-3473 §8.3): delegate to the canonical slug formula
+                // (generateSlugInternal, core-utils.cts) rather than re-implementing
+                // it. `maxLen: null` preserves this site's pre-migration untruncated
+                // contract.
+                phase_slug: phaseName ? coreUtils.generateSlugInternal(phaseName, null) : null,
                 plans: [],
                 summaries: [],
                 incomplete_plans: [],
@@ -1621,9 +1757,11 @@ function cmdInitPhaseOp(cwd, phase, raw) {
                 directory: null,
                 phase_number: roadmapPhase['phase_number'],
                 phase_name: phaseName,
-                phase_slug: phaseName
-                    ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
-                    : null,
+                // #3883 (ADR-3473 §8.3): delegate to the canonical slug formula
+                // (generateSlugInternal, core-utils.cts) rather than re-implementing
+                // it. `maxLen: null` preserves this site's pre-migration untruncated
+                // contract.
+                phase_slug: phaseName ? coreUtils.generateSlugInternal(phaseName, null) : null,
                 plans: [],
                 summaries: [],
                 incomplete_plans: [],
@@ -1674,6 +1812,9 @@ function cmdInitPhaseOp(cwd, phase, raw) {
         padded_phase: phaseNumber ? normalizePhaseName(phaseNumber) : null,
         has_research: phaseInfo?.['has_research'] || false,
         has_context: phaseInfo?.['has_context'] || false,
+        // #4014 (epic #3473 B4-unreadable): see the parallel field in
+        // cmdInitPlanPhase — additive scope signal adjacent to has_context.
+        context_scope: SCOPE.COMPLETE,
         has_plans: (phaseInfo?.['plans']?.length || 0) > 0,
         has_verification: phaseInfo?.['has_verification'] || false,
         has_reviews: phaseInfo?.['has_reviews'] || false,
@@ -1688,6 +1829,9 @@ function cmdInitPhaseOp(cwd, phase, raw) {
     };
     if (phaseInfo?.['directory']) {
         const phaseDirFull = node_path_1.default.join(cwd, phaseInfo['directory']);
+        // #4014 (epic #3473 B4-unreadable): see the parallel site in
+        // cmdInitPlanPhase — additive only, failure control-flow below unchanged.
+        result['context_scope'] = findContextMdIn(phaseDirFull).scope;
         try {
             const files = node_fs_1.default.readdirSync(phaseDirFull);
             const phaseDirName = node_path_1.default.basename(phaseDirFull);
@@ -1738,8 +1882,18 @@ function cmdInitPhaseOp(cwd, phase, raw) {
                 result['reviews_path'] = toPosixPath(node_path_1.default.join(phaseDirFull, reviewsFile));
             }
         }
-        catch {
-            /* intentionally empty */
+        catch (err) {
+            // #3885 (ADR-3473 §8.5): see the parallel site in cmdInitPlanPhase —
+            // ENOENT here is a genuine race (directory vanished after resolution)
+            // and stays a silent degrade; any other errno (EACCES/EIO/...) means
+            // the directory exists but could not be read, and must be named rather
+            // than silently reported the same as "none of context_path/
+            // research_path/verification_path/uat_path/reviews_path exist".
+            const code = err?.code;
+            if (code !== 'ENOENT') {
+                result['context_read_error'] =
+                    `Could not read phase directory ${formatDiagnosticToken(phaseDirFull)}: ${formatDiagnosticToken(err?.message ?? String(err))}`;
+            }
         }
     }
     output(withProjectRoot(cwd, result), raw);
@@ -1828,20 +1982,23 @@ function cmdInitMilestoneOp(cwd, raw) {
         const m = tok.match(/^(\d+)([A-Z]?(?:\.\d+)*)$/);
         return m ? String(parseInt(m[1], 10)) + m[2] : tok;
     };
+    // #3882 (ADR-3473 §8.2): this used to hand-roll a readdirSync over the
+    // phases directory (a heading->directory LOOKUP INDEX, same role as
+    // cmdRoadmapAnalyze's `_phaseDirNames` — `roadmapPhaseNumbers` above is
+    // already scoped/sentinel-excluded, so this map must see the PHYSICAL set
+    // to resolve each heading's phase number to its actual directory name;
+    // scoping it again would look up inside an already-scoped set for no
+    // benefit). Routed through the named "physical set, sentinels included"
+    // axis instead: every `num` looked up below came from `roadmapPhaseNumbers`
+    // (sentinels already excluded there), so a sentinel entry surviving in
+    // this map is never read — inclusion is output-invariant, this only
+    // removes the re-derivation.
     const diskPhaseDirs = new Map();
-    try {
-        const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-        for (const e of entries) {
-            if (!e.isDirectory())
-                continue;
-            const m = stripProjectCodePrefix(e.name).match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`));
-            if (!m)
-                continue;
-            diskPhaseDirs.set(canonicalizePhase(m[1]), e.name);
-        }
-    }
-    catch {
-        /* intentionally empty */
+    for (const name of listAllPhaseDirs(phasesDir, { includeSentinels: true }).value) {
+        const m = stripProjectCodePrefix(name).match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`));
+        if (!m)
+            continue;
+        diskPhaseDirs.set(canonicalizePhase(m[1]), name);
     }
     if (roadmapPhaseNumbers.length > 0) {
         phaseCount = roadmapPhaseNumbers.length;
@@ -1908,7 +2065,7 @@ function cmdInitMilestoneOp(cwd, raw) {
         all_phases_complete: phaseCount > 0 && phaseCount === completedPhases,
         archived_milestones: archivedMilestones,
         archive_count: archivedMilestones.length,
-        project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'),
+        project_exists: pathExistsInternal(cwd, toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'PROJECT.md')))),
         roadmap_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md')),
         state_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'STATE.md')),
         archive_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningRoot(cwd), 'archive')),
@@ -1918,7 +2075,12 @@ function cmdInitMilestoneOp(cwd, raw) {
 }
 function cmdInitMapCodebase(cwd, raw) {
     const config = loadConfig(cwd);
-    const codebaseDir = node_path_1.default.join(planningRoot(cwd), 'codebase');
+    // #3964: scoped like the payload's own codebase_dir/codebase_dir_exists
+    // below (and verify.cts's codebase drift check) — has_maps/existing_maps
+    // reading the flat root made the same payload claim a scoped codebase dir
+    // exists while reporting zero maps, so map-codebase's Refresh/Skip gate
+    // always forced a re-map under GSD_PROJECT.
+    const codebaseDir = node_path_1.default.join(planningDir(cwd), 'codebase');
     let existingMaps = [];
     try {
         existingMaps = node_fs_1.default.readdirSync(codebaseDir).filter((f) => f.endsWith('.md'));
@@ -1935,11 +2097,14 @@ function cmdInitMapCodebase(cwd, raw) {
         date: clock_cjs_1.realClock.localToday(),
         timestamp: clock_cjs_1.realClock.nowIso(),
         // #2376: absolute — see comment on phase_dir in cmdInitExecutePhase.
-        codebase_dir: toPosixPath(node_path_1.default.join(planningRoot(cwd), 'codebase')),
+        // #3964: scoped like verify.cts's codebase drift check (planningDir, not
+        // the flat planningRoot) so the two surfaces cannot disagree under
+        // GSD_PROJECT.
+        codebase_dir: toPosixPath(node_path_1.default.join(planningDir(cwd), 'codebase')),
         existing_maps: existingMaps,
         has_maps: existingMaps.length > 0,
         planning_exists: pathExistsInternal(cwd, '.planning'),
-        codebase_dir_exists: pathExistsInternal(cwd, '.planning/codebase'),
+        codebase_dir_exists: pathExistsInternal(cwd, toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'codebase')))),
     };
     output(withProjectRoot(cwd, result), raw);
 }
@@ -1995,6 +2160,9 @@ function cmdInitManager(cwd, raw) {
         let hasResearch = false;
         let lastActivity = null;
         let isActive = false;
+        // #4014 (epic #3473 B4-unreadable): default COMPLETE — no directory at
+        // all (dirMatch not found) is a genuine, not-unreadable answer.
+        let contextScope = SCOPE.COMPLETE;
         let completion = buildPhaseCompletionProjection(cwd, phaseNum, null, planCount, summaryCount, _slashRuntime);
         try {
             // #3185 (ADR-3180 Decision 2) moved this lookup off the
@@ -2005,6 +2173,17 @@ function cmdInitManager(cwd, raw) {
             if (dirMatch) {
                 const fullDir = node_path_1.default.join(phasesDir, dirMatch);
                 const phaseDirRel = toPosixPath(node_path_1.default.relative(cwd, fullDir));
+                // #4014 (epic #3473 B4-unreadable): this whole block used to swallow
+                // ANY readdirSync failure below into the bare `catch { /* empty */ }`
+                // at the bottom — an unreadable phase directory reported the exact
+                // same `has_context: false` / `disk_status: 'no_directory'` as a
+                // directory that never existed. findContextMdIn's directory-string
+                // form never throws, so it can record the real scope (COMPLETE vs
+                // UNREADABLE) here, BEFORE the pre-existing `fs.readdirSync(fullDir)`
+                // immediately below (unchanged) throws on the exact same unreadable
+                // directory and is caught exactly as before — this line is additive
+                // only, the failure control-flow is untouched.
+                contextScope = findContextMdIn(fullDir).scope;
                 const phaseFiles = node_fs_1.default.readdirSync(fullDir);
                 planCount = listPhasePlanFiles(fullDir).length;
                 summaryCount = listPhaseSummaryFiles(fullDir).length;
@@ -2079,6 +2258,7 @@ function cmdInitManager(cwd, raw) {
             ...completion,
             last_activity: lastActivity,
             is_active: isActive,
+            context_scope: contextScope,
         });
     }
     const MAX_NAME_WIDTH = 20;
@@ -2156,7 +2336,13 @@ function cmdInitManager(cwd, raw) {
     }
     let waitingSignal = null;
     try {
-        const waitingPath = node_path_1.default.join(cwd, '.planning', 'WAITING.json');
+        // #3964: mirror cmdSignalWaiting's write locations exactly — `.gsd/`
+        // first when it exists, else the project-aware planning dir — so the
+        // signal is read from the project (and location) it is written to.
+        const gsdWaiting = node_path_1.default.join(cwd, '.gsd', 'WAITING.json');
+        const waitingPath = node_fs_1.default.existsSync(node_path_1.default.join(cwd, '.gsd'))
+            ? gsdWaiting
+            : node_path_1.default.join(planningDir(cwd), 'WAITING.json');
         const waitingRaw = (0, shell_command_projection_cjs_1.platformReadSync)(waitingPath);
         if (waitingRaw !== null) {
             waitingSignal = JSON.parse(waitingRaw);
@@ -2261,7 +2447,7 @@ function cmdInitManager(cwd, raw) {
         recommended_actions: filteredActions,
         waiting_signal: waitingSignal,
         all_complete: completedCount === nonBacklogPhases.length && nonBacklogPhases.length > 0,
-        project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'),
+        project_exists: pathExistsInternal(cwd, toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'PROJECT.md')))),
         roadmap_exists: true,
         state_exists: true,
         manager_flags: managerFlags,
@@ -2449,7 +2635,7 @@ function cmdInitTransition(cwd, raw, options = {}) {
  *   location has one source instead of two kept in sync by hand.
  * - `debugger_model` — `resolveModelInternal`, which IS what `query
  *   resolve-model --pick model` returns (`cmdResolveModel`, src/commands.cts).
- * - `tdd_mode` — the `Boolean(wf['tdd_mode'])` idiom `cmdInitExecutePhase` and
+ * - `tdd_mode` — the `Boolean(config.tdd_mode)` idiom `cmdInitExecutePhase` and
  *   `cmdInitPlanPhase` already use. `/gsd:debug` has no `--tdd` flag, so the
  *   sibling handlers' `options['tdd'] ||` disjunct is deliberately omitted
  *   rather than carried as a phantom.
@@ -2467,7 +2653,6 @@ function cmdInitTransition(cwd, raw, options = {}) {
  */
 function cmdInitDebug(cwd, raw, options = {}) {
     const config = loadConfig(cwd);
-    const wf = (config.workflow ?? {});
     const result = {
         commit_docs: config.commit_docs,
         // #2376: absolute — debug.md builds `debug_file_path` as
@@ -2475,7 +2660,7 @@ function cmdInitDebug(cwd, raw, options = {}) {
         // own cwd may differ from the orchestrator's.
         debug_dir: toPosixPath(planningPaths(cwd).debug),
         debugger_model: resolveModelInternal(cwd, 'gsd-debugger'),
-        tdd_mode: Boolean(wf['tdd_mode']),
+        tdd_mode: Boolean(config.tdd_mode),
         diagnose: options['diagnose'] === true,
     };
     // Additive, optional field — degrades to null while `debug` has no key in
@@ -2617,7 +2802,11 @@ function cmdInitProgress(cwd, raw, options = {}) {
             const status = 'not_started';
             const phaseInfo = {
                 number: num,
-                name: name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, ''),
+                // #3883 (ADR-3473 §8.3): delegate to the canonical slug formula
+                // (generateSlugInternal, core-utils.cts) rather than re-implementing
+                // it. `maxLen: null` preserves this site's pre-migration untruncated
+                // contract.
+                name: coreUtils.generateSlugInternal(name, null) ?? '',
                 directory: null,
                 status,
                 plan_count: 0,
@@ -2632,7 +2821,7 @@ function cmdInitProgress(cwd, raw, options = {}) {
             }
         }
     }
-    phases.sort((a, b) => parseInt(a['number'], 10) - parseInt(b['number'], 10));
+    phases.sort((a, b) => comparePhaseNum(a['number'], b['number']));
     // #3581: the frontier is ROADMAP ORDER, not artifact presence. The disk loop
     // above could claim nextPhase from a stray out-of-order artifact directory
     // (a phase-9 UAT evidence dir while roadmap phase 8 was pending and
@@ -2691,9 +2880,13 @@ function cmdInitProgress(cwd, raw, options = {}) {
         paused_at: pausedAt,
         has_work_in_progress: !!currentPhase,
         phase_mvp_mode: phaseMvpMode,
-        project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'),
+        project_exists: pathExistsInternal(cwd, toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'PROJECT.md')))),
         roadmap_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md')),
         state_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'STATE.md')),
+        // #4040: partial-init discriminator (see buildInitCompletenessFields) —
+        // also adds planning_exists / requirements_exists / milestones_exists so
+        // progress.md's init_context routing never has to fall back to Glob.
+        ...buildInitCompletenessFields(cwd),
         // #2376: absolute — see comment on phase_dir in cmdInitExecutePhase.
         state_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'STATE.md')),
         roadmap_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md')),
@@ -3326,7 +3519,9 @@ function cmdSkillManifest(cwd, args, raw) {
     const skillsDir = skillsDirIdx >= 0 && args[skillsDirIdx + 1] ? args[skillsDirIdx + 1] : null;
     const manifest = buildSkillManifest(cwd, skillsDir);
     if (args.includes('--write')) {
-        const planDir = node_path_1.default.join(cwd, '.planning');
+        // #3964: write beside the project's own artifacts (planningDir is
+        // project- and workstream-aware), not the flat root.
+        const planDir = planningDir(cwd);
         if (node_fs_1.default.existsSync(planDir)) {
             const manifestPath = node_path_1.default.join(planDir, 'skill-manifest.json');
             (0, shell_command_projection_cjs_1.platformWriteSync)(manifestPath, JSON.stringify(manifest, null, 2));
@@ -3340,6 +3535,7 @@ module.exports = {
     cmdInitNewProject,
     cmdInitNewMilestone,
     cmdInitQuick,
+    cmdInitQuickBatch,
     cmdInitIngestDocs,
     cmdInitOnboard,
     cmdInitResume,