create-claude-rails 0.3.3 → 0.4.0

package/lib/cli.js

@@ -15,7 +15,7 @@ const MODULES = {
     name: 'Session Loop (orient + debrief)',
     description: 'Context continuity between sessions. Claude starts informed, ends by recording what happened.',
     mandatory: true,
-    templates: ['skills/orient', 'skills/debrief', 'skills/menu', 'hooks/stop-hook.md'],
+    templates: ['skills/orient', 'skills/debrief', 'skills/debrief/phases/upstream-feedback.md', 'skills/menu', 'hooks/stop-hook.md'],
   },
   'hooks': {
     name: 'Git Guardrails + Telemetry',
@@ -23,7 +23,7 @@ const MODULES = {
     mandatory: false,
     default: true,
     lean: true,
-    templates: ['hooks/git-guardrails.sh', 'hooks/skill-telemetry.sh', 'hooks/skill-tool-telemetry.sh'],
+    templates: ['hooks/git-guardrails.sh', 'hooks/cor-upstream-guard.sh', 'hooks/skill-telemetry.sh', 'hooks/skill-tool-telemetry.sh', 'scripts/cor-drift-check.cjs'],
   },
   'work-tracking': {
     name: 'Work Tracking (pib-db or markdown)',

package/lib/settings-merge.js

@@ -12,6 +12,15 @@ const DEFAULT_HOOKS = {
         },
       ],
     },
