@jakkrichm/create-nexus-devflow 2.11.0 → 2.12.0

package/template/.claude/skills/doctor/scripts/run-state.mjs

@@ -0,0 +1,513 @@
+#!/usr/bin/env node
+
+// Standalone ESM because installed projects may use CommonJS.
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const ACTIONS = new Set(["start", "update", "finish", "reset"]);
+const BOUNDARIES = new Set(["read-only", "reviewed", "local-only"]);
+const COMMAND_PATTERN = /^[a-z][a-z-]{0,31}$/;
+const RUN_PATH = path.join("devflow", ".state", "run.json");
+const STATUSES = new Set(["running", "blocked", "ready", "completed"]);
+const MAX_LENGTHS = {
+  detail: 1000,
+  featureId: 80,
+  featureTitle: 160,
+  progressLabel: 80,
+  resumeCommand: 240,
+  summary: 240
+};
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const projectRoot = await findProjectRoot(options.target);
+
+  if (options.action === "reset") {
+    await resetState(projectRoot);
+    console.log("Dashboard activity reset.");
+    return;
+  }
+
+  const previous = options.action === "start"
+    ? null
+    : await readState(projectRoot);
+  const state = buildState(options, previous, new Date().toISOString());
+  await writeState(projectRoot, state);
+  console.log(`Recorded /${state.command}: ${state.status} - ${state.summary}`);
+}
+
+function parseArgs(args) {
+  const options = {
+    action: null,
+    boundary: null,
+    command: null,
+    current: null,
+    detail: null,
+    featureId: null,
+    featureTitle: null,
+    help: false,
+    label: null,
+    resumeCommand: null,
+    status: null,
+    summary: null,
+    target: null,
+    total: null
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (ACTIONS.has(arg)) {
+      if (options.action) {
+        throw new Error("Choose only one run-state action.");
+      }
+      options.action = arg;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "--command") {
+      options.command = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--summary") {
+      options.summary = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--detail") {
+      options.detail = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--boundary") {
+      options.boundary = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--status") {
+      options.status = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--resume") {
+      options.resumeCommand = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--feature-id") {
+      options.featureId = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--feature-title") {
+      options.featureTitle = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--current") {
+      options.current = readInteger(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--total") {
+      options.total = readInteger(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--label") {
+      options.label = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--target" || arg === "-t") {
+      options.target = readValue(args, ++index, arg);
+      continue;
+    }
+
+    throw new Error(`Unknown run-state option: ${arg}`);
+  }
+
+  validateOptions(options);
+  return options;
+}
+
+function validateOptions(options) {
+  if (options.help) {
+    return;
+  }
+  if (!options.action) {
+    throw new Error("Choose one run-state action: start, update, finish, or reset.");
+  }
+
+  const progressCount = [options.current, options.total, options.label]
+    .filter((value) => value !== null).length;
+  if (progressCount !== 0 && progressCount !== 3) {
+    throw new Error("Progress requires --current, --total, and --label together.");
+  }
+  if (options.featureId && !options.featureTitle) {
+    throw new Error("--feature-id requires --feature-title.");
+  }
+
+  if (options.action === "reset") {
+    const unsupported = [
+      options.boundary,
+      options.command,
+      options.current,
+      options.detail,
+      options.featureId,
+      options.featureTitle,
+      options.label,
+      options.resumeCommand,
+      options.status,
+      options.summary,
+      options.total
+    ].some((value) => value !== null);
+    if (unsupported) {
+      throw new Error("Reset accepts only --target and --help.");
+    }
+    return;
+  }
+
+  if (options.action === "start") {
+    if (!options.command || !options.summary || !options.boundary) {
+      throw new Error("Start requires --command, --summary, and --boundary.");
+    }
+    if (options.status) {
+      throw new Error("Start always records running status.");
+    }
+    return;
+  }
+
+  if (options.command) {
+    throw new Error("Only start accepts --command.");
+  }
+  if (options.boundary) {
+    throw new Error("Only start accepts --boundary.");
+  }
+  if (options.action === "finish") {
+    if (options.status && !["ready", "completed"].includes(options.status)) {
+      throw new Error("Finish status must be ready or completed.");
+    }
+    return;
+  }
+  if (options.status && !["running", "blocked", "ready"].includes(options.status)) {
+    throw new Error("Update status must be running, blocked, or ready.");
+  }
+
+  const hasUpdate = [
+    options.current,
+    options.detail,
+    options.featureTitle,
+    options.resumeCommand,
+    options.status,
+    options.summary
+  ].some((value) => value !== null);
+  if (!hasUpdate) {
+    throw new Error("Update needs at least one changed activity field.");
+  }
+}
+
+function buildState(options, previous, timestamp) {
+  if (options.action === "start") {
+    const state = {
+      schemaVersion: 1,
+      command: requireText(options.command, "command", 32),
+      status: "running",
+      summary: requireText(options.summary, "summary", MAX_LENGTHS.summary),
+      boundary: requireBoundary(options.boundary),
+      startedAt: timestamp,
+      updatedAt: timestamp
+    };
+    applyOptionalFields(state, options);
+    return validateState(state);
+  }
+
+  const state = {
+    ...previous,
+    status: options.action === "finish"
+      ? options.status || "completed"
+      : options.status || previous.status,
+    summary: options.summary
+      ? requireText(options.summary, "summary", MAX_LENGTHS.summary)
+      : previous.summary,
+    updatedAt: timestamp
+  };
+  applyOptionalFields(state, options);
+
+  if (
+    options.action === "finish" ||
+    (previous.status === "blocked" && state.status !== "blocked")
+  ) {
+    if (!options.resumeCommand) {
+      delete state.resumeCommand;
+    }
+    if (!options.detail) {
+      delete state.detail;
+    }
+  }
+
+  return validateState(state);
+}
+
+function applyOptionalFields(state, options) {
+  if (options.detail) {
+    state.detail = requireText(options.detail, "detail", MAX_LENGTHS.detail);
+  }
+  if (options.resumeCommand) {
+    state.resumeCommand = requireText(
+      options.resumeCommand,
+      "resume command",
+      MAX_LENGTHS.resumeCommand
+    );
+  }
+  if (options.current !== null) {
+    state.progress = validateProgress({
+      current: options.current,
+      total: options.total,
+      label: options.label
+    });
+  }
+  if (options.featureTitle) {
+    state.feature = {
+      id: options.featureId,
+      title: requireText(
+        options.featureTitle,
+        "feature title",
+        MAX_LENGTHS.featureTitle
+      )
+    };
+    if (state.feature.id !== null) {
+      state.feature.id = requireText(
+        state.feature.id,
+        "feature ID",
+        MAX_LENGTHS.featureId
+      );
+    }
+  }
+}
+
+function validateState(value) {
+  if (!isRecord(value)) {
+    throw new Error("Run state must be an object.");
+  }
+  if (
+    value.schemaVersion !== 1 ||
+    typeof value.command !== "string" ||
+    !COMMAND_PATTERN.test(value.command) ||
+    !STATUSES.has(value.status) ||
+    !isBoundedText(value.summary, MAX_LENGTHS.summary) ||
+    typeof value.startedAt !== "string" ||
+    typeof value.updatedAt !== "string" ||
+    Number.isNaN(Date.parse(value.startedAt)) ||
+    Number.isNaN(Date.parse(value.updatedAt)) ||
+    Date.parse(value.startedAt) > Date.parse(value.updatedAt) ||
+    (value.boundary !== undefined && !BOUNDARIES.has(value.boundary)) ||
+    (value.detail !== undefined && !isBoundedText(value.detail, MAX_LENGTHS.detail)) ||
+    (value.resumeCommand !== undefined &&
+      !isBoundedText(value.resumeCommand, MAX_LENGTHS.resumeCommand)) ||
+    (value.progress !== undefined && !isValidProgress(value.progress)) ||
+    (value.feature !== undefined && !isValidFeature(value.feature))
+  ) {
+    throw new Error("Run state does not match dashboard schema version 1.");
+  }
+
+  return value;
+}
+
+function validateProgress(progress) {
+  if (!isValidProgress(progress)) {
+    throw new Error(
+      "Progress requires integers where 0 <= current <= total and total >= 1."
+    );
+  }
+  return {
+    current: progress.current,
+    total: progress.total,
+    label: progress.label.trim()
+  };
+}
+
+function isValidProgress(value) {
+  return isRecord(value) &&
+    Number.isInteger(value.current) &&
+    Number.isInteger(value.total) &&
+    value.current >= 0 &&
+    value.total >= 1 &&
+    value.current <= value.total &&
+    isBoundedText(value.label, MAX_LENGTHS.progressLabel);
+}
+
+function isValidFeature(value) {
+  return isRecord(value) &&
+    (value.id === null || isBoundedText(value.id, MAX_LENGTHS.featureId)) &&
+    isBoundedText(value.title, MAX_LENGTHS.featureTitle);
+}
+
+async function findProjectRoot(target) {
+  let current = path.resolve(process.cwd(), target || ".");
+  const initial = await fs.lstat(current);
+  if (initial.isFile()) {
+    current = path.dirname(current);
+  }
+
+  while (true) {
+    const devflowPath = path.join(current, "devflow");
+    try {
+      const devflow = await fs.lstat(devflowPath);
+      if (devflow.isSymbolicLink() || !devflow.isDirectory()) {
+        throw new Error("DevFlow path must be a real directory.");
+      }
+      const statePath = path.join(devflowPath, ".state");
+      const state = await fs.lstat(statePath);
+      if (state.isSymbolicLink() || !state.isDirectory()) {
+        throw new Error("DevFlow state path must be a real directory.");
+      }
+      return current;
+    } catch (error) {
+      if (error?.code !== "ENOENT") {
+        throw error;
+      }
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      throw new Error("Could not find a DevFlow project with devflow/.state.");
+    }
+    current = parent;
+  }
+}
+
+async function readState(projectRoot) {
+  const filePath = path.join(projectRoot, RUN_PATH);
+  await requireRegularFile(filePath);
+
+  let parsed;
+  try {
+    parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch {
+    throw new Error("Existing dashboard state is malformed. Start a new run or use /doctor.");
+  }
+  return validateState(parsed);
+}
+
+async function writeState(projectRoot, state) {
+  const filePath = path.join(projectRoot, RUN_PATH);
+  await requireRegularOrMissing(filePath);
+  const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
+
+  try {
+    await fs.writeFile(
+      temporaryPath,
+      `${JSON.stringify(validateState(state), null, 2)}\n`,
+      { encoding: "utf8", flag: "wx", mode: 0o600 }
+    );
+    await fs.rename(temporaryPath, filePath);
+    validateState(JSON.parse(await fs.readFile(filePath, "utf8")));
+  } catch (error) {
+    await fs.rm(temporaryPath, { force: true });
+    throw error;
+  }
+}
+
+async function resetState(projectRoot) {
+  const filePath = path.join(projectRoot, RUN_PATH);
+  try {
+    await requireRegularFile(filePath);
+    await fs.rm(filePath);
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+async function requireRegularFile(filePath) {
+  const stats = await fs.lstat(filePath);
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    throw new Error("Dashboard run state must be a regular file.");
+  }
+}
+
+async function requireRegularOrMissing(filePath) {
+  try {
+    await requireRegularFile(filePath);
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+function requireBoundary(value) {
+  if (!BOUNDARIES.has(value)) {
+    throw new Error("Boundary must be read-only, reviewed, or local-only.");
+  }
+  return value;
+}
+
+function requireText(value, label, maxLength) {
+  const normalized = value?.trim();
+  if (!normalized) {
+    throw new Error(`${label} is required.`);
+  }
+  if (normalized.length > maxLength) {
+    throw new Error(`${label} must be ${maxLength} characters or fewer.`);
+  }
+  return normalized;
+}
+
+function isBoundedText(value, maxLength) {
+  return typeof value === "string" &&
+    value.trim() !== "" &&
+    value.length <= maxLength;
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readValue(args, index, flag) {
+  const value = args[index];
+  if (!value) {
+    throw new Error(`${flag} needs a value.`);
+  }
+  return value;
+}
+
+function readInteger(args, index, flag) {
+  const value = readValue(args, index, flag);
+  if (!/^\d+$/.test(value)) {
+    throw new Error(`${flag} needs a non-negative integer.`);
+  }
+  return Number(value);
+}
+
+function printHelp() {
+  console.log(`DevFlow dashboard activity helper
+
+Usage:
+  node <helper> start --command feature --summary "Specifying feature 3" --boundary reviewed
+  node <helper> update --status blocked --summary "A product decision is required" --resume "/feature 3"
+  node <helper> finish --status ready --summary "Feature specification ready"
+  node <helper> reset
+
+Options:
+  --command         DevFlow command name, required for start
+  --summary         Short activity summary
+  --detail          Concise safe detail
+  --boundary        read-only, reviewed, or local-only
+  --status          update: running, blocked, or ready; finish: ready or completed
+  --resume          Safe recovery command
+  --feature-id      Build-plan feature ID
+  --feature-title   Feature, fix, or rollback title
+  --current         Completed progress count
+  --total           Total progress count
+  --label           Progress unit label
+  --target, -t      Project directory, defaults to the current directory
+  --help, -h        Show help`);
+}
+
+main().catch((error) => {
+  console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});

package/template/.claude/skills/feature/SKILL.md

@@ -6,6 +6,8 @@ argument-hint: "[{number, name, DISC-id, or IDEA-id}]"
 
 # feature - turn a build-plan feature into a buildable spec
 
+**Context reuse:** Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.
+
 **First action:** Before project inspection, preflight, or any other tool call,
 publish `running` to `devflow/.state/run.json` using the dashboard activity
 contract in `AGENTS.md`.

package/template/.claude/skills/feature/reference/feature-spec-template.md

@@ -0,0 +1,82 @@
+# 📐 [{xxx-slug}] {title}
+
+> **Status**: In-Progress  
+> **Track**: Fast-Track (Task-Isolated Living Spec Mode - Feature)  
+> **Category**: Feature  
+> **Source**: `devflow/build-plan.md: Feature {n}` & `devflow/discoveries/{DISC-ID}/discovery.md`  
+> **Branch**: `feature/{xxx-slug}`  
+> **Started Date**: {YYYY-MM-DD}  
+> **Delivered Date**: TBD  
+> **Owner**: DevFlow Core Framework Team & AI  
+
+---
+
+## 1. Specification & Scope
+
+### 1.1 Problem Statement
+{คำอธิบายปัญหาและที่มาของความจำเป็นในการพัฒนาฟีเจอร์นี้}
+
+### 1.2 In-Scope
+1. {ขอบเขตการทำงานข้อที่ 1}
+2. {ขอบเขตการทำงานข้อที่ 2}
+
+### 1.3 Out-of-Scope
+- {สิ่งที่อยู่นอกเหนือขอบเขตหรือไม่ทำในรอบนี้}
+
+### 1.4 Acceptance Criteria (เกณฑ์การยอมรับ)
+- [ ] **AC-1**: {เกณฑ์การตรวจรับข้อที่ 1}
+- [ ] **AC-2**: {เกณฑ์การตรวจรับข้อที่ 2}
+
+---
+
+## 2. Plan & Test Strategy
+
+### 2.1 Files Modified / Created
+- `{file-path}` [NEW | MODIFY | DELETE]
+
+### 2.2 Quality Gates & Sensitivity Check
+- **Quality Gate Policy (`independentReview`)**: `manual` | `always` | `when-sensitive`
+- **UI Evidence / Browser Tests**: {Not applicable | Playwright / BrowserOS Neo}
+- **Review Strategy**: One feature-level review packet at completion
+
+### 2.3 Test Decision: Required (TDD) | Optional
+- **Rationale**: {เหตุผลความจำเป็นในการเขียน Unit Tests / TDD}
+
+---
+
+## 3. Implementation Checklist (Strict TDD)
+
+- [ ] **Task 1: {หัวข้องานที่ 1}**
+  - [ ] 1.1 `[TDD-Red]`: {เขียน Test เคสล้มเหลว}
+  - [ ] 1.2 `[TDD-Green]`: {เขียนโค้ดขั้นต่ำเพื่อให้ Test ผ่าน}
+  - [ ] 1.3 `[TDD-Refactor]`: {Refactor และตรวจให้ 100% Tests Green}
+
+- [ ] **Task 2: {หัวข้องานที่ 2}**
+  - [ ] 2.1 `[TDD-Red]`: ...
+  - [ ] 2.2 `[TDD-Green]`: ...
+  - [ ] 2.3 `[TDD-Refactor]`: ...
+
+---
+
+## 4. Verification Evidence Matrix
+
+### ⚖️ Axis 1: Standards, Architecture & Quality Gate
+- **Type Safety & Build Integrity**: TBD
+- **Automated Test Matrix**: TBD
+- **Static Contract Verification**: TBD
+- **Package Smoke Test**: TBD
+- **Findings Ledger**: ตรวจสอบ `findings.md` สะอาด 100%
+
+### 🎯 Axis 2: Spec Fidelity & Behavioral Acceptance Gate
+- [ ] **AC-1**: {หลักฐานการผ่านเกณฑ์ข้อที่ 1}
+- [ ] **AC-2**: {หลักฐานการผ่านเกณฑ์ข้อที่ 2}
+
+---
+
+## 5. Delivery Verification & Independent Receipt
+
+- **Delivery Date**: TBD
+- **Verification Verdict**: TBD
+- **Framework Tests**: TBD
+- **Static Contract**: TBD
+- **Package Smoke Test**: TBD

package/template/.claude/skills/implement/SKILL.md

@@ -6,6 +6,8 @@ argument-hint: "[{run-id, number, or name}]"
 
 # implement - build the target spec, one reviewed step at a time
 
+**Context reuse:** Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.
+
 **First action:** Before project inspection, preflight, or any other tool call,
 publish `running` to `devflow/.state/run.json` using the dashboard activity
 contract in `AGENTS.md`.
@@ -81,41 +83,7 @@ instead of creating a new one.
 
 ### Type: Rollback safeguard
 
-For a rollback spec, do not hand-delete the old feature and do not run a whole
-commit `git revert`. Completed feature commits also contain Blueprint history and
-plan bookkeeping, while `devflow/context/{xxx-slug}/spec.md` now contains the active rollback
-spec. Reversing the whole commit would damage that state.
-
-Before the first rollback build step:
-
-1. Re-resolve the target archive's introducing commit and confirm it matches the
-   full Target commit SHA recorded in the approved spec.
-2. Confirm the target is an ancestor of `HEAD`, has the recorded single parent,
-   and the only dirty path before applying the patch is the approved rollback
-   spec. Stop on drift.
-3. Preview the target's product diff while excluding `.agents/**`, `.claude/**`,
-   `devflow/**`, `AGENTS.md`, `CLAUDE.md`, and
-   `prototypes/**`. Confirm the preview is non-empty and matches the Product
-   paths in the spec.
-4. Apply that product diff in reverse with three-way conflict detection and
-   stage it. Substitute the two approved full SHAs before running:
-
-       git diff --binary <target-parent> <target-commit> -- . \
-         ':(exclude).agents/**' \
-         ':(exclude).claude/**' ':(exclude)devflow/**' \
-         ':(exclude)AGENTS.md' ':(exclude)CLAUDE.md' \
-         ':(exclude)prototypes/**' |
-         git apply --reverse --3way --index
-
-   Never omit the protected pathspec exclusions for convenience.
-5. Show both `git diff --cached` and `git status`. Confirm no protected path is
-   staged or modified before presenting the step for review.
-
-If the reverse patch conflicts, stop and report the exact paths and later commit
-that appears involved. Do not auto-resolve, discard, stash, reset, or switch to a
-broad checkout. Ask whether to resolve only the conflict allowed by the approved
-spec or abandon the attempt. A cascade into another completed feature needs a
-new rollback plan.
+When implementing a rollback task, follow the exact safety procedure in `reference/rollback-implementation.md`.
 
 ## Step 2 - build one step, review, iterate, checkpoint (Strict TDD)
 

package/template/.claude/skills/implement/reference/rollback-implementation.md

@@ -0,0 +1,35 @@
+# Rollback implementation safeguard
+
+Use this only when `stage.md` / `spec.md` indicates a rollback task.
+
+Do not hand-delete the old feature and do not run a whole-commit `git revert`.
+The completed commit also contains DevFlow history and plan bookkeeping.
+
+Before the first rollback step:
+
+1. Read `Target commit` and `Target parent`. Stop unless both values match
+   `^[0-9a-f]{40}$`.
+2. Resolve the archive's introducing commit and verify it has exactly one parent.
+   Stop on a merge target. Confirm the resolved commit exactly equals `Target
+   commit` and the resolved parent exactly equals `Target parent`.
+3. Confirm the target is an ancestor of `HEAD` and the approved rollback spec is
+   the only dirty path. Stop on drift.
+4. Preview the target's product diff while excluding `.agents/**`,
+   `.claude/**`, `devflow/**`, `AGENTS.md`, `CLAUDE.md`, and `prototypes/**`.
+   Confirm it is non-empty and matches the Product paths in the spec.
+5. Apply only the resolved product diff in reverse with three-way conflict
+   detection. Use only the resolved full SHA values:
+
+       git diff --binary <target-parent> <target-commit> -- . \
+         ':(exclude).agents/**' \
+         ':(exclude).claude/**' ':(exclude)devflow/**' \
+         ':(exclude)AGENTS.md' ':(exclude)CLAUDE.md' \
+         ':(exclude)prototypes/**' |
+         git apply --reverse --3way --index
+
+6. Show the staged diff and status. Stop if any protected path is staged or
+   modified.
+
+If the reverse patch conflicts, report the exact paths and later commit involved.
+Do not auto-resolve, discard, stash, reset, or broaden the rollback. Ask whether
+to resolve only the approved conflict or abandon the attempt.