@haposoft/cafekit 0.8.9 → 0.8.11

package/README.md

@@ -2,7 +2,7 @@
 
 > Claude Code-first spec-driven workflow and runtime bundle for AI coding assistants.
 
-[![Version](https://img.shields.io/badge/version-0.8.0-blue.svg)](https://github.com/haposoft/cafekit)
+[![Version](https://img.shields.io/badge/version-0.8.11-blue.svg)](https://github.com/haposoft/cafekit)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude%20Code](https://img.shields.io/badge/Claude%20Code-Primary-orange.svg)](https://claude.ai/code)
 
@@ -46,9 +46,11 @@ Claude Code install targets:
 
 ```text
 .claude/
+├── .gitignore
 ├── skills/
 ├── agents/
 ├── hooks/
+├── cafekit.json
 ├── status.cjs
 ├── runtime.json
 ├── settings.json
@@ -61,6 +63,13 @@ Managed runtime features include:
 - rule/context injection
 - spec state awareness
 - safe settings merge on reinstall
+- installed CafeKit version tracking in `.claude/cafekit.json`
+
+To check the installed CafeKit package version:
+
+```bash
+cat .claude/cafekit.json
+```
 
 ## Core Skills
 

package/bin/install.js

@@ -20,6 +20,7 @@ const os = require('os');
 const readline = require('readline');
 const { execSync } = require('child_process');
 const packageJson = require('../package.json');
+const INSTALL_COMMAND = `npx ${packageJson.name}@${packageJson.version}`;
 
 function validateManifestV2(manifest) {
   if (!manifest || manifest.version !== 2) return false;
@@ -339,6 +340,55 @@ function ensureWorkflowDependencies(platformKey, platform, results, options = {}
   });
 }
 
+function readJsonFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writePlatformVersionMetadata(platformKey, results) {
+  const platform = PLATFORMS[platformKey];
+  const targetPath = path.join(platform.folder, 'cafekit.json');
+  const targetExists = fs.existsSync(targetPath);
+  const existingMetadata = readJsonFile(targetPath);
+  const now = new Date().toISOString();
+  const previousVersion = typeof existingMetadata.version === 'string'
+    ? existingMetadata.version
+    : null;
+
+  const metadata = {
+    schemaVersion: 1,
+    packageName: packageJson.name,
+    version: packageJson.version,
+    platform: platform.id,
+    platformName: platform.name,
+    installedAt: existingMetadata.installedAt || now,
+    lastInstalledAt: now,
+    installCommand: INSTALL_COMMAND
+  };
+
+  if (previousVersion && previousVersion !== packageJson.version) {
+    metadata.previousVersion = previousVersion;
+  }
+
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+
+  if (targetExists) {
+    console.log(`  ↻ Version metadata updated: ${targetPath}`);
+    results.updated++;
+  } else {
+    console.log(`  ✓ Version metadata installed: ${targetPath}`);
+    results.copied++;
+  }
+}
+
 function getPlatformSpecFiles(platformKey) {
   if (platformKey === 'claude') {
     const manifestCommands = CLAUDE_MIGRATION_MANIFEST?.commands?.core;
@@ -701,7 +751,8 @@ function copyClaudeRuntimeFiles(platformKey, results, options = {}) {
 
   manifest.runtime.files.forEach(relPath => {
     const srcPath = path.join(srcBase, relPath);
-    const targetPath = path.join(targetBase, relPath);
+    const targetRelPath = relPath === 'gitignore' ? '.gitignore' : relPath;
+    const targetPath = path.join(targetBase, targetRelPath);
 
     if (!fs.existsSync(srcPath)) {
       console.log(`  ⚠ Runtime file not found: ${relPath}`);
@@ -717,10 +768,10 @@ function copyClaudeRuntimeFiles(platformKey, results, options = {}) {
       fs.copyFileSync(srcPath, targetPath);
 
       if (targetExists) {
-        console.log(`  ↻ Runtime updated: ${relPath}`);
+        console.log(`  ↻ Runtime updated: ${targetRelPath}`);
         results.updated++;
       } else {
-        console.log(`  ✓ Runtime installed: ${relPath}`);
+        console.log(`  ✓ Runtime installed: ${targetRelPath}`);
         results.copied++;
       }
     } else {
@@ -1065,6 +1116,8 @@ async function main() {
         copyGeminiFile(platformKey, results, installerOptions);
       }
 
+      writePlatformVersionMetadata(platformKey, results);
+
       results.targets.push(platform.commandsDir);
       console.log();
     }
@@ -1085,6 +1138,7 @@ async function main() {
     console.log();
     console.log(`  Copied Files:       ${results.copied}`);
     console.log(`  Updated Files:      ${results.updated}`);
+    console.log(`  CafeKit Version:    ${packageJson.version}`);
     console.log(`  Skipped Files:      ${results.skipped}`);
     console.log(`  Installed Skills:   ${results.installedSkills > 0 ? 'Yes ✓' : 'No'}`);
     console.log(`  Dependency Checks:  ${results.dependencyChecks}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.9",
+  "version": "0.8.11",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/gitignore

@@ -7,10 +7,12 @@
 skills/.venv/
 .venv/
 venv/
+skills/**/node_modules/
 __pycache__/
 *.pyc
 
-# System generated or logs
+# System generated state, caches, and logs
+session-state/
 hooks/.logs/
 agent-memory/
 settings.bak.json

package/src/claude/migration-manifest.json

@@ -68,6 +68,7 @@
   },
   "runtime": {
     "files": [
+      "gitignore",
       "runtime.json",
       "status.cjs",
       "hooks/session.cjs",

package/src/claude/scripts/validate-spec-output.cjs

@@ -86,23 +86,31 @@ function extractRequirementIds(requirementsText) {
 }
 
 function validateTaskSections(taskPath, content, errors) {
-  const hasContext =
-    hasHeading(content, 'Context') ||
-    hasHeading(content, 'Objective') ||
-    hasHeading(content, 'Goal');
+  const hasContext = hasHeading(content, 'Context');
+  const hasConstraints = hasHeading(content, 'Constraints');
   const hasSteps =
     hasHeading(content, 'Steps') || hasHeading(content, 'Implementation Steps');
   const hasRequirements =
-    hasHeading(content, 'Requirements') || /^\*\*Requirement:\*\*/m.test(content);
+    hasHeading(content, 'Requirements') || /_Requirements:\s*[^_\n]+_/i.test(content);
+  const hasRelatedFiles = hasHeading(content, 'Related Files');
+  const hasCompletionCriteria = hasHeading(content, 'Completion Criteria');
   const hasEvidence =
     hasHeading(content, 'Evidence') ||
     hasHeading(content, 'Task Test Plan & Verification Evidence') ||
     hasHeading(content, 'Verification & Evidence');
+  const hasRiskAssessment = hasHeading(content, 'Risk Assessment');
 
-  if (!hasContext) errors.push(`${taskPath}: missing Context/Objective/Goal`);
+  if (!hasContext) errors.push(`${taskPath}: missing Context`);
+  if (!hasConstraints) errors.push(`${taskPath}: missing Constraints`);
   if (!hasSteps) errors.push(`${taskPath}: missing Steps/Implementation Steps`);
   if (!hasRequirements) errors.push(`${taskPath}: missing Requirements mapping`);
+  if (!hasRelatedFiles) errors.push(`${taskPath}: missing Related Files`);
+  if (!hasCompletionCriteria) errors.push(`${taskPath}: missing Completion Criteria`);
   if (!hasEvidence) errors.push(`${taskPath}: missing Evidence or task test plan`);
+  if (!hasRiskAssessment) errors.push(`${taskPath}: missing Risk Assessment`);
+  if (hasEvidence && !/Runtime reachability verification/i.test(content)) {
+    errors.push(`${taskPath}: missing Runtime reachability verification`);
+  }
 }
 
 function validateSpec(specDir) {
@@ -187,6 +195,28 @@ function validateSpec(specDir) {
     errors.push('tasks/: feature work cannot be entirely R0; reserve R0 for shared foundation tasks');
   }
 
+  const validationRecommended = spec.design_context?.validation_recommended === true;
+  if (taskFiles.length >= 5 && !validationRecommended) {
+    errors.push('spec.json.design_context.validation_recommended: must be true for specs with 5+ task files');
+  }
+  if (
+    (validationRecommended || taskFiles.length >= 5) &&
+    spec.ready_for_implementation === true &&
+    spec.validation?.status !== 'completed'
+  ) {
+    errors.push(
+      'spec.json.ready_for_implementation: cannot be true when validation is recommended but validation.status is not completed',
+    );
+  }
+  if (spec.validation?.status === 'completed') {
+    if (!spec.timestamps?.validation_done) {
+      errors.push('spec.json.timestamps.validation_done: required when validation.status is completed');
+    }
+    if (taskFiles.length >= 5 && !spec.timestamps?.review_done) {
+      errors.push('spec.json.timestamps.review_done: required for 5+ task specs after validation');
+    }
+  }
+
   const requirementsPath = path.join(specDir, 'requirements.md');
   const designPath = path.join(specDir, 'design.md');
   const researchPath = path.join(specDir, 'research.md');

package/src/claude/skills/specs/SKILL.md

@@ -137,6 +137,7 @@ The system MUST NOT execute Steps 1-8. Instead, load `references/review.md` and
 5. **MUST NOT create implementation code files** (`.ts`, `.js`, `.py`, etc.). The validate workflow produces ONLY markdown spec documents and reports. If a fix requires a new shared module, describe it in the relevant task file instead of creating the actual code file.
 6. **MUST NOT over-engineer fixes.** Apply YAGNI — if user says "configure later", add an abstraction note to the task, do NOT generate 4 concrete provider implementations.
 7. **MUST follow auto-decision table exactly.** Count task files + scan for keywords → pick mode. No self-justification to override the table result.
+8. **MUST run deterministic validator.** Before reporting validation PASS, run `node .claude/scripts/validate-spec-output.cjs specs/<feature>`. If it exits non-zero, validation is FAIL/BLOCKED, `ready_for_implementation` remains `false`, and output MUST NOT suggest `/hapo:develop`.
 
 ## Workflow Diagram
 
@@ -321,12 +322,15 @@ Each task file MUST be **self-contained and implementation-ready** — detailed
 
 **Structure per task file:**
 1. **Context** — why this task exists, current state, target outcome, relevant exact files.
-2. **Steps** — concise implementation checklist with business intent and code-level detail.
-3. **Requirements** — list requirement IDs and acceptance criteria covered by this task.
-4. **Related Files** — table with exact paths, action type, and descriptions when paths are known; otherwise run scout first.
-5. **Completion Criteria** — observable, testable criteria.
-6. **Evidence** — automated command(s), artifact/runtime proof, negative-path proof, and runtime reachability proof.
-7. **Risk Assessment** — table with risk, severity, mitigation.
+2. **Constraints** — MUST / SHOULD / MUST NOT / SCOPE guardrails.
+3. **Steps** — concise implementation checklist with business intent and code-level detail.
+4. **Requirements** — list requirement IDs and acceptance criteria covered by this task.
+5. **Related Files** — table with exact paths, action type, and descriptions when paths are known; otherwise run scout first.
+6. **Completion Criteria** — observable, testable criteria.
+7. **Evidence** — automated command(s), artifact/runtime proof, negative-path proof, and runtime reachability proof.
+8. **Risk Assessment** — table with risk, severity, mitigation.
+
+**Template fidelity is mandatory:** preserve the task template headings exactly. Do NOT rename `## Context` to `## Objective`, do NOT replace `## Completion Criteria` with prose, do NOT remove `## Related Files`, `## Constraints`, or `## Risk Assessment`, and do NOT collapse `## Evidence` into generic QA scenarios. Compact wording is fine; missing sections are invalid.
 
 **Parallel markers:** Append `(P)` to tasks that can run concurrently (no data dependency, no shared files, no prerequisite approval from another task). Tasks serving DIFFERENT requirements are often parallelizable.
 
@@ -350,6 +354,7 @@ Load: `references/review.md` + `rules/design-review.md`
 - **PROHIBITION:** The system MUST NOT skip Red Team because of a prior code-auditor review. Code review ≠ Spec review.
 - **PROHIBITION:** The system MUST NOT create `.ts`, `.js`, `.py` or any implementation files during validation. Spec-only outputs.
 - **Reconciliation Rule:** `validation.status = "completed"` is forbidden until all accepted findings and validation decisions are physically propagated into `requirements.md`, `design.md`, `tasks/*.md`, and `spec.json` where applicable.
+- **Deterministic Gate:** Run `node .claude/scripts/validate-spec-output.cjs specs/<feature>` after all fixes and before final output. Script failure overrides any LLM checklist result and blocks `ready_for_implementation = true`.
 
 ### Step 9.5: Finalization Audit (MANDATORY)
 - Re-scan the `tasks/` directory and rebuild `spec.json.task_files` from the real filesystem (sorted, relative paths)
@@ -366,6 +371,7 @@ Load: `references/review.md` + `rules/design-review.md`
 - FAIL if a task creates runtime-facing artifacts but neither proves reachability from an entrypoint/caller nor names a later integration task responsible for wiring them.
 - FAIL if a UI/app/runtime spec has multiple user-facing task outputs but no final integration/reachability task or final integration section.
 - FAIL if accepted validation decisions exist in reports but are not reflected in the implementation-facing sections of affected artifacts (`Context`, `Steps`, `Requirements`, `Completion Criteria`, `Evidence`, canonical contracts, or requirements text).
+- FAIL if any generated task replaces the required task template with a reduced `Objective` / `Steps` / `Evidence` shape. `Context`, `Constraints`, `Related Files`, `Completion Criteria`, `Evidence`, and `Risk Assessment` must all remain present.
 - FAIL if the spec scope/provider was switched away from Anthropic/Claude but `requirements.md`, `design.md`, or `tasks/*.md` still contain stale provider-specific strings such as `Claude API`, `Haiku`, or `haiku_reachable`. `research.md` is the only allowed place for historical cost comparisons.
 - FAIL if privacy/delete-data work lacks a single canonical deletion policy. The design MUST explicitly choose either:
   1. hard-delete with no re-registration lock, or
@@ -437,7 +443,7 @@ Task paths that omit the `task-` prefix or use non-padded sequence numbers (for
 6. `task_registry` matches the real filesystem and does not omit any task file
 7. If `design_context.validation_recommended = true`, `validation.status = "completed"` (or another explicit user-accepted risk state that is recorded)
 
-If any approval is `false`, `ready_for_implementation` MUST remain `false`.
+If any approval is `false`, `ready_for_implementation` MUST remain `false`. If the spec has 5+ task files, `ready_for_implementation` MUST remain `false` until `/hapo:specs <feature> --validate` completes Red Team + Validate and writes `validation.status = "completed"`.
 
 ## Output Structure
 

package/src/claude/skills/specs/references/review.md

@@ -10,6 +10,25 @@ Review a spec before implementation. The system auto-decides the review depth ba
 2. If not → check active spec (spec with `in_progress` status; accept legacy `in-progress` when reading existing files)
 3. If nothing found → ask user to specify path
 
+## Deterministic Validator Gate (MANDATORY)
+
+This gate is the hard source of truth for `hapo:specs --validate`. LLM red-team tables and markdown validation reports are advisory until this script passes.
+
+After resolving the spec path, run:
+
+```bash
+node .claude/scripts/validate-spec-output.cjs specs/<feature>
+```
+
+Required behavior:
+1. Run the validator once before the final PASS decision. If it fails, copy the exact failing categories into the validation findings/blockers and fix the physical spec artifacts.
+2. Red Team and Validate may continue while fixing issues, but they cannot approve the spec while validator errors remain.
+3. Run the validator again after every accepted Red Team / Validate fix set and before any final verdict.
+4. The final report MUST include the validator command and the final PASS/FAIL result.
+5. If the validator exits non-zero, final verdict is **FAIL / BLOCKED**, `validation.status` MUST NOT become `completed`, `ready_for_implementation` MUST remain `false`, and the output MUST NOT suggest `/hapo:develop`.
+6. A markdown checklist, manual QA table, or "all required sections present" claim cannot override validator failure.
+7. For specs with 5+ task files, a pre-review validator PASS only proves artifact shape. It does not mean implementation can start until Red Team + Validate finish, accepted fixes are propagated, and `spec.json.validation.status` is written as `completed`.
+
 ## Auto-Decision: When to Red Team vs Validate
 
 The system evaluates the spec and picks the appropriate review mode:
@@ -45,6 +64,7 @@ These rules override any self-reasoning or optimization the system may attempt:
 7. **Implementation-facing propagation is mandatory.** A decision that affects implementation is NOT considered applied if it only appears in `Risk Assessment`, `validate-log.md`, or `red-team-report.md`. It must update at least one of: `requirements.md`, `Canonical Contracts & Invariants`, `Context`, `Steps`, `Requirements`, `Completion Criteria`, or `Evidence`.
 8. **CafeKit command dialect only.** Validation output MUST use `/hapo:develop <feature>` as the implementation handoff. Never mention `/sdd:execute-spec`, `/sdd:*`, `/work`, `/code`, `/specs <feature> --approve`, `/hapo:specs <feature> --approve`, or non-CafeKit aliases.
 9. **CafeKit task filename convention only.** Task files MUST use `tasks/task-R{N}-{SEQ}-<slug>.md` with two-digit `SEQ` (for example `tasks/task-R0-01-project-scaffolding.md`). Files like `tasks/R0-1-project-scaffolding.md` are legacy/foreign format; rename them and update `spec.json.task_files`, `spec.json.task_registry`, and dependency references before passing validation.
+10. **Deterministic validator is mandatory.** The final validation verdict MUST be derived from `node .claude/scripts/validate-spec-output.cjs specs/<feature>`. If that command fails, report FAIL/BLOCKED and list the script output. Do NOT report PASS.
 
 ---
 
@@ -226,13 +246,15 @@ Save to `reports/validate-log.md`:
 Before declaring validation complete:
 1. Re-read `spec.json`, `requirements.md`, `design.md`, and all `tasks/task-*.md`
 2. Verify every accepted red-team finding and every validation action item is reflected in the correct physical file(s)
-3. Fail the audit if:
+3. Run `node .claude/scripts/validate-spec-output.cjs specs/<feature>` and keep the raw result visible
+4. Fail the audit if:
    - a report says "applied" but the file still contains the old text
    - stale provider strings remain after a provider change
    - delete-data/privacy artifacts mix multiple canonical policies
    - any task path fails the CafeKit `tasks/task-R{N}-{SEQ}-<slug>.md` naming convention
    - `spec.json.updated_at`, `timestamps.review_done`, or `timestamps.validation_done` do not reflect the final reviewed state
-4. Only after the audit passes may you:
+   - deterministic validator exits non-zero
+5. Only after the audit passes may you:
    - set `spec.json.validation.status = "completed"`
    - set `spec.json.timestamps.validation_done`
    - set `spec.json.timestamps.review_done`
@@ -240,8 +262,10 @@ Before declaring validation complete:
 
 #### Step 8: Final Status Write-Back
 - Update `spec.json.updated_at` to the reconciliation time
+- On final PASS, set `spec.json.validation.status = "completed"`, `spec.json.timestamps.validation_done`, and, when Red Team ran, `spec.json.timestamps.review_done`
+- On final PASS, set `spec.json.ready_for_implementation = true` only after the deterministic validator passes on the final physical artifacts
 - Ensure `red-team-report.md` and `validate-log.md` do not contradict `spec.json`
-- If reconciliation fails, keep `validation.status` as `not-run` or `in_progress` and list blockers explicitly
+- If reconciliation or deterministic validation fails, keep `validation.status` as `not-run` or `in_progress`, keep `ready_for_implementation = false`, list blockers explicitly, and do not provide an implementation handoff.
 
 ---
 
@@ -256,6 +280,7 @@ Red Team: {N} findings ({A} accepted, {R} rejected)
 Validate: {Q} questions asked, {D} decisions confirmed
 
 Files modified: {list}
+Deterministic validator: PASS via `node .claude/scripts/validate-spec-output.cjs specs/<feature>`
 
 📌 Next step: /hapo:develop <feature>    (ONLY if reconciliation audit passed)
 ```