forge-orkes 0.80.3 → 0.81.0

package/bin/create-forge.js

@@ -295,19 +295,25 @@ function upgradeDir(relDir, { autoClean = false } = {}) {
 }
 
 /**
- * Guarantee CLAUDE.md carries the single `@.forge/FORGE.md` import line, migrating
- * any legacy embedded forge section out in one pass. The framework prose itself lives
- * in .forge/FORGE.md (synced separately) — this function never writes prose into
- * CLAUDE.md and never touches user content outside the legacy forge section.
+ * Guarantee CLAUDE.md carries the single `@.forge/FORGE.md` import line WITHIN ITS
+ * FIRST 3 LINES, migrating any legacy embedded forge section out in one pass. Claude
+ * Code truncates memory files at 40k chars from the TAIL — an import line buried below
+ * that cliff silently unloads the entire framework, so the import must never live in
+ * the tail. The framework prose itself lives in .forge/FORGE.md (synced separately) —
+ * this function never writes prose into CLAUDE.md and never touches user content
+ * outside the legacy forge section / the one line it relocates.
  *
  *   no CLAUDE.md                         → write the stub (comment + import) → 'created'
  *   marker section present               → replace section in place with the import line → 'migrated'
  *   legacy `# Forge` header (no markers) → strip header-to-EOF, append import line → 'migrated'
- *   import line already present          → 'unchanged'
- *   none of the above                    → append comment + import line at EOF → 'appended'
+ *   import line within the first 3 lines → untouched, no rewrite (no mtime churn) → 'unchanged'
+ *   import line present but lower        → remove that line, insert as line 1 + blank line,
+ *                                           every other byte preserved in order → 'moved'
+ *   no import line anywhere              → prepend import line + blank line, original
+ *                                           content follows intact → 'appended'
  *
- * Newline cleanup is confined to the seam of the replaced region only — a global
- * collapse would mutate user content, which upgrades must never do.
+ * Newline cleanup is confined to the seam of the replaced/relocated region only — a
+ * global collapse would mutate user content, which upgrades must never do.
  */
 function ensureClaudeMdImport() {
   const destPath = path.join(targetDir, 'CLAUDE.md');
@@ -344,21 +350,90 @@ function ensureClaudeMdImport() {
     return 'migrated';
   }
 
-  // Import line already present (tolerating trailing whitespace/CRLF) — nothing to do.
-  if (FORGE_IMPORT_RE.test(existing)) return 'unchanged';
+  // Import line present somewhere (tolerating trailing whitespace/CRLF) — find its
+  // exact line so position and byte-preservation are decided on real line boundaries,
+  // not the regex's own (looser) match span.
+  if (FORGE_IMPORT_RE.test(existing)) {
+    const lines = existing.split('\n');
+    const idx = lines.findIndex((l) => l.trimEnd() === FORGE_IMPORT_LINE);
+
+    // Already within the first 3 lines — leave the file byte-for-byte untouched.
+    if (idx === -1 || idx <= 2) return 'unchanged';
+
+    // Remove the import's own line.
+    lines.splice(idx, 1);
+    // If that removal left two adjacent blank lines where there weren't three
+    // before, collapse them back to one — the only non-import byte we ever drop.
+    if (idx > 0 && idx < lines.length && lines[idx - 1].trim() === '' && lines[idx].trim() === '') {
+      lines.splice(idx, 1);
+    }
+    const merged = FORGE_IMPORT_LINE + '\n\n' + lines.join('\n');
+    fs.writeFileSync(destPath, merged);
+    return 'moved';
+  }
 
-  // User-authored CLAUDE.md with no forge content and no import line — append it.
-  const merged =
-    existing.trimEnd() + '\n\n' + CLAUDE_STUB;
+  // User-authored CLAUDE.md with no forge content and no import line anywhere —
+  // prepend the import (plus a separating blank line) so it is never buried below
+  // the truncation cliff. Original content follows intact, byte-for-byte.
+  const merged = FORGE_IMPORT_LINE + '\n\n' + existing;
   fs.writeFileSync(destPath, merged);
   return 'appended';
 }
 
