@xenonbyte/da-vinci-workflow 0.2.3 → 0.2.5

package/lib/worktree-preflight.js

@@ -0,0 +1,214 @@
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const { STATUS } = require("./workflow-contract");
+
+function runGit(projectRoot, args) {
+  return spawnSync("git", args, {
+    cwd: projectRoot,
+    encoding: "utf8",
+    maxBuffer: 8 * 1024 * 1024
+  });
+}
+
+function checkIgnoredDirectory(projectRoot, directoryPath) {
+  const relativePath = path.relative(projectRoot, directoryPath) || path.basename(directoryPath);
+  const result = runGit(projectRoot, ["check-ignore", relativePath]);
+  if (result.error) {
+    return {
+      directory: directoryPath,
+      relativePath,
+      ignored: false,
+      error: `failed to execute git check-ignore: ${result.error.message || "unknown error"}`
+    };
+  }
+  if (result.status === 0) {
+    return {
+      directory: directoryPath,
+      relativePath,
+      ignored: true,
+      error: null
+    };
+  }
+  if (result.status === 1) {
+    return {
+      directory: directoryPath,
+      relativePath,
+      ignored: false,
+      error: null
+    };
+  }
+  const statusText = Number.isFinite(result.status) ? `exit ${result.status}` : "unknown status";
+  const stderr = String(result.stderr || "").trim();
+  return {
+    directory: directoryPath,
+    relativePath,
+    ignored: false,
+    error: `git check-ignore failed (${statusText})${stderr ? `: ${stderr}` : ""}`
+  };
+}
+
+function readPackageScripts(projectRoot) {
+  const packagePath = path.join(projectRoot, "package.json");
+  if (!fs.existsSync(packagePath)) {
+    return {};
+  }
+  try {
+    const payload = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+    return payload && payload.scripts && typeof payload.scripts === "object" ? payload.scripts : {};
+  } catch (_error) {
+    return {};
+  }
+}
+
+function runWorktreePreflight(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const findings = {
+    failures: [],
+    warnings: [],
+    notes: []
+  };
+
+  const candidateDirs = [".worktrees", "worktrees"]
+    .map((name) => path.join(projectRoot, name))
+    .filter((candidate) => fs.existsSync(candidate));
+  const gitStatus = runGit(projectRoot, ["status", "--porcelain"]);
+  const gitStatusSummary = {
+    healthy: false,
+    exitCode: Number.isFinite(gitStatus.status) ? gitStatus.status : null,
+    message: ""
+  };
+  const dirtyEntries = [];
+  if (gitStatus.error) {
+    gitStatusSummary.message = `failed to execute git status: ${gitStatus.error.message || "unknown error"}`;
+    findings.warnings.push(
+      "Unable to execute `git status`; worktree-isolation preflight cannot be trusted in the current environment."
+    );
+  } else if (gitStatus.status !== 0) {
+    const stderr = String(gitStatus.stderr || "").trim();
+    gitStatusSummary.message = stderr || "git status returned non-zero exit";
+    if (/not a git repository/i.test(stderr)) {
+      findings.warnings.push(
+        "Current project is not a git repository; worktree-isolation preflight is advisory-only and recommends isolation."
+      );
+    } else {
+      findings.warnings.push(
+        `git status failed (${gitStatusSummary.exitCode !== null ? gitStatusSummary.exitCode : "unknown exit"}); worktree-isolation checks may be unreliable.`
+      );
+    }
+  } else {
+    gitStatusSummary.healthy = true;
+    const lines = String(gitStatus.stdout || "")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean);
+    dirtyEntries.push(...lines);
+  }
+
+  const ignoreChecks = [];
+  if (candidateDirs.length > 0) {
+    if (!gitStatusSummary.healthy) {
+      findings.warnings.push(
+        "Skipped git-ignore safety checks for worktree directories because git status is unavailable."
+      );
+    } else {
+      for (const candidate of candidateDirs) {
+        const check = checkIgnoredDirectory(projectRoot, candidate);
+        ignoreChecks.push(check);
+        if (check.error) {
+          findings.warnings.push(
+            `Unable to verify git-ignore state for ${check.relativePath}: ${check.error}`
+          );
+          continue;
+        }
+        if (!check.ignored) {
+          findings.failures.push(
+            `Worktree directory ${check.relativePath} is not git-ignored; isolation setup is unsafe.`
+          );
+        } else {
+          findings.notes.push(`Worktree directory ${check.relativePath} is git-ignored.`);
+        }
+      }
+    }
+  }
+
+  if (dirtyEntries.length > 0) {
+    findings.warnings.push(
+      `Workspace is dirty (${dirtyEntries.length} change(s)); isolated execution is recommended before bounded parallel work.`
+    );
+  }
+
+  const scripts = readPackageScripts(projectRoot);
+  if (!scripts.test) {
+    findings.warnings.push("No `test` script found in package.json; baseline verification heuristics are weak.");
+  } else {
+    findings.notes.push("Detected package.json test script for baseline verification checks.");
+  }
+
+  if (candidateDirs.length === 0) {
+    findings.notes.push("No project-local worktree directory found (.worktrees/ or worktrees/).");
+  }
+
+  const status =
+    findings.failures.length > 0
+      ? STATUS.BLOCK
+      : findings.warnings.length > 0
+      ? STATUS.WARN
+      : STATUS.PASS;
+
+  const recommendedIsolation =
+    dirtyEntries.length > 0 ||
+    options.parallelPreferred === true ||
+    findings.failures.length > 0 ||
+    !gitStatusSummary.healthy;
+
+  return {
+    status,
+    advisory: true,
+    projectRoot,
+    failures: findings.failures,
+    warnings: findings.warnings,
+    notes: findings.notes,
+    summary: {
+      worktreeDirectories: candidateDirs.map((candidate) => path.relative(projectRoot, candidate)),
+      ignoreChecks,
+      dirtyEntries: dirtyEntries.length,
+      gitStatus: gitStatusSummary,
+      recommendedIsolation
+    }
+  };
+}
+
+function formatWorktreePreflightReport(result) {
+  const lines = [
+    "Worktree preflight",
+    `Project: ${result.projectRoot}`,
+    `Status: ${result.status}`,
+    `Advisory: ${result.advisory ? "yes" : "no"}`,
+    `Recommended isolation: ${result.summary.recommendedIsolation ? "yes" : "no"}`
+  ];
+  if (result.failures.length > 0) {
+    lines.push("Failures:");
+    for (const failure of result.failures) {
+      lines.push(`- ${failure}`);
+    }
+  }
+  if (result.warnings.length > 0) {
+    lines.push("Warnings:");
+    for (const warning of result.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+  if (result.notes.length > 0) {
+    lines.push("Notes:");
+    for (const note of result.notes) {
+      lines.push(`- ${note}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  runWorktreePreflight,
+  formatWorktreePreflightReport
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Requirement-to-design-to-code workflow skill for Codex, Claude, and Gemini",
   "bin": {
     "da-vinci": "bin/da-vinci.js",

package/references/artifact-templates.md

@@ -662,21 +662,46 @@ Use this structure:
 ```md
 # Tasks
 
+## Discipline Markers (Machine-readable)
+- design_approval: approved @ <ISO-8601 timestamp>
+- plan_self_review: complete @ <ISO-8601 timestamp>
+- operator_review_ack: accepted @ <ISO-8601 timestamp>
+
 ## 1. Setup
-- [ ] Project or page setup
+- [ ] 1.1 Project or page setup
+- Target files: `<repo path>`
+- Verification command: `<exact command>`
+- Execution intent: `serial`
+- Review intent: `true`
 
 ## 2. UI Structure
-- [ ] Implement major sections from Pencil
+- [ ] 2.1 Implement major sections from Pencil
+- Target files: `<repo path>`
+- Verification command: `<exact command>`
+- Execution intent: `bounded_parallel`
+- Review intent: `true`
 
 ## 3. Behavior
-- [ ] Implement states and interactions from spec
+- [ ] 3.1 Implement states and interactions from spec
+- Target files: `<repo path>`
+- Verification command: `<exact command>`
+- Execution intent: `review_required`
+- Review intent: `true`
 
 ## 4. Integration
-- [ ] Wire required data or services
+- [ ] 4.1 Wire required data or services
+- Target files: `<repo path>`
+- Verification command: `<exact command>`
+- Execution intent: `serial`
+- Review intent: `true`
 
 ## 5. Verification
-- [ ] Check requirement coverage
-- [ ] Check Pencil coverage
+- [ ] 5.1 Check requirement coverage
+- [ ] 5.2 Check Pencil coverage
+- Verification command: `da-vinci verify-bindings --project <path> [--change <id>]`
+- Verification command: `da-vinci verify-implementation --project <path> [--change <id>]`
+- Verification command: `da-vinci verify-structure --project <path> [--change <id>]`
+- Verification command: `da-vinci verify-coverage --project <path> [--change <id>]`
 
 ## Metadata Hints (Machine-readable)
 - Spec slice: `<slice-id>`
@@ -699,8 +724,12 @@ Prefer top-level task groups. They are required for execution checkpoints.
 Additional guidance:
 
 - keep top-level task groups in `X. Title` form to support task-group execution metadata
+- keep checklist numbering in `X.Y` form and avoid placeholder wording such as `TBD` or `TODO`
+- keep discipline markers parseable and timestamped so stale approvals can be detected
 - include explicit verification actions so `lint-tasks` and `verify-coverage` can consume intent deterministically
 - keep task text concrete enough that coverage tools can map behavior and state work
+- include explicit file targets or code-area references for each task group
+- include execution intent (`serial`, `bounded_parallel`, or `review_required`) and review intent metadata per group
 
 Recommended path:
 
@@ -780,6 +809,27 @@ Use this structure:
 - explicit test evidence summary
 - open gaps
 
+## Task Review Evidence
+### Task Review <task-group-id> (spec)
+- Status: PASS / WARN / BLOCK
+- Reviewer: `<name>`
+- Summary: `<summary>`
+- Issues: `<issue list>`
+- Recorded at: `<ISO-8601 timestamp>`
+
+### Task Review <task-group-id> (quality)
+- Status: PASS / WARN / BLOCK
+- Reviewer: `<name>`
+- Summary: `<summary>`
+- Issues: `<issue list>`
+- Recorded at: `<ISO-8601 timestamp>`
+
+## Verification Freshness
+- verification baseline timestamp
+- latest verify signal timestamps by surface
+- freshness outcome: `fresh` / `stale`
+- stale reasons when freshness is not satisfied
+
 ## Context Delta
 - Add concise entries after each `execution checkpoint`
 - Required fields: `time`, `checkpoint_type`, `goal`, `decision`, `constraints`, `impact`, `status`, `next_action`

package/references/skill-workflow-detail.md

@@ -0,0 +1,66 @@
+# Skill Workflow Detail (Stage-Specific)
+
+This file owns stage-specific operational detail moved out of core `SKILL.md`.
+Core `SKILL.md` remains the invariant contract and routing index.
+
+## Split Non-Goals
+
+- Do not change route truth (`requirements -> design -> tasks -> build -> verify`) by moving prose.
+- Do not weaken autonomous-by-default policy.
+- Do not redefine checkpoints or acceptance semantics implicitly through wording changes.
+- Do not duplicate moved sections back into `SKILL.md`, command assets, and references simultaneously.
+
+## Move Map
+
+The following sections were moved from core `SKILL.md` into owned references:
+
+- `Design Input Collection` -> `references/design-inputs.md`
+- `Default Workflow` -> `references/checkpoints.md` and `references/artifact-templates.md`
+- `Pencil Generation Rules` -> `references/pencil-design-to-code.md` and `references/layout-hygiene.md`
+- `Default Artifacts` -> `references/artifact-templates.md`
+- `Prompt Entry Route Recipes` (detailed variants) -> `references/prompt-recipes.md`
+- `Mode-specific elaboration` -> `references/modes.md`
+- `Platform adapter elaboration` -> `references/platform-adapters.md`
+
+## Stage Detail Ownership
+
+Use this section when the current stage needs tactical instructions beyond core contract.
+
+### 1. Discovery & Planning
+
+- Ensure change root exists and active change id is unambiguous.
+- Keep proposal/spec/design/tasks artifacts synchronized with the selected mode.
+- Treat artifact drift as a blocker for execution confidence.
+
+### 2. Design Inputs & Page Mapping
+
+- Collect/confirm form factor, visual direction, and constraints from existing project truth first.
+- Resolve project page map and implementation-to-design bindings before design expansion.
+- Keep binding records explicit and parseable for downstream verification/scaffold commands.
+
+### 3. Pencil Design Execution
+
+- Keep `.da-vinci/designs/` reserved for project-local `.pen` sources.
+- Use Pencil session wrapper commands for autonomous runs:
+  - `da-vinci pencil-session begin --project <project-path> --pen <path>`
+  - `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+  - `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- Keep screenshot review and supervisor review records explicit when required.
+
+### 4. Build & Verification
+
+- `tasks.md` PASS/accepted WARN is the handoff into implementation, not completion.
+- During build, persist task execution and task review evidence with CLI envelopes.
+- Before completion-facing wording, require fresh verification evidence and completion audit pass.
+
+### 5. Scaffold Guidance
+
+- Scaffold output is reviewable TODO skeleton only, never final production code.
+- Keep traversal and output-root safety guarantees intact.
+- Preserve known implementation landing shape when available.
+
+## Maintainer Guidance
+
+- New invariant policy belongs in core `SKILL.md`.
+- New stage-specific procedure belongs in one owned reference file, then linked from core `Load References On Demand`.
+- When moving text, update this move map in the same patch.