create-claude-rails 0.4.2 → 0.5.1

package/README.md

@@ -1,21 +1,39 @@
 # Claude on Rails
 
-Opinionated process scaffolding for Claude Code projects.
+Process scaffolding for Claude Code projects, by a guy who'd rather
+talk to Claude than write code.
 
 One command gives you a session loop (orient/debrief), work tracking,
 structured planning, an audit system with expert perspectives, and
 enforcement hooks — all configured through conversational onboarding.
+Most of it was built by Claude. I just complained until it worked.
 
-## Quick Start
+## Install
+
+Open a terminal, `cd` into your project folder, and run:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/orenmagid/claude-on-rails/main/install.sh | bash
+```
+
+That's it. No Node.js, no npm, no git required — just a terminal.
+
+Then open [Claude Code](https://claude.ai/code) in the same folder and
+say `/onboard`. It'll interview you about your project and set everything
+up based on your answers.
+
+### For developers
+
+If you have Node.js installed and want interactive module selection,
+database setup, or the full install:
 
 ```bash
 npx create-claude-rails
 ```
 
-That's it. The CLI walks you through module selection, copies skill files,
+The CLI walks you through module selection, copies skill files,
 sets up hooks, and optionally installs a local SQLite work tracker. When
-it's done, open Claude Code and run `/onboard` — it interviews you about
-your project and generates the context layer that makes everything work.
+it's done, open Claude Code and run `/onboard`.
 
 ## What You Get
 
@@ -36,9 +54,9 @@ you already use GitHub Issues, Linear, or something else.
 - **`/execute`** — step-through execution with checkpoints and guardrails.
 
 ### Audit System (opt-in)
-15 expert perspectives (security, accessibility, data integrity,
-performance, etc.) that analyze your codebase and produce structured
-findings. Triage UI for reviewing results.
+20 expert perspectives (security, accessibility, data integrity,
+performance, architecture, process, etc.) that analyze your codebase and
+produce structured findings. Triage UI for reviewing results.
 
 ### Compliance Stack (opt-in)
 Scoped instructions in `.claude/rules/` that load by file path. An
@@ -102,8 +120,14 @@ scripts/
 
 ## Upgrading
 
+Re-run the installer to pick up new versions:
+
 ```bash