+// --- Hook identity helpers (per-hook dedupe key: event + matcher + script basename) ---
+
+// Normalize a hook group's matcher for key comparisons — trim, and treat an
+// absent/empty matcher as the same value so an unset matcher never desyncs
+// from "".
+function normalizeMatcher(matcher) {
+  return typeof matcher === 'string' ? matcher.trim() : '';
+}
+
+// Basename of the first path-looking token in a command string (quotes
+// stripped) — "bash /path/to/x.sh" and "$CLAUDE_PROJECT_DIR/.claude/hooks/x.sh"
+// both resolve to "x.sh", so the same framework script hosted at a different
+// path, or invoked via an interpreter prefix, is recognized as the same hook.
+// No path-looking token (e.g. a bare `echo` one-liner) → the whole trimmed
+// command is its own identity.
+function hookScriptBasename(command) {
+  const tokens = command.match(/"[^"]*"|'[^']*'|\S+/g) || [];
+  for (const raw of tokens) {
+    let tok = raw;
+    if ((tok.startsWith('"') && tok.endsWith('"')) || (tok.startsWith("'") && tok.endsWith("'"))) {
+      tok = tok.slice(1, -1);
+    }
+    if (tok.includes('/')) return path.basename(tok);
+  }
+  return command.trim();
+}
+
+// Identity of a single hook entry within a group. Prompt-backed hooks key off
+// the prompt text; anything else (neither command nor prompt) falls back to a
+// full-entry identity so it never collides with something it isn't.
+function hookEntryIdentity(hookEntry) {
+  if (typeof hookEntry.command === 'string') return 'cmd:' + hookScriptBasename(hookEntry.command);
+  if (typeof hookEntry.prompt === 'string') return 'prompt:' + hookEntry.prompt.trim();
+  return 'raw:' + JSON.stringify(hookEntry);
+}
+
+// Full dedupe key for one (event, matcher, hook-entry) registration. JSON-encoded
+// as a tuple so no delimiter choice can be ambiguated by the values themselves.
+function hookKey(event, matcher, hookEntry) {
+  return JSON.stringify([event, normalizeMatcher(matcher), hookEntryIdentity(hookEntry)]);
+}
+
 /**
  * Additively install the template's framework-managed hooks into an existing
- * settings.json (ADR-017). Never removes a user's hooks; dedups by deep-equality
- * so re-running upgrade is idempotent. New groups (the safety guardrails) get
- * appended; groups the project already has (identical) are skipped.
+ * settings.json (ADR-017). Never removes a user's hooks. Dedupes PER HOOK
+ * ENTRY, keyed by (event, matcher, script basename) — not whole-group
+ * equality — because consumer repos legitimately reshape groups (combine two
+ * matcher="Bash" groups into one, host the same script at a project-local
+ * path, etc.) without that being a meaningfully different hook. A hook whose
+ * key already exists anywhere under that event is skipped; a genuinely new
+ * hook is appended into an existing dest group sharing its matcher, or into a
+ * newly created group when no such group exists yet. See cleanupDuplicateHooks()
+ * (called from upgradeSettings()) for the paired destination-side cleanup pass
+ * that collapses duplicates already baked into a project's settings.json.
  */
 function mergeManagedHooks(destSettings, srcSettings) {
   if (!srcSettings.hooks) return;
@@ -366,12 +441,62 @@ function mergeManagedHooks(destSettings, srcSettings) {
   for (const event of Object.keys(srcSettings.hooks)) {
     const srcGroups = srcSettings.hooks[event] || [];
     const destGroups = destSettings.hooks[event] || (destSettings.hooks[event] = []);
-    for (const group of srcGroups) {
-      const groupJson = JSON.stringify(group);
-      if (!destGroups.some((d) => JSON.stringify(d) === groupJson)) {
-        destGroups.push(group);
+
+    const existingKeys = new Set();
+    const groupsByMatcher = new Map();
+    for (const group of destGroups) {
+      const nm = normalizeMatcher(group.matcher);
+      if (!groupsByMatcher.has(nm)) groupsByMatcher.set(nm, group);
+      for (const hookEntry of group.hooks || []) {
+        existingKeys.add(hookKey(event, group.matcher, hookEntry));
       }
     }
+
+    for (const srcGroup of srcGroups) {
+      for (const hookEntry of srcGroup.hooks || []) {
+        const key = hookKey(event, srcGroup.matcher, hookEntry);
+        if (existingKeys.has(key)) continue; // already installed, whatever group it sits in
+
+        const nm = normalizeMatcher(srcGroup.matcher);
+        let destGroup = groupsByMatcher.get(nm);
+        if (!destGroup) {
+          destGroup = { matcher: srcGroup.matcher, hooks: [] };
+          destGroups.push(destGroup);
+          groupsByMatcher.set(nm, destGroup);
+        }
+        destGroup.hooks.push(hookEntry);
+        existingKeys.add(key);
+      }
+    }
+  }
+}
+
+/**
+ * Collapse duplicate hook registrations already baked into a project's
+ * settings.json — the same (event, matcher, script basename) appearing in
+ * more than one group, or more than once in the same group — keeping the
+ * first occurrence and dropping any group the collapse empties. Runs on
+ * every upgrade, independent of what mergeManagedHooks() just added, so
+ * repos that accumulated near-duplicate groups under the old whole-group
+ * equality merge converge without operator action. Idempotent by
+ * construction: a settings.json with no duplicates is left byte-identical.
+ */
+function cleanupDuplicateHooks(destSettings) {
+  if (!destSettings.hooks) return;
+  for (const event of Object.keys(destSettings.hooks)) {
+    const groups = destSettings.hooks[event];
+    if (!Array.isArray(groups)) continue;
+    const seen = new Set();
+    for (const group of groups) {
+      if (!Array.isArray(group.hooks)) continue;
+      group.hooks = group.hooks.filter((hookEntry) => {
+        const key = hookKey(event, group.matcher, hookEntry);
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      });
+    }
+    destSettings.hooks[event] = groups.filter((g) => Array.isArray(g.hooks) && g.hooks.length > 0);
   }
 }
 
@@ -475,6 +600,9 @@ function upgradeSettings() {
   migrateActiveSkillHook(destSettings);
   // Additively install framework-managed safety guardrails (ADR-017)
   mergeManagedHooks(destSettings, srcSettings);
+  // Converge any duplicate hook registrations already baked into the
+  // destination (pre-existing, or left by an older whole-group merge).
+  cleanupDuplicateHooks(destSettings);
   mergeManagedDeny(destSettings, srcSettings);
   mergeManagedAllow(destSettings, srcSettings);
 
@@ -535,6 +663,9 @@ async function install() {
     case 'appended':
       console.log('  Added @.forge/FORGE.md import line to existing CLAUDE.md');
       break;
+    case 'moved':
+      console.log('  Moved @.forge/FORGE.md import line to the top of CLAUDE.md');
+      break;
     case 'unchanged':
       console.log('  CLAUDE.md import line already present');
       break;
@@ -959,6 +1090,9 @@ async function upgrade() {
   } else if (claudeStatus === 'appended') {
     results.updated.push('CLAUDE.md');
     say('  CLAUDE.md: @.forge/FORGE.md import line restored');
+  } else if (claudeStatus === 'moved') {
+    results.updated.push('CLAUDE.md');
+    say('  CLAUDE.md: @.forge/FORGE.md import line moved to the top (was below the truncation-safe zone)');
   } else if (claudeStatus === 'unchanged') {
     results.unchanged.push('CLAUDE.md');
   } else if (claudeStatus === 'created') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.80.3",
+  "version": "0.81.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/hooks/forge-size-gate.sh

@@ -42,6 +42,16 @@
 # A declared-gate artifact that does not exist in this repo (e.g. no
 # prototypes/ dir yet) is skipped silently — not an error, not a violation.
 #
+# Special-cased alongside the tiered skill-file class: the CONSUMER's
+# repo-root CLAUDE.md, advisory at 30 KB (m-56). This is NOT a FORGE.md Size
+# Gates table row — that table lists forge-owned artifacts, and CLAUDE.md
+# belongs entirely to the consumer (the import-to-top fix keeps the
+# @.forge/FORGE.md import out of Claude Code's 40k-char tail-truncation
+# zone; this check is the companion advisory for when the consumer's own
+# prose grows past a size where relocating it into path-scoped
+# .claude/rules/ files, ADR-018, is worth considering). Absent CLAUDE.md or
+# under 30 KB → silent, same contract as every other check.
+#
 # Contract (SessionStart, mirrors forge-state-rollup.sh — ADR-032):
 #   - Exit 0 ALWAYS. SessionStart is non-blocking; this hook must never abort
 #     a session.
@@ -164,6 +174,22 @@ for f in "$root"/.claude/skills/*/SKILL.md; do
   check_gate "$f" "$skill_kb"
 done
 
+# --- consumer CLAUDE.md advisory (special-cased — NOT a Size Gates table row) -
+# CLAUDE.md is consumer-owned, not forge-owned, so it never joins the declared
+# table above (m-56). Threshold is 30 KB BINARY (30720 B — Claude Code's own
+# memory-file semantics use binary units), unlike the decimal-KB gates above.
+# Missing file or under threshold → silent, same contract as every other check.
+
+CLAUDE_MD_GATE_BYTES=30720
+
+if [ -f "$root/CLAUDE.md" ]; then
+  claude_bytes="$(wc -c < "$root/CLAUDE.md" 2>/dev/null | tr -d ' ')"
+  if [ -n "$claude_bytes" ] && [ "$claude_bytes" -gt "$CLAUDE_MD_GATE_BYTES" ]; then
+    VIOLATIONS="${VIOLATIONS}${VIOLATIONS:+, }CLAUDE.md (${claude_bytes}B, over the 30KB advisory threshold — relocate prose into path-scoped .claude/rules/, ADR-018)"
+    VIOLATION_COUNT=$((VIOLATION_COUNT + 1))
+  fi
+fi
+
 # --- summary (stdout → injected into boot context) ---------------------------
 # Silent when clean. One terse line when not.
 

package/template/.claude/hooks/tests/forge-size-gate.test.sh

@@ -114,6 +114,34 @@ check_has "missing tier-list → default 20KB tier applied even to 'forge'" "$ou
 rm -rf "$REPO/.claude/skills"
 printf 'forge\nchief-of-staff\n' > "$REPO/.claude/hooks/skill-gate-tiers.txt"
 
+# ===========================================================================
+# Case F1 — consumer CLAUDE.md over the 30KB (30720B) advisory threshold: one
+# advisory line naming CLAUDE.md, its byte size, the 30KB threshold, and the
+# .claude/rules/ relocation pointer. Special-cased, NOT a Size Gates table row.
+# ===========================================================================
+pad_to "$REPO/CLAUDE.md" 31000
+out_f1="$("$GATE" --project "$REPO" 2>&1)"
+check_has "over-30KB CLAUDE.md named" "$out_f1" "CLAUDE.md"
+check_has "over-30KB CLAUDE.md shows actual bytes" "$out_f1" "31000B"
+check_has "over-30KB CLAUDE.md names the 30KB threshold" "$out_f1" "30KB"
+check_has "over-30KB CLAUDE.md points at .claude/rules/ relocation" "$out_f1" ".claude/rules"
+rm -f "$REPO/CLAUDE.md"
+
+# ===========================================================================
+# Case F2 — consumer CLAUDE.md under the 30KB threshold → never named.
+# ===========================================================================
+pad_to "$REPO/CLAUDE.md" 5000
+out_f2b="$("$GATE" --project "$REPO" 2>&1)"
+check_absent "under-30KB CLAUDE.md never named" "$out_f2b" "CLAUDE.md"
+rm -f "$REPO/CLAUDE.md"
+
+# ===========================================================================
+# Case F3 — no CLAUDE.md at all → no error, clean run, exit 0.
+# ===========================================================================
+out_f3="$("$GATE" --project "$REPO" 2>&1)"; rc_f3=$?
+check "absent CLAUDE.md → exit 0" "$rc_f3" "0"
+check_absent "absent CLAUDE.md never named" "$out_f3" "CLAUDE.md"
+
 # ===========================================================================
 # Case F — non-Forge repo / non-repo dir: silent no-op, exit 0.
 # ===========================================================================

package/template/.claude/settings.json

@@ -1,6 +1,6 @@
 {
   "forge": {
-    "version": "0.80.3",
+    "version": "0.81.0",
     "default_tier": "standard",
     "beads_integration": false,
     "context_gates": {

package/template/.forge/gitignore

@@ -34,13 +34,19 @@ dev-source
 # Orchestration locks
 *.lock
 
-# Render-on-read derived registries (0.53.0). Regenerated at every `forge` boot
-# from their sources (state/index.yml ← state/milestone-*.yml; streams/active.yml
-# ← streams/*.yml + active milestones). Local cache only — never committed, so a
-# committed projection can never drift stale from its source. Without these
-# entries a fresh install would re-commit them.
+# Render-on-read derived registries (0.53.0; context.md joined in 0.80.0/ADR-033).
+# Regenerated at every `forge` boot from their sources (state/index.yml ←
+# state/milestone-*.yml; streams/active.yml ← streams/*.yml + active milestones;
+# context.md ← context/*.md joined against state/index.yml). Local cache only —
+# never committed, so a committed projection can never drift stale from its
+# source. Without these entries a fresh install would re-commit them, and an
+# upgrade would silently re-track context.md after a project migrated off the
+# monolithic file (issue #46 — this line must ship canonically, not as a
+# per-project manual edit, since this file is overwritten wholesale on every
+# upgrade).
 state/index.yml
 streams/active.yml
+context.md
 
 # Notion board id-binding cache (ADR-020 derived class) — forge-id → page-id, rebuilt
 # by query-self-heal; never committed (a committed copy would leak private Notion page IDs).

package/template/.forge/migrations/0.80.0-context-md-sharding.md

@@ -123,19 +123,23 @@ What is **not** repeatable is the untrack step below — do that once.
 git rm --cached .forge/context.md
 ```
 
-Add `.forge/context.md` to whichever gitignore file already lists
-`.forge/state/index.yml` and `.forge/streams/active.yml` — grep for
-`index.yml` to find the right file (in this repo it's the root
-`.gitignore`, under the "Render-on-read derived registries" comment block;
-your project's may differ if it customized gitignore layout):
+If your project uses the shipped `.forge/.gitignore` default (no custom
+gitignore layout), a `create-forge` install/upgrade at 0.80.4+ already lists
+`context.md` next to `state/index.yml` and `streams/active.yml` in that file —
+nothing to add by hand, and it's safe against a future upgrade overwriting it
+(issue #46: before 0.80.4, `.forge/.gitignore` was wholesale re-synced from
+the canonical shipped file on every upgrade, silently reverting a manual
+addition here — the fix moved the line into the canonical source itself).
+
+If your project customized gitignore layout (e.g. this repo's own root
+`.gitignore`, not `.forge/.gitignore`), add `.forge/context.md` there by
+hand, next to the other two derived-registry entries, matching their
+existing comment block rather than starting a new one:
 
 ```bash
 grep -rn "index.yml" .gitignore .forge/.gitignore 2>/dev/null
 ```
 
-Add the line next to the other two derived-registry entries, matching their
-existing comment block rather than starting a new one.
-
 ### 3. Commit the migration output
 
 ```bash