@haposoft/cafekit 0.8.9 → 0.8.10

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.10-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)
 
@@ -49,6 +49,7 @@ Claude Code install targets:
 ├── skills/
 ├── agents/
 ├── hooks/
+├── cafekit.json
 ├── status.cjs
 ├── runtime.json
 ├── settings.json
@@ -61,6 +62,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;
@@ -1065,6 +1115,8 @@ async function main() {
         copyGeminiFile(platformKey, results, installerOptions);
       }
 
+      writePlatformVersionMetadata(platformKey, results);
+
       results.targets.push(platform.commandsDir);
       console.log();
     }
@@ -1085,6 +1137,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.10",
   "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/scripts/validate-spec-output.cjs

@@ -93,7 +93,7 @@ function validateTaskSections(taskPath, content, errors) {
   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 hasEvidence =
     hasHeading(content, 'Evidence') ||
     hasHeading(content, 'Task Test Plan & Verification Evidence') ||

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
 
@@ -350,6 +351,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)

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

@@ -10,6 +10,24 @@ 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.
+
 ## Auto-Decision: When to Red Team vs Validate
 
 The system evaluates the spec and picks the appropriate review mode:
@@ -45,6 +63,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 +245,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`
@@ -241,7 +262,7 @@ Before declaring validation complete:
 #### Step 8: Final Status Write-Back
 - Update `spec.json.updated_at` to the reconciliation time
 - 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 +277,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)
 ```