create-claude-rails 0.3.4 → 0.4.1

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)',
@@ -183,10 +183,12 @@ async function run() {
   // --- Directory detection ---
   const dirState = detectProjectState(projectDir);
 
+  let existingManifest = {};
   if (dirState === 'existing-install') {
     const existing = readMetadata(projectDir);
+    existingManifest = existing.manifest || {};
     console.log(`  Found existing installation (v${existing.version}, installed ${existing.installedAt.split('T')[0]})`);
-    console.log('  Will add new files only. Use /cor-upgrade in Claude Code to update existing files.');
+    console.log('  Updating upstream-managed files and adding new files.');
     if (!flags.yes && !flags.lean) {
       const { proceed } = await prompts({
         type: 'confirm',
@@ -401,6 +403,7 @@ async function run() {
           skipConflicts: flags.yes || dirState === 'existing-install',
           skipPhases: isSkill,
           projectRoot: projectDir,
+          existingManifest,
         });
         totalCopied += results.copied.length;
         totalSkipped += results.skipped.length;
@@ -429,8 +432,14 @@ async function run() {
           }
 
           if (flags.yes || dirState === 'existing-install') {
-            // --yes or existing install: keep existing files (safe default)
-            totalSkipped++;
+            // If file is in the old manifest, it's upstream-managed — overwrite.
+            // If not, it's project-created — skip.
+            if (existingManifest[mPath]) {
+              if (!flags.dryRun) fs.copyFileSync(srcPath, destPath);
+              totalOverwritten++;
+            } else {
+              totalSkipped++;
+            }
             allManifest[mPath] = incomingHash;
           } else {
             const response = await prompts({

package/lib/copy.js

@@ -11,13 +11,13 @@ function hashContent(content) {
  * Recursively copy files from src to dest, surfacing conflicts.
  * Returns { copied: string[], skipped: string[], overwritten: string[] }
  */
-async function copyTemplates(src, dest, { dryRun = false, skipConflicts = false, skipPhases = false, projectRoot = null } = {}) {
+async function copyTemplates(src, dest, { dryRun = false, skipConflicts = false, skipPhases = false, projectRoot = null, existingManifest = {} } = {}) {
   const results = { copied: [], skipped: [], overwritten: [], manifest: {} };
-  await walkAndCopy(src, dest, src, results, dryRun, skipConflicts, skipPhases, projectRoot);
+  await walkAndCopy(src, dest, src, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest);
   return results;
 }
 
-async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipConflicts, skipPhases, projectRoot) {
+async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest) {
   const entries = fs.readdirSync(currentSrc, { withFileTypes: true });
 
   for (const entry of entries) {
@@ -37,7 +37,7 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipC
       if (!dryRun && !fs.existsSync(destPath)) {
         fs.mkdirSync(destPath, { recursive: true });
       }
-      await walkAndCopy(srcRoot, destRoot, srcPath, results, dryRun, skipConflicts, skipPhases, projectRoot);
+      await walkAndCopy(srcRoot, destRoot, srcPath, results, dryRun, skipConflicts, skipPhases, projectRoot, existingManifest);
     } else {
       const incoming = fs.readFileSync(srcPath, 'utf8');
       const incomingHash = hashContent(incoming);
@@ -52,8 +52,20 @@ async function walkAndCopy(srcRoot, destRoot, currentSrc, results, dryRun, skipC
         }
 
         if (skipConflicts) {
-          results.skipped.push(relPath);
-          results.manifest[relPath] = incomingHash;
+          // Check if file is upstream-managed (in the old manifest).
+          // If so, overwrite — it can't be customized (hook enforces this).
+          // If not, skip — it's project-created content.
+          const manifestKey = projectRoot
+            ? path.relative(projectRoot, destPath)
+            : relPath;
+          if (existingManifest[manifestKey]) {
+            if (!dryRun) fs.copyFileSync(srcPath, destPath);
+            results.overwritten.push(relPath);
+            results.manifest[relPath] = incomingHash;
+          } else {
+            results.skipped.push(relPath);
+            results.manifest[relPath] = incomingHash;
+          }
           continue;
         }
 

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.4",
+  "version": "0.4.1",
   "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.