+    {
+      matcher: 'Edit|Write',
+      hooks: [
+        {
+          type: 'command',
+          command: '.claude/hooks/cor-upstream-guard.sh',
+        },
+      ],
+    },
   ],
   UserPromptSubmit: [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-rails",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Claude on Rails — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-rails": "bin/create-claude-rails.js"

package/templates/hooks/cor-upstream-guard.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# CoR Upstream Guard — PreToolUse hook for Edit and Write tool calls
+#
+# Blocks modifications to files managed by Claude on Rails. These files
+# are upstream-owned: updates come through /cor-upgrade, not direct edits.
+# Project-specific customization goes in _context.md and phase files.
+#
+# How it works:
+#   Reads .corrc.json manifest (list of CoR-installed files with hashes).
+#   If the target file_path is in the manifest, block the write.
+#
+# ROLLBACK: Comment out the PreToolUse entry for this hook in
+# .claude/settings.json to disable it immediately.
+#
+# Hook contract:
+#   Input: $CLAUDE_TOOL_INPUT has the tool use JSON with "file_path" field
+#   Output: JSON on stdout with { "decision": "block"|"allow", "reason": "..." }
+
+# Extract file_path from tool input
+FILE_PATH=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('file_path',''))" 2>/dev/null)
+
+if [ -z "$FILE_PATH" ]; then
+  echo '{"decision":"allow"}'
+  exit 0
+fi
+
+# Find the project root (where .corrc.json lives)
+# Walk up from current directory
+find_project_root() {
+  local dir="$PWD"
+  while [ "$dir" != "/" ]; do
+    if [ -f "$dir/.corrc.json" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+  done
+  return 1
+}
+
+PROJECT_ROOT=$(find_project_root)
+
+if [ -z "$PROJECT_ROOT" ]; then
+  # No .corrc.json found — not a CoR project, allow everything
+  echo '{"decision":"allow"}'
+  exit 0
+fi
+
+# Resolve file_path to a relative path from project root
+# Handle both absolute and relative paths
+if [[ "$FILE_PATH" = /* ]]; then
+  # Absolute path — make relative to project root
+  REL_PATH="${FILE_PATH#$PROJECT_ROOT/}"
+  # If the path didn't change, the file is outside the project
+  if [ "$REL_PATH" = "$FILE_PATH" ]; then
+    echo '{"decision":"allow"}'
+    exit 0
+  fi
+else
+  REL_PATH="$FILE_PATH"
+fi
+
+# Check if this relative path is in the manifest
+IN_MANIFEST=$(python3 -c "
+import json, sys
+try:
+    with open('$PROJECT_ROOT/.corrc.json') as f:
+        data = json.load(f)
+    manifest = data.get('manifest', {})
+    print('yes' if '$REL_PATH' in manifest else 'no')
+except:
+    print('no')
+" 2>/dev/null)
+
+if [ "$IN_MANIFEST" = "yes" ]; then
+  echo "{\"decision\":\"block\",\"reason\":\"Blocked: $REL_PATH is managed by Claude on Rails. CoR-managed files are upstream-owned — edits come through /cor-upgrade, not direct modification. Put project-specific content in _context.md or phase files instead.\"}"
+else
+  echo '{"decision":"allow"}'
+fi

package/templates/scripts/cor-drift-check.cjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// CoR Drift Check — detect modified upstream-managed files
+//
+// Compares current file hashes against .corrc.json manifest hashes.
+// Reports files that have been modified since install (drift).
+//
+// Usage:
+//   node scripts/cor-drift-check.js          # exit 0 if clean, 1 if drift
+//   node scripts/cor-drift-check.js --json   # output JSON for programmatic use
+//   node scripts/cor-drift-check.js --fix    # show what /cor-upgrade would fix
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const projectRoot = findProjectRoot();
+if (!projectRoot) {
+  console.error('No .corrc.json found — not a CoR project.');
+  process.exit(2);
+}
+
+const metadataPath = path.join(projectRoot, '.corrc.json');
+const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+const manifest = metadata.manifest || {};
+
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.corrc.json'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function hashContent(content) {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+const drifted = [];
+const missing = [];
+const clean = [];
+
+for (const [relPath, expectedHash] of Object.entries(manifest)) {
+  const fullPath = path.join(projectRoot, relPath);
+
+  if (!fs.existsSync(fullPath)) {
+    missing.push(relPath);
+    continue;
+  }
+
+  const content = fs.readFileSync(fullPath, 'utf8');
+  const currentHash = hashContent(content);
+
+  if (currentHash !== expectedHash) {
+    drifted.push(relPath);
+  } else {
+    clean.push(relPath);
+  }
+}
+
+const args = process.argv.slice(2);
+
+if (args.includes('--json')) {
+  console.log(JSON.stringify({ drifted, missing, clean: clean.length }, null, 2));
+} else {
+  if (drifted.length === 0 && missing.length === 0) {
+    console.log(`All ${clean.length} CoR-managed files match upstream hashes.`);
+  } else {
+    if (drifted.length > 0) {
+      console.log(`Drifted (${drifted.length} files modified from upstream):`);
+      for (const f of drifted) console.log(`  ${f}`);
+    }
+    if (missing.length > 0) {
+      console.log(`Missing (${missing.length} files deleted):`);
+      for (const f of missing) console.log(`  ${f}`);
+    }
+    console.log(`\nClean: ${clean.length} files match.`);
+    if (args.includes('--fix')) {
+      console.log('\nRun /cor-upgrade to restore drifted files to upstream versions.');
+    }
+  }
+}
+
+process.exit(drifted.length > 0 || missing.length > 0 ? 1 : 0);

package/templates/skills/debrief/SKILL.md

@@ -28,6 +28,9 @@ related:
   - type: file
     path: .claude/skills/debrief/phases/loose-ends.md
     role: "Project-specific: non-project items to capture"
+  - type: file
+    path: .claude/skills/debrief/phases/upstream-feedback.md
+    role: "Instruction: surface CoR friction back to source repo"
   - type: file
     path: .claude/skills/debrief/phases/report.md
     role: "Project-specific: how to present the summary"
@@ -182,7 +185,24 @@ them now while context is fresh.
 > different destinations (memory/feedback vs finding database). Both
 > feed the enforcement pipeline, but through different channels.
 
-### 8. Capture Loose Ends (core)
+### 8. Upstream Feedback (core)
+
+Read `phases/upstream-feedback.md`. This is an **instruction phase**
+shipped with CoR — it tells Claude to reflect on whether the session
+revealed friction with any CoR-provided skill, phase, or convention.
+
+If friction is found, Claude drafts a short feedback item and surfaces
+it in the report for the user to confirm, edit, or dismiss. If
+confirmed, the feedback is delivered to the CoR repo (via local link
+or GitHub issue). If nothing — the phase is silent.
+
+This is different from `/extract` (which proposes generalizable
+artifacts for upstreaming). This captures field friction: what hurt,
+what was confusing, what needed a workaround.
+
+**This phase should not be skipped.** It's how CoR learns from use.
+
+### 9. Capture Loose Ends (core)
 
 Read `phases/loose-ends.md` for non-project items and environmental
 concerns to capture before closing. Sessions generate non-project
@@ -191,14 +211,14 @@ these aren't captured somewhere, they rely on human memory.
 
 **Skip (absent/empty).**
 
-### 9. Discover Custom Phases
+### 10. Discover Custom Phases
 
 After running the core phases above, check for any additional phase
 files in `phases/` that the skeleton doesn't define. These are project-
 specific extensions. Each custom phase file declares its position in
 the workflow. Execute them at their declared position.
 
-### 10. Present Report (presentation)
+### 11. Present Report (presentation)
 
 Read `phases/report.md` for how to present the debrief summary.
 
@@ -218,6 +238,7 @@ Read `phases/report.md` for how to present the debrief summary.
 | `update-state.md` | Default: check system-status.md | What state files to update |
 | `health-checks.md` | Skip | Session-end health checks |
 | `record-lessons.md` | Default: ask what was learned | How to capture learnings |
+| `upstream-feedback.md` | **Instruction: always runs** | Surface CoR friction to source repo |
 | `loose-ends.md` | Skip | Non-project items to capture |
 | `report.md` | Default: brief summary | How to present the report |
 
@@ -228,7 +249,8 @@ Phases are either **core** (maintain system state) or **presentation**
 skip presentation phases. Core phases always run.
 
 - **Core phases** (always run): inventory, close-work, auto-maintenance,
-  update-state, health-checks, record-lessons, loose-ends, persist work
+  update-state, health-checks, record-lessons, upstream-feedback,
+  loose-ends, persist work
 - **Presentation phases** (skippable): report
 
 A project that wants a quick debrief variant skips the report and

package/templates/skills/debrief/phases/upstream-feedback.md

@@ -0,0 +1,106 @@
+# Upstream Feedback — Surface CoR Friction to the Source
+
+**Position:** Runs after record-lessons (step 7), before capture loose
+ends (step 8). Lessons are fresh; friction is top of mind.
+
+**This is an instruction phase** — it tells Claude what to do, not a
+customization point for the project. It ships with CoR and should not
+be deleted or replaced with `skip: true`.
+
+## What This Phase Does
+
+During debrief, Claude already has full session context: what was built,
+what went wrong, what was learned. This phase asks Claude to reflect on
+one narrow question: **was there friction with anything CoR provided?**
+
+- A skill whose flow didn't match how the project actually works
+- A phase file whose default behavior was wrong or confusing
+- A convention that fought the project's grain
+- A missing capability that required a workaround
+- An unclear SKILL.md that led to wasted time
+
+This is NOT the same as `/extract` (which looks for generalizable
+artifacts to upstream). This is field feedback — "this thing you shipped
+hurt when I used it."
+
+## Workflow
+
+### 1. Claude Reflects (silent)
+
+Review the session for CoR-specific friction. Consider:
+
+- Did any CoR skill need to be worked around or used in an unintended way?
+- Did a phase file's default behavior cause confusion or extra work?
+- Was a SKILL.md unclear, leading to misinterpretation?
+- Did the skeleton/phase separation feel wrong for something?
+- Was something missing that would have helped?
+- Did orient or debrief surface irrelevant information or miss something important?
+
+If nothing comes to mind — **stop here silently**. Most sessions have
+no CoR friction. Do not prompt the user with "any CoR feedback?" every
+time. The phase produces nothing and costs nothing unless there's
+something real.
+
+### 2. Draft Feedback (if friction found)
+
+For each friction point, draft a short feedback item:
+
+```
+## [Short title]
+
+**Skill/phase:** [which CoR component]
+**Friction:** [what happened — 2-3 sentences max]
+**Suggestion:** [what might be better — optional, can be "not sure"]
+**Session context:** [one line about what the project was doing when this came up]
+```
+
+Keep it concrete. "The plan skill was confusing" is not useful.
+"The plan skill's critique phase activated 4 perspectives when only 1
+was relevant, adding 3 minutes of noise to every plan" is useful.
+
+### 3. Surface for Confirmation
+
+Include the draft in the debrief report under a distinct heading:
+
+> **Upstream feedback for CoR:**
+> I noticed friction with [component]. Here's what I'd send:
+> [draft]
+>
+> Send this upstream? (yes / edit / skip)
+
+The user confirms, edits, or dismisses. One quick decision per item.
+Do not ask open-ended questions. Do not batch — if there are multiple
+friction points (rare), present each separately.
+
+### 4. Deliver
+
+If the user confirms, deliver the feedback. Detection and delivery
+follow the same pattern as `/extract`:
+
+**If linked** (the CoR package resolves to a local directory — check
+if `node -e "console.log(require.resolve('create-claude-rails'))"`
+points to a local path rather than a `node_modules` path):
+
+- Write the feedback as a markdown file in the CoR repo's `feedback/`
+  directory (create it if needed)
+- Filename: `[source-project]-[date]-[short-title].md`
+  (e.g., `flow-2026-04-04-plan-critique-noise.md`)
+- Add frontmatter: `type: field-feedback`, `source: [project]`,
+  `date: [ISO date]`, `component: [skill/phase name]`
+
+**If not linked** (CoR is installed from npm):
+
+- Open a GitHub issue on the CoR repo
+- Title: `Field feedback: [short title]`
+- Label: `field-feedback` (create if needed)
+- Body: the feedback markdown
+
+**If neither works** (no link, no gh access):
+
+- Output the feedback to the terminal and tell the user to file
+  it manually or copy it to the CoR repo
+
+### 5. Done
+
+Note in the debrief report what was sent and where. Move on to the
+next phase.

package/templates/skills/publish/SKILL.md

@@ -68,5 +68,7 @@ With user confirmation:
 
 ### 5. Post-Publish
 
+- Re-run the lean install (`node bin/create-claude-rails.js --lean`) to
+  update the local dogfood copy with the just-published templates
 - Update `system-status.md` if it exists
 - Report the published version and npm URL