Instruction Manager

Segments, library, targets

A segment is one ## section, stored in a library independent of any file. A target is a file composed into — .global for ~/.claude/CLAUDE.md, or .project(id). An assignment binds a segment to a target with an order and an enabled flag. One segment assigned to many targets is what makes a rule shared.

Managed region, by default

Code Raven owns a fenced block and nothing else. Text above or below the markers is never read, moved, or touched. The marker format mirrors DossierClaudeCodeSync:19-20; the integrity stamp reuses the CommandInstaller format at CommandInstaller.swift:65-67.

<!-- BEGIN CodeRaven Instructions — managed by Code Raven; edits inside are overwritten -->
<!-- CodeRaven v1.102.x sha256:a1b2c3d4e5f6 -->
...composed segments...
<!-- END CodeRaven Instructions -->

Full-file mode, opt-in and destructive

Code Raven owns the whole file. Reaching this mode requires a typed confirmation and a snapshot, and the UI labels it CAUTION / IRREVERSIBLE while stating that hand edits made outside the app are lost on the next compose. It exists because a fully-generated file is the cleaner model once the library holds everything, and getting there should be possible deliberately.

Drift is detected, never overwritten blind

Every write stores the sha256 of the region it wrote. Before the next write the app re-hashes what is on disk. On mismatch it refuses to write and offers two explicit choices: adopt the on-disk text back into the library, or overwrite it. This is the discipline CommandInstaller already applies to slash commands via CommandFileStatus.userModified. Drift here is expected: Claude itself edits CLAUDE.md through /init, the update-memory skill, and this project's own mirror-config rule.

Snapshots are the only undo

~/.claude is not a git repository. Before every write the current file is copied to Application Support/Code Raven/Instructions/snapshots/{target}/{ISO8601}.md, keeping the last 20, restorable from the section UI.

Getting ahead of drift, in three layers

Detecting drift after the fact is the backstop. Three layers sit in front of it.

A pinned instruction segment. The first segment in every managed region is Code Raven Managed Instructions, written by the app and non-disableable. It states that the block is composed from a library, that edits inside it are overwritten, that content outside the markers is hand-owned, and that a change to a managed rule goes through the bridge.

A sanctioned path. An instruction that only says do not fails, because Claude still has to add a rule when asked. .claude/instruction-changes/*.json follows the established bridge convention, so do not edit the region has an answer to then how do I add a rule?

A hook that enforces it. HookInstaller already installs a PreToolUse hook, and approve-bridge-writes.py already singles out CLAUDE.md as a path it deliberately leaves on the normal permission path. A sibling hook matches Edit|Write|NotebookEdit and, when the edit would touch a managed region, exits 0 and emits a deny.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "This block is composed by Code Raven. Write the change to .claude/instruction-changes/ instead."
  },
  "systemMessage": "Managed instruction region — change routed through the bridge."
}

Exit 0 with JSON rather than exit 2, because exit 2 blocks deterministically and discards the reason, leaving Claude blocked without knowing the bridge exists.

One field name has to be checked against reality. A documentation pass reported the path arrives as tool_input.path. The hook already running in this repo reads tool_input.get("file_path", "") and works. The installed hook is ground truth; the new one reads both keys and prefers whichever is populated.

What this does not cover. The hook sees Claude Code tool calls and nothing else, so an external editor, a shell redirect, or the LAN sync still reach the file. /init regenerates CLAUDE.md wholesale and would be blocked rather than redirected. Instruction text is persuasion and lowers the rate without driving it to zero. Every one of those paths lands on the Phase 1 sha check, which stays the design's floor.

Shared segments and token substitution

A shared segment resolves {{PROJECT_NAME}}, {{PROJECT_PATH}}, and {{COMMAND_PREFIX}} at compose time from the target project. Unresolved tokens are left verbatim and flagged in the preview rather than silently blanked. The CodeRaven/VentureRaven diff shows project name and command prefix are the only real differences, so this is enough to make those four sections genuinely shared.

Disabling removes the text, rather than commenting it out

CLAUDE.md is injected verbatim including HTML comments, so a commented-out segment still reaches the model and still costs context. Reversibility comes from the library holding the body, not from the file retaining it.

Managed region is the default; full-file ownership is gated

Full generation is the cleaner data model but destroys any edit made outside the app, and ~/.claude has no version control to recover from. It ships as an explicitly-confirmed mode rather than the default.

The never-write-CLAUDE.md rule is narrowed, not discarded

DossierClaudeCodeSync.swift:5-10 and the developer-profile blueprint both record that the app writes to a dedicated file and never CLAUDE.md. That rule protected against automatic, generated content landing in a hand-maintained file. It is rewritten to scope it to automatic writes: the Instruction Manager writes only on explicit user action, only inside markers, only after a snapshot.

One section parser, not two

DossierHarvestService.sections(of:source:) already splits CLAUDE.md on ##. Rather than writing a second parser, the lossless version is extracted and the harvest is refactored to call it.

Composition is deterministic, with no AI call

Matching DossierProjectionBuilder.buildPackage. What the preview shows is exactly what lands on disk.

Claude edits the managed region mid-session

Phase 3 addresses this with a pinned instruction, a bridge path, and a PreToolUse deny, which together should make it uncommon. None of the three is airtight: the hook sees only Claude Code tool calls, the instruction is persuasion, and /init would be blocked rather than redirected. The sha check stays as the floor.

The hook is a new way for the environment to feel broken

A denied write during /init reads as a failure rather than a redirect. The settings toggle exists for that reason, defaulting to on but switchable without uninstalling the feature.

The deny reason may never reach the model

There are open reports of permissionDecisionReason being discarded on a PreToolUse deny. If that holds, Claude sees a bare refusal rather than a pointer to the bridge, and the pinned instruction is the only remaining signal. Bash cannot be matched by file path at all, so a shell redirect into CLAUDE.md bypasses the hook entirely.

~/.claude is LAN-synced

LANSyncService.swift:298 syncs the whole folder between the iMac and the MacBook Pro. Writes from both machines are a genuine conflict. This plan detects it by sha mismatch and refuses; it does not merge.

Substituted text is not literally the library text

For shared segments the preview is the only accurate statement of what lands on disk. Reading the library body alone will mislead.

Full-file mode is genuinely destructive

Snapshots are the entire recovery story, and they live in Application Support, so clearing app data loses them.

Adoption is a one-way door in practice

Nothing technically prevents reverting, but once CLAUDE.md carries markers every later hand edit has to reckon with them. The Unmanage action exists so the exit is real.