-npx create-claude-rails            # re-run to add modules
+# Shell installer (re-downloads latest)
+curl -fsSL https://raw.githubusercontent.com/orenmagid/claude-on-rails/main/install.sh | bash
+
+# npm installer (if using Node.js)
+npx create-claude-rails
 ```
 
 In Claude Code, run `/cor-upgrade` for conversational merge of upstream
@@ -121,8 +145,14 @@ starts from zero. Orient/debrief creates continuity. Planning with
 perspectives catches problems before they ship. The enforcement pipeline
 turns recurring mistakes into permanent fixes.
 
-None of this requires you to be a developer. The onboarding interview
-meets you where you are, and the system adapts based on what you tell it.
+None of this requires you to be a developer. I'm barely one myself. The
+onboarding interview meets you where you are, and the system adapts
+based on what you tell it.
+
+This is very much a work in progress. Things will break. The session
+loop is solid; everything else is still finding its shape. If you try it
+and something's weird, that's not you — it's probably me. Or Claude.
+We're figuring it out together.
 
 ## License
 

package/lib/cli.js

@@ -500,6 +500,23 @@ async function run() {
     }
   }
 
+  // --- Clean up files removed upstream ---
+  if (Object.keys(existingManifest).length > 0) {
+    let totalRemoved = 0;
+    for (const oldPath of Object.keys(existingManifest)) {
+      if (!allManifest[oldPath]) {
+        const fullPath = path.join(projectDir, oldPath);
+        if (fs.existsSync(fullPath)) {
+          if (!flags.dryRun) fs.unlinkSync(fullPath);
+          totalRemoved++;
+        }
+      }
+    }
+    if (totalRemoved > 0) {
+      console.log(`  🧹 Removed ${totalRemoved} file${totalRemoved === 1 ? '' : 's'} no longer in upstream`);
+    }
+  }
+
   // --- Write metadata ---
   if (!flags.dryRun) {
     createMetadata(projectDir, {

package/package.json

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

package/templates/skills/cor-upgrade/SKILL.md

@@ -2,24 +2,22 @@
 model: opus
 name: cor-upgrade
 description: |
-  Conversational upgrade when new Claude on Rails skeletons arrive. Detects current
-  adoption state, diffs against upstream, and for each change walks through
-  an intelligent merge — conversation not mechanical copy. Intelligence is
-  the merge strategy. Use when: "cor-upgrade", "update CoR", "new skeletons",
-  "/cor-upgrade".
+  Conversational upgrade when Claude on Rails updates. Runs the installer to
+  mechanically update all upstream-owned files, then walks through what changed
+  conversationally — explaining improvements, handling _context.md updates,
+  new phase file opportunities, and schema migrations. Intelligence is the
+  merge strategy for the parts that need it. Use when: "cor-upgrade",
+  "update CoR", "new skeletons", "/cor-upgrade".
 related:
   - type: file
-    path: .claude/skills/cor-upgrade/phases/detect-current.md
-    role: "Inventory current adoption state"
+    path: .claude/skills/cor-upgrade/phases/pre-upgrade.md
+    role: "Pre-upgrade checks and state capture"
   - type: file
-    path: .claude/skills/cor-upgrade/phases/diff-upstream.md
-    role: "Semantic diff against upstream CoR"
+    path: .claude/skills/cor-upgrade/phases/explain-changes.md
+    role: "How to explain what changed"
   - type: file
-    path: .claude/skills/cor-upgrade/phases/merge.md
-    role: "Intelligent merge strategy — the core of the skill"
-  - type: file
-    path: .claude/skills/cor-upgrade/phases/apply.md
-    role: "Apply approved changes"
+    path: .claude/skills/cor-upgrade/phases/adapt.md
+    role: "Handle non-manifest concerns — _context.md, phase files, schema"
 ---
 
 # /cor-upgrade — Conversational Claude on Rails Upgrade
@@ -27,34 +25,30 @@ related:
 ## Purpose
 
 This is the methodology's central claim made operational: **intelligence
-is the merge strategy.**
-
-Traditional frameworks distribute as code. You install a new version,
-run a migration script, resolve merge conflicts in config files, and hope
-nothing breaks. The upgrade path is mechanical — diff, patch, pray. This
-works for code because code has precise semantics. It fails for process
-because process is always adapted to context.
-
-AI-native methodology distributes as conversation. The upstream CoR
-package publishes new skeletons, updated defaults, additional perspectives,
-schema migrations. But the project has already adapted those skeletons —
-customized phase files, tuned perspectives, extended workflows. A
-mechanical merge would destroy the adaptations. A manual merge would
-require the user to understand both what changed upstream and how their
-project diverged, then mentally compose the two. Neither works.
-
-The upgrade skill reads both sides — the upstream change and the
-downstream context — and translates improvements into the project's
-idiom. It explains what changed and why, examines how the project
-currently handles that area, and proposes an adaptation that preserves
-local customizations while incorporating upstream improvements. The
-user confirms, modifies, or rejects each proposal. Nothing is applied
-silently.
+is the merge strategy** — but only where intelligence is needed.
+
+CoR upgrades have two layers:
+
+1. **Mechanical layer.** Skeleton SKILL.md files, hook scripts, utility
+   scripts — these are upstream-owned and tracked in `.corrc.json`. The
+   installer overwrites them deterministically. No conversation needed.
+   The upstream guard hook (PreToolUse on Edit|Write) enforces this
+   boundary at runtime — Claude cannot accidentally modify these files.
+
+2. **Conversational layer.** Everything the installer can't handle:
+   explaining what changed and why, updating `_context.md` sections that
+   new features reference, identifying new phase file opportunities,
+   running schema migrations, adapting project context to upstream
+   improvements. This is where intelligence is the merge strategy.
+
+The old approach tried to use conversation for everything — including
+mechanical file updates. That was fragile. Now the installer handles
+the deterministic parts, and this skill focuses entirely on the parts
+that actually need reasoning.
 
 This is a **skeleton skill** using the `phases/` directory pattern. The
-orchestration (detect, diff, merge, apply) is generic. Your project
-defines specifics — where upstream lives, what's adopted, how to
-present changes — in phase files under `phases/`.
+orchestration is generic. Your project defines specifics in phase files
+under `phases/`.
 
 ### Phase File Protocol
 
@@ -70,126 +64,170 @@ The skeleton always does something reasonable when a phase file is absent.
 Phase files customize, not enable. Use `skip: true` when you actively
 don't want a phase to run — not even the default.
 
-### Skeleton/Extension Separation
-
-This skill understands a critical boundary: **skeleton SKILL.md files may
-update, but phase files are NEVER overwritten by upstream changes.**
-
-Skeleton files (SKILL.md) contain the generic orchestration — the workflow
-steps, the phase protocol, the default behaviors. These are authored by
-CoR and may improve over time. When upstream publishes a better skeleton,
-the upgrade skill can propose replacing it.
-
-Phase files contain the project's customizations — what specific files to
-read, what specific APIs to call, what specific checks to run. These are
-authored by the project adopter (you and Claude together). Upstream has
-no knowledge of them and no authority to change them. Even if upstream
-adds a new phase file as an example or default, it never overwrites an
-existing project phase file.
-
-This separation is what makes upgrades safe. The skeleton evolves; the
-customizations persist. The merge intelligence sits at the boundary
-between the two.
-
-## Workflow
-
-### 1. Detect Current State
+### Write Protection
 
-Read `phases/detect-current.md` for how to inventory the project's
-current CoR adoption.
+Manifest-tracked files (skeleton SKILL.md files, hooks, scripts) are
+protected by the upstream guard hook. Claude cannot Edit or Write to
+them during normal operation. This is intentional — these files are
+upstream-owned and should only change through the installer.
 
-**Default (absent/empty):** Scan the project for CoR artifacts:
-- For each skill in `.claude/skills/`: is it a CoR skeleton? Which
-  phase files are customized vs using defaults vs explicitly skipped?
-- Which perspectives are adopted? Which groups configured?
-- What hooks are installed from CoR?
-- What pib-db schema version is in use (check for known columns)?
-- What's in `memory/patterns/`?
+**What this means for upgrades:**
+- The installer (running via Bash as a Node.js/shell process) bypasses
+  the hook because it doesn't use Claude's Edit/Write tools
+- After the installer runs, all manifest-tracked files are current
+- This skill then handles everything the installer doesn't touch:
+  _context.md, phase files, schema, and explanation
 
-Output: a structured manifest of current adoption state, consumed by
-the diff phase.
-
-### 2. Diff Against Upstream
-
-Read `phases/diff-upstream.md` for how to compare the project's state
-against the upstream CoR package.
-
-**Default (absent/empty):** Look for `.pib-upstream/` in the project
-root (staged by `npx create-claude-rails upgrade`). For each
-adopted skeleton: perform a semantic diff of SKILL.md — section by
-section, not line by line. Identify new phases, changed workflows,
-updated defaults. For non-adopted skills: list what's new and available.
-For perspectives: detect new or updated ones in upstream. For schema:
-compare `pib-db-schema.sql` columns against the project's actual DB
-tables.
-
-Output: a categorized list of changes, each tagged with a change
-category (see below).
-
-### 3. Merge — The Intelligence
-
-Read `phases/merge.md` for how to handle each detected change. This is
-the core of the skill — where conversation replaces mechanical patching.
-
-**Default (absent/empty):** For each change detected in the diff phase:
-
-1. **Explain** what changed and why. Read the upstream change, infer its
-   purpose from context (commit messages, surrounding documentation,
-   the change itself). Don't just say "line 47 changed" — say "the
-   orient skeleton now includes a calendar-check phase because projects
-   found that missing upcoming deadlines was a recurring failure mode."
-
-2. **Examine** how the project currently handles this area. Read the
-   relevant phase files, skill definitions, and configuration. Understand
-   the project's adaptation before proposing anything.
-
-3. **Propose** an adaptation. Based on the change category (see below),
-   recommend one of: adopt as-is, adapt to fit the project's patterns,
-   or skip with a reason. Explain what each option would mean concretely.
-
-4. **Dialogue.** The user decides. This is conversation, not mechanical
-   merge. If the user wants something different from what you proposed,
-   co-author the adaptation together.
+### Skeleton/Extension Separation
 
-#### Change Categories
+Skeleton files (SKILL.md, hooks, scripts) are upstream-owned, manifest-
+tracked, and write-protected. They evolve through the installer.
 
-Each detected change falls into one of six categories. The category
-determines the default merge strategy:
+Phase files and _context.md are project-owned. They are NEVER in the
+manifest, NEVER write-protected, and NEVER overwritten by the installer.
+They evolve through conversation — this skill, /onboard, or direct
+editing.
 
-| # | Category | Default Strategy |
-|---|----------|-----------------|
-| 1 | **New default behavior** — a phase the project uses defaults for gains a new default | Auto-adopt. The project was already trusting upstream defaults; the new default is strictly additive. Mention it but don't require confirmation. |
-| 2 | **Changed default behavior** — a phase the project uses defaults for has its default modified | Explain + propose. The project trusted the old default; the new one is different. Show what changed and let the user decide. |
-| 3 | **New phase added to skeleton** — upstream added a phase that didn't exist before | Explain what the phase does, propose opt-in. New phases start as "absent" (using default or skipped), so adoption is always explicit. |
-| 4 | **Changed skeleton workflow** — the SKILL.md orchestration itself changed | The most sensitive category. Examine the project's phase files and any custom phases. Co-author the adaptation — don't just replace the skeleton. |
-| 5 | **New skeleton skill available** — upstream published a skill the project hasn't adopted | Present what the skill does, what problem it solves, what adoption would involve. User decides whether and when to adopt. |
-| 6 | **Schema migration** — upstream schema has new columns or tables | Detect the difference, generate ALTER TABLE / CREATE TABLE SQL, present for review, apply only after explicit confirmation. |
+This separation is enforced mechanically (manifest + hook), not just
+by convention. The upgrade is safe because the boundary is real.
 
-**CRITICAL:** Phase files are NEVER overwritten. The merge handles
-skeleton SKILL.md updates and new capabilities. Project-specific
-customizations in phase files are sacred — they represent the project's
-adaptation of the methodology to its own context. If an upstream change
-would interact with a phase file's content (e.g., a skeleton now
-references a concept the phase file also addresses), the merge proposes
-a collaborative edit, not a replacement.
+## Workflow
 
-### 4. Apply Approved Changes
+### 1. Pre-Upgrade Snapshot
 
-Read `phases/apply.md` for how to apply the changes the user approved
-in the merge phase.
+Read `phases/pre-upgrade.md` for pre-upgrade checks.
 
 **Default (absent/empty):**
-- For skeleton-only changes: copy the updated SKILL.md from upstream,
-  preserving the project's phase files untouched.
-- For changes that interact with phase files: make collaborative edits
-  as approved in the merge dialogue — show the diff before writing.
-- For schema migrations: run the approved SQL against the project's DB.
-- For new skills: copy the skeleton SKILL.md, create an empty `phases/`
-  directory. The project customizes from there.
-- Commit after each logical group of changes with a clear message
-  describing what was upgraded and why.
-- Present a summary: what was applied, what was skipped (with reasons),
-  what the user might want to review or customize next.
+- Read `.corrc.json` to capture the current version and module set
+- Note which phase files exist and have content (these won't be touched)
+- Note any `_context.md` sections that may need updating
+- If the project has a work tracker DB, note the current schema
+
+Output: a snapshot of the project's current state, used to explain
+what changed after the installer runs.
+
+### 2. Run the Installer
+
+Run the installer via Bash to mechanically update all upstream files:
+
+```
+# Shell installer (re-downloads latest from npm registry)
+curl -fsSL https://raw.githubusercontent.com/orenmagid/claude-on-rails/main/install.sh | bash
+
+# Or npm installer (if Node.js available)
+npx create-claude-rails
+```
+
+The installer:
+- Overwrites all manifest-tracked files (skeletons, hooks, scripts)
+- Preserves files NOT in the manifest (phase files, _context.md)
+- Updates `.corrc.json` with new version, hashes, and any new files
+- Adds new skills/hooks/scripts that didn't exist in the old version
+
+**This is a Bash command, not an Edit/Write operation.** It bypasses
+the upstream guard hook because it runs as a separate process using
+the filesystem directly. This is by design — the installer is the
+authorized update path for manifest-tracked files.
+
+### 3. Explain What Changed
+
+Read `phases/explain-changes.md` for how to present changes.
+
+**Default (absent/empty):** Compare the pre-upgrade snapshot against
+the new state:
+
+1. **Version jump.** What version did we come from? What version are
+   we on now?
+
+2. **Changed skeletons.** For each SKILL.md that the installer updated,
+   explain what changed and why — not line-by-line diffs, but semantic
+   summaries. "The debrief skill now includes an upstream feedback phase
+   that surfaces CoR friction during debrief sessions." "The plan skill's
+   critique step now pulls from more perspectives by default."
+
+3. **New files.** Any skills, hooks, or scripts that were added for the
+   first time. Explain what they do and whether they need any setup.
+
+4. **New phase opportunities.** If new skeletons reference phase files
+   that the project doesn't have yet, mention them as opportunities.
+   "The orient skeleton now supports a `calendar-check.md` phase — you
+   could create one to check upcoming deadlines."
+
+5. **Deprecations or removals.** If anything was removed upstream,
+   explain why and what replaces it.
+
+Walk through each category conversationally. The user should understand
+what they're getting, not just that files changed.
+
+### 4. Adapt Non-Manifest Concerns
+
+Read `phases/adapt.md` for how to handle the conversational layer.
+
+**Default (absent/empty):** After explaining changes, handle anything
+the installer couldn't:
+
+#### _context.md Updates
+If new skeletons reference `_context.md § Section` names that the
+project's `_context.md` doesn't have, propose adding them. New features
+often depend on context sections — e.g., a new perspective might
+reference `§ Friction Captures` which the project hasn't defined yet.
+Show the section template from `_context-template.md` and help the
+user fill it in.
+
+#### Phase File Opportunities
+For each skeleton that changed, check its phase files against the
+project's `phases/` directory. There are three cases:
+
+1. **Existing phase file, workflow changed around it.** The project
+   customized this phase and the skeleton shifted. Discuss the
+   implications: "The orient skeleton reorganized its steps — your
+   custom `health-checks.md` phase still works, but it now runs
+   earlier in the workflow. Is that okay?"
+
+2. **New phase the skeleton now references.** The upstream added a
+   phase that didn't exist before. Explain what the default behavior
+   is and what customizing it would look like. Don't push — just
+   surface the opportunity. "The debrief skeleton now has an
+   `upstream-feedback` step. It runs by default — here's what it does.
+   If you ever want to change that behavior, you'd create
+   `phases/upstream-feedback.md`."
+
+3. **Existing default that changed meaningfully.** The project uses
+   the default (no phase file) and the default behavior shifted. The
+   project gets the improvement automatically, but mention it so they
+   know. If the new default does something they might not want, suggest
+   creating a phase file to customize or skip it. "The plan skeleton's
+   default research phase now reads test files too. You've been using
+   the default — you'll get this automatically. If that's too noisy,
+   create `phases/research.md` to scope it."
+
+4. **Default that won't fit the project.** Read `_context.md` and
+   compare against what the default actually does. If there's a
+   mismatch, say so and offer to create the phase file now. "The
+   orient skeleton added a `work-scan` phase. The default reads git
+   history — but your `_context.md` says you use Linear. The default
+   won't see your tickets. Want to create `phases/work-scan.md` that
+   checks Linear?" This isn't speculation — it's reading both sides
+   and spotting the gap.
+
+**Don't enumerate every absent phase file.** That's `/onboard`'s job.
+The upgrade skill only surfaces phase opportunities that are *relevant
+to what changed* in this upgrade — including cases where the project's
+context makes a default obviously insufficient.
+
+#### Schema Migrations
+If the upstream schema has new columns or tables:
+- Detect the difference between the shipped schema and the project's DB
+- Generate `ALTER TABLE` / `CREATE TABLE` SQL
+- Present for review
+- Apply only after explicit confirmation
+
+#### New Module Adoption
+If the upgrade added modules the project hadn't installed before,
+walk through what they do and whether to keep them.
+
+Present a summary when done: what was mechanically updated, what was
+adapted conversationally, what the user might want to customize next.
 
 ### 5. Discover Custom Phases
 
@@ -202,23 +240,21 @@ the workflow. Execute them at their declared position.
 
 | Phase | Absent = | What it customizes |
 |-------|----------|-------------------|
-| `detect-current.md` | Default: scan .claude/skills/, perspectives, hooks, DB | How to inventory adoption state |
-| `diff-upstream.md` | Default: compare against .pib-upstream/ (staged by CLI) | Where upstream lives and how to diff |
-| `merge.md` | Default: explain + examine + propose for each change | How to handle each change category |
-| `apply.md` | Default: copy skeletons, collaborative edits, SQL migrations | How to apply approved changes |
+| `pre-upgrade.md` | Default: read .corrc.json, note phase files, note _context.md | Pre-upgrade state capture |
+| `explain-changes.md` | Default: semantic summary of version jump, changed skeletons, new files | How to present what changed |
+| `adapt.md` | Default: _context.md sections, phase implications, schema, new modules | How to handle non-manifest concerns |
 
 ## Proactive Trigger
 
 The upgrade skill doesn't have to wait for the user to invoke it.
-Orient can detect when upstream CoR files are newer than the project's
-adopted copies and surface "CoR updates available" in the briefing.
+Orient can detect when upstream CoR has a newer version than what's
+in `.corrc.json` and surface "CoR updates available" in the briefing.
 This is a hint, not a blocker — the user decides when to run /cor-upgrade.
 
-To enable this, a project's orient `phases/health-checks.md` or a
-custom orient phase can compare modification times between upstream
-skeleton SKILL.md files and their adopted counterparts. When drift is
-detected, orient mentions it. When the user is ready, they invoke
-/cor-upgrade and the full conversational merge begins.
+The drift check script (`scripts/cor-drift-check.cjs`) can also detect
+if manifest-tracked files have been modified outside the installer,
+though the upstream guard hook should prevent this during normal
+Claude Code operation.
 
 ## Extending
 
@@ -238,29 +274,29 @@ Examples of phases mature projects add:
 ## Calibration
 
 **Core failure this targets:** Process improvements published upstream
-never reach adopted projects, or reach them as destructive overwrites
-that erase hard-won customizations.
+never reach adopted projects, or reach them but nobody understands
+what changed.
 
 ### Without Skill (Bad)
 
-New CoR skeletons arrive. The user manually diffs files, trying to
-figure out what changed. Some changes are obvious — a new skill directory
-appeared. Others are subtle — a default behavior in an existing skeleton
-shifted. The user copies files they think are updated, accidentally
-overwrites a phase file they'd customized, doesn't notice a schema
-migration is needed. Three sessions later, a skill fails because it
-references a DB column that doesn't exist yet. The customization they
-spent two sessions tuning is gone, replaced by the upstream default.
+New CoR version is out. The user re-runs the installer. Files update
+silently. The user has no idea what changed — was it just bug fixes?
+New features? Did a skill they rely on change its workflow? They also
+don't realize the new debrief skill references a `§ Friction Captures`
+section in _context.md that their project doesn't have, so the upstream
+feedback phase silently does nothing. Three weeks later they wonder
+why no friction is being captured.
 
 ### With Skill (Good)
 
-New CoR skeletons arrive. The user runs `/cor-upgrade`. Claude inventories
-what's adopted, diffs against upstream, and walks through each change:
-"The orient skeleton added a calendar-check phase. Your project doesn't
-have calendar integration, so this would be a no-op — skip it for now?"
-"The debrief skeleton's default inventory behavior now includes checking
-for uncommitted stash entries. You're using the default here, so this
-improvement applies automatically." "There's a new schema column for
-deferred trigger conditions. Here's the ALTER TABLE — want me to apply
-it?" Nothing is lost. Everything is explained. The project gets better
-without getting broken.
+New CoR version is out. The user runs `/cor-upgrade`. The installer
+updates all upstream files mechanically — fast, deterministic, safe
+(phase files untouched). Then Claude explains: "You went from v0.4.1
+to v0.5.0. The big change: debrief now has an upstream feedback phase
+that captures CoR friction. It references `_context.md § Friction
+Captures` — let's add that section to your context file." "The plan
+skill's critique step now uses three perspectives instead of one. Your
+existing phase files are fine — this is a default behavior change."
+"There's a new `investigate` skill for deep-dive debugging. Want to
+try it?" Everything is explained. Non-manifest concerns are handled.
+The project gets better without confusion.

package/templates/skills/cor-upgrade/phases/apply.md

@@ -1,86 +0,0 @@
-# Apply — Execute Approved Changes
-
-Apply the changes approved during the merge conversation. Each change
-type has a specific application method.
-
-When this file is absent or empty, the default behavior is: apply each
-approved change using the type-appropriate method below, commit after
-each logical group, and present a summary. To explicitly skip applying
-(dry-run mode where merge proposes but nothing is written), write only
-`skip: true`.
-
-## Application Methods
-
-### Skeleton SKILL.md Updates
-
-Copy the updated SKILL.md from upstream to the project's `.claude/skills/`
-directory. The project's `phases/` directory is untouched — only the
-skeleton orchestration file changes.
-
-Before copying, verify:
-- The project's phase files still exist and are intact
-- The new skeleton's phase references match the phase files that exist
-- If the new skeleton references a phase the project doesn't have,
-  note it (the project will use the default behavior)
-
-### Phase File Collaborative Edits
-
-When a merge proposal includes changes to a phase file (always with
-user approval):
-- Show the exact diff before writing
-- Make the edit
-- Read back the result so the user can verify
-
-Never bulk-replace a phase file. Edits are surgical and approved.
-
-### Schema Migrations
-
-- Present the SQL one more time before executing
-- Run the migration against the project's database
-- Verify the schema change took effect (query the table structure)
-- If migration fails, report the error — don't retry or attempt fixes
-  without user input
-
-### New Skills
-
-- Copy the skeleton SKILL.md from upstream
-- Create an empty `phases/` directory
-- Do NOT copy upstream example phase files — the project starts fresh
-  and customizes from the skeleton's defaults
-- Note the new skill in the summary so the user knows to customize it
-
-### New Perspectives
-
-- Copy new perspective files to the project's perspective directory
-- If the project has a group configuration, note the new perspective
-  but don't auto-add it to any group — the user decides placement
-
-### New Hooks or Rules
-
-- Present the hook/rule configuration
-- Add to `.claude/settings.json` or `.claude/rules/` after confirmation
-- If the project has existing hooks that might conflict, flag it
-
-## Commit Strategy
-
-Commit after each logical group of changes:
-- All skeleton updates in one commit
-- Schema migrations in a separate commit (easy to revert)
-- New skills in a separate commit
-- Phase file edits in a separate commit (clearly separated from
-  skeleton changes)
-
-Commit messages should describe what was upgraded:
-"Upgrade orient + debrief skeletons from upstream CoR"
-"Add trigger_condition column (CoR schema migration)"
-"Adopt /validate skill from CoR"
-
-## Summary
-
-After all changes are applied, present:
-- **Applied:** what was changed, with commit references
-- **Skipped:** what the user chose not to adopt, with their reasons
-  (useful context for the next upgrade)
-- **Review next:** suggestions for customization — new skills that
-  need phase files, new phases that might benefit from project-specific
-  content, perspectives to consider adding to groups

package/templates/skills/cor-upgrade/phases/detect-current.md

@@ -1,82 +0,0 @@
-# Detect Current — Inventory Claude on Rails Adoption State
-
-Build a structured manifest of the project's current CoR adoption. This
-manifest is consumed by the diff-upstream phase to determine what has
-changed.
-
-When this file is absent or empty, the default behavior is: read
-`.corrc.json` for version and module metadata, then scan the project's
-`.claude/skills/`, perspectives, hooks, and database for CoR artifacts.
-To explicitly skip detection, write only `skip: true`.
-
-## What to Inventory
-
-### Package Metadata (.corrc.json)
-
-Read `.corrc.json` from the project root. This file is written by the
-CLI installer (`npx create-claude-rails`) and contains:
-
-- **`version`** — the installed package version (for diff-upstream comparison)
-- **`installedAt`** — when the install or last upgrade happened
-- **`modules`** — which module groups were selected (boolean map)
-- **`skipped`** — modules the user opted out of, with reasons
-- **`upstreamPackage`** — the npm package name (`create-claude-rails`)
-
-If `.corrc.json` is missing, this is either a pre-npm adoption or a
-manual install. Note this in the manifest — the diff-upstream phase
-needs to know whether version comparison is possible or if it must fall
-back to pure filesystem diffing.
-
-### Skills
-
-For each directory in `.claude/skills/`:
-- **Is it a CoR skeleton?** Compare the SKILL.md against the upstream
-  upstream templates directory. If it matches a known skeleton
-  (by name or by frontmatter `name` field), it's a CoR skill.
-- **Phase file status:** For each phase file the skeleton defines, check
-  whether the project's copy is: absent (using default), empty (using
-  default), contains `skip: true` (opted out), or contains custom content
-  (project-specific adaptation).
-- **Custom phases:** Any phase files in the project's `phases/` directory
-  that the skeleton doesn't define are project extensions.
-
-### Perspectives
-
-- Which perspective groups exist in `.claude/skills/perspectives/`?
-- Which perspectives are listed in each group's `_group.yaml`?
-- Which perspectives have project-customized content vs upstream defaults?
-
-### Hooks
-
-- Read `.claude/settings.json` (or `.claude/settings.local.json`).
-- Identify which hooks were installed as part of CoR adoption vs
-  project-specific additions.
-
-### Database Schema
-
-- If the project uses `pib-db`, check the actual DB schema against
-  known CoR columns. Record which tables and columns exist.
-- Note the effective schema version (inferred from which columns are
-  present, not from a version number).
-
-### Memory and Patterns
-
-- Count files in `memory/patterns/` and `memory/archive/`.
-- Note whether the enforcement pipeline is active (patterns have
-  `enforcement` frontmatter fields).
-
-## Output Format
-
-Produce a structured manifest (in conversation, not a file) listing:
-- **Package version** from `.corrc.json` (or "unknown — no .corrc.json")
-- **Installed modules** from `.corrc.json` modules map
-- **Skipped modules** with reasons from `.corrc.json` skipped map
-- Each adopted skill with its phase file statuses
-- Each adopted perspective group with member count
-- Hook count and types
-- Schema state
-- Pattern/archive counts
-
-This manifest feeds directly into the diff-upstream phase. The version
-field is especially critical — it determines whether diff-upstream can
-do a targeted version-to-version comparison or must diff everything.

package/templates/skills/cor-upgrade/phases/diff-upstream.md

@@ -1,72 +0,0 @@
-# Diff Upstream — Compare Project Against Claude on Rails Package
-
-Compare the project's current adoption state (from detect-current) against
-the upstream CoR package. Produce a categorized list of changes.
-
-When this file is absent or empty, the default behavior is: look for
-`.pib-upstream/` in the project root (staged by `npx create-claude-rails
-upgrade`) and perform semantic diffs of all adopted skeletons. To
-explicitly skip diffing, write only `skip: true`.
-
-## Locating Upstream
-
-Default: `.pib-upstream/` in the project root. This directory is created
-by `npx create-claude-rails upgrade`, which fetches the latest package
-from npm and stages its templates here for comparison. The directory is
-gitignored — it's a transient diff target, not a permanent fixture.
-
-If `.pib-upstream/` doesn't exist, prompt the user:
-"Run `npx create-claude-rails upgrade` first — it fetches the latest
-upstream and stages it for comparison."
-
-If your project stores upstream elsewhere (a submodule, a symlinked
-directory, a separate checkout), specify the path here.
-
-## Diff Strategy
-
-The diff is **semantic, not textual.** Line-by-line diffs of markdown
-files are noisy and miss the point. Instead:
-
-### For Each Adopted Skeleton SKILL.md
-
-Compare section by section:
-- **Purpose/description** — has the framing changed?
-- **Workflow steps** — are there new phases? Removed phases? Reordered?
-- **Phase summary table** — do defaults differ?
-- **Default behaviors** — for each phase, has the "absent/empty" behavior
-  changed? This matters most for projects using defaults.
-- **Calibration** — has the failure mode description evolved?
-- **Extending section** — new extension examples?
-
-### For Non-Adopted Skills
-
-List any skills in upstream that the project hasn't adopted. For each,
-note: name, one-line description, what problem it addresses.
-
-### For Perspectives
-
-- New perspectives in upstream that the project doesn't have.
-- Updated perspectives where upstream content differs from project copy.
-- New perspective groups.
-
-### For Schema
-
-Compare `pib-db-schema.sql` (or equivalent) column-by-column against
-the project's actual database tables. Flag: new columns, changed types,
-new tables, new indexes.
-
-### For Infrastructure
-
-- New hooks in upstream's recommended settings.
-- New rules files in upstream's `.claude/rules/`.
-- Changes to the CoR onboarding or seed skills.
-
-## Output Format
-
-A categorized change list, where each change has:
-- **What** changed (specific file, section, or artifact)
-- **Category** (1-6, matching the SKILL.md's change categories)
-- **Summary** of the change in plain language
-- **Impact** on the project (does this touch something the project customized?)
-
-This feeds directly into the merge phase.

package/templates/skills/cor-upgrade/phases/merge.md

@@ -1,97 +0,0 @@
-# Merge — Intelligent Upgrade Conversation
-
-THE INTELLIGENCE. For each change detected by diff-upstream, walk
-through a conversational merge: explain, examine, propose, dialogue.
-
-When this file is absent or empty, the default behavior is: process
-each change using the category-based strategy defined in the skeleton
-SKILL.md. To explicitly skip merging (just list changes without
-proposing anything), write only `skip: true`.
-
-## The Merge Loop
-
-For each change in the categorized list:
-
-### 1. Explain What Changed and Why
-
-Read the upstream change in full. Don't summarize from the diff — read
-the actual new content. Infer purpose from:
-- The change itself (what does it add, remove, or alter?)
-- Surrounding documentation (did a README or methodology essay mention it?)
-- Commit messages if accessible
-- The pattern of changes (if several skeletons gained the same phase,
-  that's a methodology-wide shift)
-
-Communicate at the level of intent, not lines: "The orient skeleton now
-checks for stale deferred items because projects found that deferred
-work was being forgotten" — not "lines 140-155 were added."
-
-### 2. Examine the Project's Current Implementation
-
-Before proposing anything, understand how the project handles this area:
-- Read the relevant phase files (customized? default? skipped?)
-- Check if the project has custom phases that address the same concern
-- Look at related memory patterns or feedback
-- Understand why the project's current approach exists
-
-### 3. Propose Adaptation
-
-Based on the change category:
-
-**Category 1 (new default):** "This applies automatically since you're
-using the default. Here's what it adds: [description]. No action needed
-unless you want to customize it."
-
-**Category 2 (changed default):** "The default behavior for [phase]
-changed from [old] to [new]. You're currently using the default. The
-new version [explanation]. Adopt the new default, or would you prefer
-to pin the old behavior by writing it into your phase file?"
-
-**Category 3 (new phase):** "Upstream added a [name] phase to [skill].
-It handles [description]. Your project [does/doesn't] have something
-similar. Want to opt in, or skip it for now?"
-
-**Category 4 (changed workflow):** "The [skill] skeleton's workflow
-changed: [description]. Your project has customized [these phases].
-Here's how I'd adapt: [proposal]. Let's walk through it."
-
-**Category 5 (new skill):** "There's a new [name] skill available. It
-handles [description]. Adopting it would involve [steps]. Want to
-explore it, or skip for now?"
-
-**Category 6 (schema migration):** "The upstream schema adds [columns/
-tables]. Here's the migration SQL: [SQL]. This would enable [features].
-Want me to apply it?"
-
-### 4. Dialogue
-
-Wait for the user's response. They may:
-- Accept as proposed
-- Want modifications (co-author the adaptation)
-- Skip with a reason (record why for future upgrades)
-- Ask questions (answer from upstream context)
-
-## CRITICAL: Phase File Protection
-
-Phase files are NEVER overwritten by this process. The merge handles:
-- Skeleton SKILL.md updates (the generic orchestration)
-- New capabilities and defaults
-- Schema migrations
-- New skills and perspectives
-
-It does NOT handle:
-- Replacing project phase files with upstream examples
-- Overwriting custom perspectives
-- Changing project-specific hook configurations
-
-If an upstream change interacts with a phase file's content (e.g., a
-skeleton now references a concept the phase file also addresses), propose
-a **collaborative edit** — show the user what you'd change in their
-phase file and why, get approval before touching it.
-
-## Batch vs Interactive
-
-For small upgrades (1-3 changes), walk through each one interactively.
-For large upgrades (many changes), group by category and handle
-auto-adopt items (category 1) in batch, then walk through the rest
-individually.