@haposoft/cafekit 0.8.10 → 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.10-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,6 +46,7 @@ Claude Code install targets:
 
 ```text
 .claude/
+├── .gitignore
 ├── skills/
 ├── agents/
 ├── hooks/

package/bin/install.js

@@ -751,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}`);
@@ -767,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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.10",
+  "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') || /_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

@@ -322,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.
 
@@ -368,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
@@ -439,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

@@ -27,6 +27,7 @@ Required behavior:
 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
 
@@ -261,6 +262,8 @@ 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 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.