lee-spec-kit 0.8.3 → 0.8.4

package/dist/index.js

@@ -1297,8 +1297,9 @@ Before taking the next workflow step:
    - task commit checkpoints after each completed task
 8. In standalone mode, keep the docs repo on its docs branch and do not create feature branches or worktrees there
 9. In standalone mode, use the project repo through its managed feature worktree under the shared workspace \`.worktrees/\` root instead of checking the feature branch out in the main project repo
-10. Keep docs and code synchronized; if code changes materially, update the active feature docs in the same turn before stopping
-11. When docs are synced to code, refresh an explicit marker like \`<!-- lee-spec-kit:workflow-sync 2026-04-16T12:34:56.789Z -->\` in the active feature docs (prefer \`tasks.md\` or \`decisions.md\`) so \`workflow-audit\` can prove the sync happened after the latest code change
+10. In standalone mode, do not hand-write \`git worktree add\`; run the exact \`nextAction.command\` from \`workflow-stage\` so the managed workspace path, stale directory cleanup, and \`.env\` / \`.env.*\` copy step stay consistent
+11. Keep docs and code synchronized; if code changes materially, update the active feature docs in the same turn before stopping
+12. When docs are synced to code, refresh an explicit marker like \`<!-- lee-spec-kit:workflow-sync 2026-04-16T12:34:56.789Z -->\` in the active feature docs (prefer \`tasks.md\` or \`decisions.md\`) so \`workflow-audit\` can prove the sync happened after the latest code change
 
 Approval and remote actions:
 
@@ -1464,10 +1465,33 @@ function resolveManagedWorktreePath(config, projectRoot, branchName) {
     normalizeBranchNameForWorktree(branchName)
   );
 }
-function buildManagedWorktreeEnvLinkCommand(projectRoot, worktreePath) {
-  const sourceEnvPath = path8.resolve(projectRoot, ".env");
-  const targetEnvPath = path8.resolve(worktreePath, ".env");
-  return `if [ -f "${sourceEnvPath}" ] && [ ! -e "${targetEnvPath}" ] && [ ! -L "${targetEnvPath}" ]; then ln -s "${sourceEnvPath}" "${targetEnvPath}"; fi`;
+var registeredWorktreeCache = /* @__PURE__ */ new Map();
+function listRegisteredGitWorktrees(projectRoot) {
+  const resolvedProjectRoot = path8.resolve(projectRoot);
+  const cached = registeredWorktreeCache.get(resolvedProjectRoot);
+  if (cached) return cached;
+  const output = runGitCapture(
+    ["worktree", "list", "--porcelain"],
+    resolvedProjectRoot
+  ) || "";
+  const worktrees = /* @__PURE__ */ new Set();
+  for (const line of output.split(/\r?\n/u)) {
+    if (!line.startsWith("worktree ")) continue;
+    const listedPath = line.slice("worktree ".length).trim();
+    if (listedPath) worktrees.add(path8.resolve(listedPath));
+  }
+  registeredWorktreeCache.set(resolvedProjectRoot, worktrees);
+  return worktrees;
+}
+function isRegisteredGitWorktree(projectRoot, worktreePath) {
+  const resolvedTarget = path8.resolve(worktreePath);
+  return listRegisteredGitWorktrees(projectRoot).has(resolvedTarget);
+}
+function buildManagedWorktreeStaleCleanupCommand(projectRoot, worktreePath) {
+  return `if [ -d "${worktreePath}" ] && ! git -C "${projectRoot}" worktree list --porcelain | grep -Fxq "worktree ${worktreePath}"; then rm -rf "${worktreePath}"; fi`;
+}
+function buildManagedWorktreeEnvCopyCommand(projectRoot, worktreePath) {
+  return `sh -c 'source_dir=$1; target_dir=$2; for source_env in "$source_dir"/.env "$source_dir"/.env.*; do [ -e "$source_env" ] || [ -L "$source_env" ] || continue; target_env="$target_dir/$(basename "$source_env")"; if [ ! -e "$target_env" ] && [ ! -L "$target_env" ]; then cp -p "$source_env" "$target_env"; fi; done' sh "${path8.resolve(projectRoot)}" "${path8.resolve(worktreePath)}"`;
 }
 
 // src/utils/init/options.ts
@@ -4023,7 +4047,7 @@ async function resolveExistingManagedWorktreePath(config, projectGitCwd, slug, f
     (candidate) => resolveManagedWorktreePath(config, projectRoot, candidate)
   );
   for (const candidate of candidates) {
-    if (await fs.pathExists(candidate)) {
+    if (await fs.pathExists(candidate) && isRegisteredGitWorktree(projectRoot, candidate)) {
       return candidate;
     }
   }
@@ -6744,6 +6768,380 @@ function docsCommand(program2) {
     }
   });
 }
+
+// src/utils/task-lines.ts
+function parseTaskLine(line, index = -1) {
+  const match = line.match(
+    /^\s*-\s*\[(TODO|DOING|DONE|REVIEW)\]((?:\[[^\]]+\])*)\s+(T-[A-Za-z0-9-]+)\s+(.+?)\s*$/
+  );
+  if (!match) return null;
+  const tags = [...(match[2] || "").matchAll(/\[([^\]]+)\]/g)].map((entry) => (entry[1] || "").trim()).filter(Boolean);
+  return {
+    index,
+    raw: line,
+    status: match[1],
+    tags,
+    taskId: match[3],
+    title: match[4]
+  };
+}
+
+// src/utils/doc-mutation.ts
+function collectRepeatableOption(value, previous = []) {
+  return [...previous, value];
+}
+function normalizeRequiredText(value, label) {
+  const normalized = (value || "").trim();
+  if (!normalized || normalized === "-" || /^todo$/i.test(normalized)) {
+    throw createCliError(
+      "INVALID_ARGUMENT",
+      `${label} must contain concrete text.`
+    );
+  }
+  return normalized;
+}
+function normalizeRequiredItems(values, label) {
+  const normalized = (values || []).map((value) => value.trim()).filter(Boolean);
+  if (normalized.length === 0) {
+    throw createCliError(
+      "INVALID_ARGUMENT",
+      `${label} must be provided at least once.`
+    );
+  }
+  for (const value of normalized) {
+    normalizeRequiredText(value, label);
+  }
+  return normalized;
+}
+async function resolveFeatureDocTarget(input) {
+  const state = await resolveFeatureSelection(
+    input.cwd,
+    input.selector,
+    input.component
+  );
+  if (state.status !== "selected" || !state.matchedFeature) {
+    throw createCliError(
+      "CONTEXT_SELECTION_REQUIRED",
+      `A single feature is required. Pass <feature-name> explicitly.`
+    );
+  }
+  const targetPath = path8.join(state.matchedFeature.path, input.fileName);
+  if (!await fs.pathExists(targetPath)) {
+    throw createCliError(
+      "PRECONDITION_FAILED",
+      `${input.fileName} not found for feature: ${state.matchedFeature.folderName}`
+    );
+  }
+  return {
+    feature: state.matchedFeature,
+    path: targetPath
+  };
+}
+function findSecondLevelHeadingIndex(lines, names) {
+  const alternatives = names.map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  const pattern = new RegExp(`^\\s*##\\s+(${alternatives.join("|")})\\s*$`);
+  return lines.findIndex((line) => pattern.test(line));
+}
+function findNextSecondLevelHeadingIndex(lines, start) {
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^\s*##\s+/.test(lines[index] || "")) return index;
+  }
+  return lines.length;
+}
+function normalizeMarkdownEnd(content) {
+  return content.replace(/\s+$/g, "") + "\n";
+}
+function localDate() {
+  return getLocalDateString();
+}
+function nextTaskSequence(content, featureFolderName) {
+  const escaped = featureFolderName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const taskIdPattern = new RegExp(`\\bT-${escaped}-(\\d+)\\b`, "g");
+  let max = 0;
+  for (const match of content.matchAll(taskIdPattern)) {
+    const parsed = Number(match[1] || "0");
+    if (Number.isFinite(parsed) && parsed > max) max = parsed;
+  }
+  return max + 1;
+}
+function findTaskInsertIndex(lines, sectionStart, sectionEnd) {
+  let lastTaskIndex = -1;
+  for (let index = sectionStart; index < sectionEnd; index += 1) {
+    if (parseTaskLine(lines[index] || "", index)) lastTaskIndex = index;
+  }
+  if (lastTaskIndex < 0) return sectionEnd;
+  let insertIndex = lastTaskIndex + 1;
+  while (insertIndex < sectionEnd) {
+    const line = lines[insertIndex] || "";
+    if (parseTaskLine(line, insertIndex)) break;
+    if (/^\s{2,}\S/.test(line) || /^\s*$/.test(line)) {
+      insertIndex += 1;
+      continue;
+    }
+    break;
+  }
+  return insertIndex;
+}
+
+// src/commands/task.ts
+function normalizeTaskRef(value) {
+  const ref = normalizeRequiredText(value, "--ref").toUpperCase();
+  if (ref === "NON-PRD") return ref;
+  if (!/^PRD-[A-Z0-9][A-Z0-9-]*$/.test(ref)) {
+    throw createCliError(
+      "INVALID_ARGUMENT",
+      "`--ref` must be `NON-PRD` or a `PRD-*` requirement key."
+    );
+  }
+  return ref;
+}
+function formatTaskBlock(input) {
+  return [
+    `- [TODO][${input.ref}] ${input.taskId} ${input.title}`,
+    `  - Date: ${input.date}`,
+    "  - Acceptance:",
+    ...input.acceptanceItems.map((item) => `    - ${item}`),
+    "  - Checklist:",
+    ...input.checklistItems.map((item) => `    - [ ] ${item}`)
+  ];
+}
+async function runTaskAdd(featureName, options) {
+  const target = await resolveFeatureDocTarget({
+    cwd: process.cwd(),
+    selector: featureName,
+    component: options.component,
+    fileName: "tasks.md"
+  });
+  const title = normalizeRequiredText(options.title, "--title");
+  const ref = normalizeTaskRef(options.ref);
+  const acceptanceItems = normalizeRequiredItems(options.acceptance, "--acceptance");
+  const checklistItems = normalizeRequiredItems(options.check, "--check");
+  const content = await fs.readFile(target.path, "utf-8");
+  const lines = content.split("\n");
+  const taskListIndex = findSecondLevelHeadingIndex(lines, ["Task List", "\uD0DC\uC2A4\uD06C \uBAA9\uB85D"]);
+  if (taskListIndex < 0) {
+    throw createCliError(
+      "PRECONDITION_FAILED",
+      "tasks.md is missing a `Task List` section."
+    );
+  }
+  const sectionEnd = findNextSecondLevelHeadingIndex(lines, taskListIndex);
+  const insertIndex = findTaskInsertIndex(lines, taskListIndex + 1, sectionEnd);
+  const taskId = `T-${target.feature.folderName}-${String(
+    nextTaskSequence(content, target.feature.folderName)
+  ).padStart(2, "0")}`;
+  const recordedAt = localDate();
+  const block = formatTaskBlock({
+    ref,
+    taskId,
+    title,
+    date: recordedAt,
+    acceptanceItems,
+    checklistItems
+  });
+  const shouldPrefixBlank = insertIndex > taskListIndex + 1 && (lines[insertIndex - 1] || "").trim() !== "";
+  const shouldSuffixBlank = insertIndex < lines.length && (lines[insertIndex] || "").trim() !== "";
+  lines.splice(
+    insertIndex,
+    0,
+    ...shouldPrefixBlank ? [""] : [],
+    ...block,
+    ...shouldSuffixBlank ? [""] : []
+  );
+  await fs.writeFile(target.path, normalizeMarkdownEnd(lines.join("\n")), "utf-8");
+  const payload = {
+    status: "ok",
+    reasonCode: "TASK_ADDED",
+    feature: target.feature.folderName,
+    taskId,
+    title,
+    ref,
+    tasksUpdated: true,
+    tasksPath: target.path,
+    recordedAt
+  };
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(chalk.green(`Added task ${taskId} to ${target.feature.folderName}.`));
+  console.log(chalk.gray(`- tasks.md updated: ${target.path}`));
+}
+function taskCommand(program2) {
+  const task = program2.command("task").description("Patch feature task docs");
+  task.command("add [feature-name]").description("Append a docs-only task block to tasks.md").requiredOption("--title <title>", "Task title").requiredOption("--ref <ref>", "Requirement ref: NON-PRD or PRD-* key").option(
+    "--acceptance <text>",
+    "Concrete acceptance item. Repeat to add more than one.",
+    collectRepeatableOption,
+    []
+  ).option(
+    "--check <text>",
+    "Concrete checklist item. Repeat to add more than one.",
+    collectRepeatableOption,
+    []
+  ).option("--component <component>", "Component name for multi projects").option("--json", "Output JSON").action(async (featureName, options) => {
+    try {
+      await runTaskAdd(featureName, options);
+    } catch (error) {
+      const cliError = toCliError(error);
+      const suggestions = getCliErrorSuggestions(cliError.code, DEFAULT_LANG);
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            status: "error",
+            reasonCode: cliError.code,
+            error: cliError.message,
+            suggestions
+          })
+        );
+        process.exitCode = 1;
+        return;
+      }
+      console.error(chalk.red(`[${cliError.code}] ${cliError.message}`));
+      printCliErrorSuggestions(suggestions, DEFAULT_LANG);
+      process.exitCode = 1;
+    }
+  });
+}
+function getNextDecisionSequence(content) {
+  let max = 0;
+  for (const match of content.matchAll(/^##\s+D(\d+):\s+/gm)) {
+    if (/\{(?:Decision Title|결정 제목)\}/.test(match[0])) continue;
+    const parsed = Number(match[1] || "0");
+    if (Number.isFinite(parsed) && parsed > max) max = parsed;
+  }
+  return max + 1;
+}
+function findPlaceholderDecisionRange(content) {
+  const match = /^##\s+D(\d+):\s+.*$/m.exec(content);
+  if (!match || match.index === void 0) return null;
+  const afterHeadingIndex = match.index + match[0].length;
+  const nextHeadingMatch = /^##\s+D\d+:\s+/m.exec(content.slice(afterHeadingIndex));
+  const end = nextHeadingMatch ? afterHeadingIndex + nextHeadingMatch.index : content.length;
+  const block = content.slice(match.index, end);
+  const isPlaceholder = /\{(?:Decision Title|결정 제목)\}/.test(match[0]) || /-\s+\*\*Decision\*\*:\s*(Final choice|최종 선택)/.test(block);
+  if (!isPlaceholder) return null;
+  const sequence = Number(match[1] || "1");
+  return {
+    start: match.index,
+    end,
+    sequence: Number.isFinite(sequence) ? sequence : 1
+  };
+}
+function formatOptions(options) {
+  return options.length > 0 ? options.join("; ") : "-";
+}
+function formatDecisionBlock(input) {
+  return [
+    `## ${input.decisionId}: ${input.title} (${input.date})`,
+    "",
+    `- **Context**: ${input.context}`,
+    `- **Constraints**: ${input.constraints}`,
+    `- **Options**: ${formatOptions(input.options)}`,
+    `- **Decision**: ${input.decision}`,
+    `- **Rationale**: ${input.rationale}`,
+    "- **Trace**:",
+    "  - **At DOING start**: Recorded by `decision add` when the decision was created.",
+    "  - **Before DONE**: Update this line when the related task is completed.",
+    "  - **Post-merge check**: Update this line after merge when applicable.",
+    "- **Evidence**:",
+    ...input.evidence.map((item) => `  - **Test/Log**: ${item}`),
+    `- **Consequences**: ${input.consequence}`
+  ].join("\n");
+}
+async function runDecisionAdd(featureName, options) {
+  const target = await resolveFeatureDocTarget({
+    cwd: process.cwd(),
+    selector: featureName,
+    component: options.component,
+    fileName: "decisions.md"
+  });
+  const title = normalizeRequiredText(options.title, "--title");
+  const context = normalizeRequiredText(options.context, "--context");
+  const decision = normalizeRequiredText(options.decision, "--decision");
+  const rationale = normalizeRequiredText(options.rationale, "--rationale");
+  const evidence = normalizeRequiredItems(options.evidence, "--evidence");
+  const constraints = (options.constraints || "").trim() || "-";
+  const consequence = (options.consequence || "").trim() || "-";
+  const optionItems = (options.option || []).map((value) => value.trim()).filter(Boolean);
+  const content = await fs.readFile(target.path, "utf-8");
+  const placeholderRange = findPlaceholderDecisionRange(content);
+  const decisionSequence = placeholderRange?.sequence ?? getNextDecisionSequence(content);
+  const decisionId = `D${String(decisionSequence).padStart(3, "0")}`;
+  const recordedAt = localDate();
+  const block = formatDecisionBlock({
+    decisionId,
+    title,
+    date: recordedAt,
+    context,
+    constraints,
+    options: optionItems,
+    decision,
+    rationale,
+    evidence,
+    consequence
+  });
+  const nextContent = placeholderRange ? normalizeMarkdownEnd(
+    `${content.slice(0, placeholderRange.start)}${block}${content.slice(
+      placeholderRange.end
+    )}`
+  ) : `${normalizeMarkdownEnd(content)}
+${block}
+`;
+  await fs.writeFile(target.path, nextContent, "utf-8");
+  const payload = {
+    status: "ok",
+    reasonCode: "DECISION_ADDED",
+    feature: target.feature.folderName,
+    decisionId,
+    title,
+    decisionsUpdated: true,
+    decisionsPath: target.path,
+    recordedAt
+  };
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(chalk.green(`Added decision ${decisionId} to ${target.feature.folderName}.`));
+  console.log(chalk.gray(`- decisions.md updated: ${target.path}`));
+}
+function decisionCommand(program2) {
+  const decision = program2.command("decision").description("Patch feature decision docs");
+  decision.command("add [feature-name]").description("Append a docs-only ADR block to decisions.md").requiredOption("--title <title>", "Decision title").requiredOption("--context <text>", "Decision context").option("--constraints <text>", "Decision constraints").option(
+    "--option <text>",
+    "Alternative considered. Repeat to add more than one.",
+    collectRepeatableOption,
+    []
+  ).requiredOption("--decision <text>", "Final decision").requiredOption("--rationale <text>", "Decision rationale").option(
+    "--evidence <text>",
+    "Evidence link or test/log note. Repeat to add more than one.",
+    collectRepeatableOption,
+    []
+  ).option("--consequence <text>", "Decision consequence").option("--component <component>", "Component name for multi projects").option("--json", "Output JSON").action(async (featureName, options) => {
+    try {
+      await runDecisionAdd(featureName, options);
+    } catch (error) {
+      const cliError = toCliError(error);
+      const suggestions = getCliErrorSuggestions(cliError.code, DEFAULT_LANG);
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            status: "error",
+            reasonCode: cliError.code,
+            error: cliError.message,
+            suggestions
+          })
+        );
+        process.exitCode = 1;
+        return;
+      }
+      console.error(chalk.red(`[${cliError.code}] ${cliError.message}`));
+      printCliErrorSuggestions(suggestions, DEFAULT_LANG);
+      process.exitCode = 1;
+    }
+  });
+}
 function detectCommand(program2) {
   program2.command("detect").description(tr(DEFAULT_LANG, "cli", "detect.cmdDescription")).option("--dir <dir>", tr(DEFAULT_LANG, "cli", "detect.optDir")).option("--json", tr(DEFAULT_LANG, "cli", "detect.optJson")).action(async (options) => {
     try {
@@ -6924,7 +7322,7 @@ function registerCodexHooksIntegration(parent) {
         removeLeeSpecKitCodexHooks,
         resolveCodexHooksRepoRoot,
         upsertLeeSpecKitCodexHooks
-      } = await import('./hooks-B5UIIZYN.js');
+      } = await import('./hooks-43P4YKHY.js');
       const repoRoot = config.docsRepo === "standalone" ? resolveConfiguredStandaloneWorkspaceRoot(config) : resolveCodexHooksRepoRoot(process.cwd());
       if (!repoRoot) {
         throw createCliError(
@@ -7385,15 +7783,20 @@ function getExpectedWorktreePath(config, projectGitCwd, branchName) {
   return resolveManagedWorktreePath(config, projectRoot, branchName);
 }
 async function resolveExistingExpectedWorktreePath(config, projectGitCwd, branchName) {
+  const projectRoot = resolveProjectRootFromGitCwd2(projectGitCwd);
   const candidate = getExpectedWorktreePath(config, projectGitCwd, branchName);
-  return await fs.pathExists(candidate) ? candidate : null;
+  return await fs.pathExists(candidate) && isRegisteredGitWorktree(projectRoot, candidate) ? candidate : null;
 }
 function buildManagedWorktreeCreateCommand(config, projectGitCwd, branchName) {
   const projectRoot = resolveProjectRootFromGitCwd2(projectGitCwd);
   const worktreePath = getExpectedWorktreePath(config, projectGitCwd, branchName);
   const worktreeParent = path8.dirname(worktreePath);
-  const envLinkCommand = buildManagedWorktreeEnvLinkCommand(projectRoot, worktreePath);
-  return `mkdir -p "${worktreeParent}" && (git -C "${projectRoot}" worktree add "${worktreePath}" "${branchName}" || git -C "${projectRoot}" worktree add -b "${branchName}" "${worktreePath}") && ${envLinkCommand}`;
+  const staleCleanupCommand = buildManagedWorktreeStaleCleanupCommand(
+    projectRoot,
+    worktreePath
+  );
+  const envCopyCommand = buildManagedWorktreeEnvCopyCommand(projectRoot, worktreePath);
+  return `${staleCleanupCommand} && mkdir -p "${worktreeParent}" && (git -C "${projectRoot}" worktree add "${worktreePath}" "${branchName}" || git -C "${projectRoot}" worktree add -b "${branchName}" "${worktreePath}") && ${envCopyCommand}`;
 }
 function resolveRemotePrMergeMeta(prRef, projectGitCwd) {
   if (!prRef) return null;
@@ -9224,10 +9627,10 @@ function parseStagedPaths(output) {
     staged.set(`path:${normalizeSlashes3(parts[1])}`, `${status}:path`);
   }
   return [...staged.entries()].map(([encodedPath, encodedStatus]) => {
-    const [role, path26] = encodedPath.split(":", 2);
+    const [role, path27] = encodedPath.split(":", 2);
     const [status, entryRole] = encodedStatus.split(":", 2);
     return {
-      path: path26,
+      path: path27,
       status,
       role: entryRole || role || "path"
     };
@@ -9502,6 +9905,8 @@ function configureRootCommandSurface() {
     ["init", "Docs Schema Commands:"],
     ["idea", "Docs Schema Commands:"],
     ["feature", "Docs Schema Commands:"],
+    ["task", "Docs Schema Commands:"],
+    ["decision", "Docs Schema Commands:"],
     ["docs", "Workflow Policy Commands:"],
     ["detect", "Workflow Policy Commands:"],
     ["github", "Workflow Policy Commands:"],
@@ -9531,6 +9936,8 @@ updateCommand(program);
 configCommand(program);
 githubCommand(program);
 docsCommand(program);
+taskCommand(program);
+decisionCommand(program);
 detectCommand(program);
 workflowStageCommand(program);
 integrationsCommand(program);