devflow-kit 2.5.0 → 3.0.0

package/dist/targets/claude-code/compliance-install.js

@@ -1,8 +1,18 @@
 /**
  * Compliance artifact installer for the Claude Code target.
  *
- * Convergence function: installs or removes the compliance skill directory
- * and rule file based on the current feature state.
+ * Convergence function: installs the compliance skill directory on every
+ * machine and installs or removes the rule file based on the current feature state.
+ *
+ * D-COMPLIANCE-INSTALL-ALWAYS: the skill and all six framework references are
+ * installed whatever the machine's own selection, because a repository can turn
+ * the review lens on by itself (`compliance` in `.devflow/project.json`, folded
+ * into the `COMPLIANCE` field of the settings line). What the machine switch still
+ * owns is the RULE — the one artifact Claude Code loads into every prompt — and
+ * the stamp on SKILL.md: the machine's frameworks when compliance is on, the
+ * neutral zero-framework stamp when it is off. Which references a run loads is
+ * decided by the ids its caller passes (D-COMPLIANCE-REPO-LENS), never by which
+ * files are present.
  *
  * Applies ADR-013: I/O orchestration in src/targets/; pure helpers in src/core/.
  * Applies PF-009: warn-not-throw for per-item failures.
@@ -12,10 +22,12 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { skillsDir, rulesDir } from '../../core/assets.js';
-import { ALWAYS_PRESENT_REFS, normalizeFrameworks } from '../../core/compliance.js';
+import { ALWAYS_PRESENT_REFS, COMPLIANCE_FRAMEWORKS, normalizeFrameworks } from '../../core/compliance.js';
 import { parseComplianceFragment, composeComplianceSkill, composeComplianceRule } from '../../core/compliance-compose.js';
 import { validateSkillShadow, validateRuleShadow } from './installer.js';
 // ── Path helpers ───────────────────────────────────────────────────────────
+/** Every registry framework id — the reference set every install carries. */
+const ALL_FRAMEWORK_IDS = COMPLIANCE_FRAMEWORKS.map(fw => fw.id);
 /** Installed compliance skill dir: {claudeDir}/skills/devflow:compliance/ */
 function skillTarget(claudeDir) {
     return path.join(claudeDir, 'skills', 'devflow:compliance');
@@ -67,13 +79,15 @@ async function loadComplianceFragments(canonicalSrc, frameworks, warn) {
 }
 // ── Skill installer ────────────────────────────────────────────────────────
 /**
- * Install the compliance skill directory (selective references).
+ * Install the compliance skill directory (every reference).
  *
  * SKILL.md source: shadow at {devflowDir}/skills/compliance/SKILL.md (when valid),
- * otherwise canonical src/assets/skills/compliance/SKILL.md.
+ * otherwise canonical src/assets/skills/compliance/SKILL.md. It is composed with
+ * `stampFrameworks` — the machine's selection, or none for the neutral stamp.
  *
- * Reference files installed: ALWAYS_PRESENT_REFS + one {id}.md per selected framework.
- * References always come from the canonical source — framework refs are not user-overridable.
+ * Reference files installed: ALWAYS_PRESENT_REFS + one {id}.md for EVERY registry
+ * framework (D-COMPLIANCE-INSTALL-ALWAYS). References always come from the canonical
+ * source — framework refs are not user-overridable.
  *
  * `fragments` is loaded once by convergeComplianceArtifacts and shared with the rule
  * installer — the SKILL.md and the rule compose from the same parsed set.
@@ -81,7 +95,7 @@ async function loadComplianceFragments(canonicalSrc, frameworks, warn) {
  * Applies PF-011: build under a .tmp sibling, remove old target, rename.
  * Applies PF-009: unexpected I/O failures are reported via warn; never thrown.
  */
-async function installSkillDir(claudeDir, devflowDir, frameworks, fragments, warn) {
+async function installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, warn) {
     const canonicalSrc = path.join(skillsDir(), 'compliance');
     const target = skillTarget(claudeDir);
     const tmpTarget = `${target}.tmp`;
@@ -100,7 +114,7 @@ async function installSkillDir(claudeDir, devflowDir, frameworks, fragments, war
         // SKILL.md: compose from template (shadow or canonical) + fragments.
         // C1: a shadow without tokens passes through byte-identical.
         const templateContent = await fs.readFile(skillMdSrc, 'utf-8');
-        const { content: composedSkill, warnings: skillWarnings } = composeComplianceSkill(templateContent, frameworks, fragments);
+        const { content: composedSkill, warnings: skillWarnings } = composeComplianceSkill(templateContent, stampFrameworks, fragments);
         for (const w of skillWarnings)
             warn(`compliance: ${w}`);
         await fs.writeFile(path.join(tmpTarget, 'SKILL.md'), composedSkill, 'utf-8');
@@ -121,9 +135,10 @@ async function installSkillDir(claudeDir, devflowDir, frameworks, fragments, war
         }
         // Per-framework reference files: source is frameworks/{id}/reference.md,
         // destination is references/{id}.md (installed artifact layout unchanged — C1
-        // for consumers). Every id here is a registry-validated bare name — no separator,
-        // no traversal — from normalizeFrameworks in convergeComplianceArtifacts.
-        for (const fw of frameworks) {
+        // for consumers). Every registry id, whatever the machine selected: a repository
+        // may declare any of them. The ids come from the static registry — no separator,
+        // no traversal. C7: bounded by the registry's six entries.
+        for (const fw of ALL_FRAMEWORK_IDS) {
             const srcRef = path.join(canonicalSrc, 'frameworks', fw, 'reference.md');
             const dstRef = path.join(refDst, `${fw}.md`);
             try {
@@ -183,10 +198,10 @@ async function installRuleFile(claudeDir, devflowDir, frameworks, fragments, war
 /**
  * Converge compliance artifacts in the Claude Code install target.
  *
- * Convergence matrix:
- *   enabled + rulesEnabled  → install skill dir (selective refs) + stamped rule
- *   enabled + !rulesEnabled → install skill dir only; remove stale rule
- *   !enabled                → remove both artifacts (warn-not-throw per PF-009)
+ * Convergence matrix (D-COMPLIANCE-INSTALL-ALWAYS):
+ *   enabled + rulesEnabled  → skill dir (every ref, machine stamp) + stamped rule
+ *   enabled + !rulesEnabled → skill dir (every ref, machine stamp); remove stale rule
+ *   !enabled                → skill dir (every ref, neutral stamp); remove rule
  *
  * PF-015: both artifact operations execute unconditionally — no || short-circuits.
  * PF-011: skill dir write uses temp-sibling+rename to avoid ENOENT windows.
@@ -218,63 +233,32 @@ export async function convergeComplianceArtifacts(opts) {
         converged = false;
         warn(msg);
     };
-    // ── Disable path ─────────────────────────────────────────────────────────
-    if (!enabled) {
-        // Detect pre-existing artifacts BEFORE removal (to set removedPreexisting).
-        const skillExisted = await pathExists(skillTarget(claudeDir));
-        const ruleExisted = await pathExists(ruleTarget(claudeDir));
-        // PF-015: collect results independently — one failure must not skip the other.
-        let skillErr = null;
-        let ruleErr = null;
-        // Step 1: attempt skill dir removal
-        try {
-            if (skillExisted) {
-                await fs.rm(skillTarget(claudeDir), { recursive: true, force: true });
-            }
-        }
-        catch (err) {
-            skillErr = String(err);
-        }
-        // Step 2: attempt rule removal (runs regardless of Step 1 outcome — PF-015)
-        try {
-            if (ruleExisted) {
-                await fs.rm(ruleTarget(claudeDir), { force: true });
-            }
-        }
-        catch (err) {
-            ruleErr = String(err);
-        }
-        // PF-009: warn after BOTH attempts so neither failure blocks the other.
-        if (skillErr !== null) {
-            trackingWarn(`compliance: failed to remove skill dir — ${skillErr}`);
-        }
-        if (ruleErr !== null) {
-            trackingWarn(`compliance: failed to remove rule — ${ruleErr}`);
-        }
-        return { removedPreexisting: skillExisted || ruleExisted, converged };
-    }
-    // ── Enable path ──────────────────────────────────────────────────────────
-    //
-    // PF-015: installSkillDir and the rule step are independent operations.
-    // An error in installSkillDir is caught internally and reported via trackingWarn,
-    // so execution always continues to the rule step.
     // Fragments are read and parsed once per convergence and shared by both artifacts:
     // they are the same registry-owned files either way, so parsing twice would only
-    // duplicate the I/O and report each malformed fragment twice.
-    const fragments = await loadComplianceFragments(path.join(skillsDir(), 'compliance'), safeFrameworks, trackingWarn);
-    await installSkillDir(claudeDir, devflowDir, safeFrameworks, fragments, trackingWarn);
-    if (rulesEnabled) {
+    // duplicate the I/O and report each malformed fragment twice. Only the stamped
+    // frameworks need one — a compliance-off machine stamps none.
+    const stampFrameworks = enabled ? safeFrameworks : [];
+    const fragments = await loadComplianceFragments(path.join(skillsDir(), 'compliance'), stampFrameworks, trackingWarn);
+    // PF-015: the skill and the rule are independent operations. An error in
+    // installSkillDir is caught internally and reported via trackingWarn, so
+    // execution always continues to the rule step.
+    await installSkillDir(claudeDir, devflowDir, stampFrameworks, fragments, trackingWarn);
+    if (enabled && rulesEnabled) {
         await installRuleFile(claudeDir, devflowDir, safeFrameworks, fragments, trackingWarn);
+        return { removedPreexisting: false, converged };
     }
-    else {
-        // Rules disabled: remove any stale rule left from a prior enabled run.
-        // Ignore ENOENT (force: true) — absence is the desired end state.
+    // Compliance off, or rules off: no rule. Probe first so a disable convergence
+    // can report that it removed one; absence is already the desired end state.
+    const ruleExisted = await pathExists(ruleTarget(claudeDir));
+    if (ruleExisted) {
         try {
             await fs.rm(ruleTarget(claudeDir), { force: true });
         }
-        catch { /* absent = already in desired end state */ }
+        catch (err) {
+            trackingWarn(`compliance: failed to remove rule — ${String(err)}`);
+        }
     }
-    return { removedPreexisting: false, converged };
+    return { removedPreexisting: !enabled && ruleExisted, converged };
 }
 // ── Manifest-slice wrapper ─────────────────────────────────────────────────
 /**

package/dist/targets/claude-code/hooks.js

@@ -1,9 +1,114 @@
 /**
- * Shared hook types for Claude Code settings.json.
- * Used by learn.ts, ambient.ts, and memory.ts.
+ * Shared hook types and hook-ownership helpers for Claude Code settings.json.
+ * Used by every module that registers or removes a devflow hook (ambient.ts,
+ * capture.ts, memory.ts, context.ts, proxy.ts, legacy-hooks.ts).
  *
  * NOTE: hud.ts uses a structurally different Settings type (statusLine, not hooks)
  * and is intentionally excluded from this shared module.
  */
-export {};
+import * as path from 'path';
+/** The directory, relative to a devflow root, that holds every hook devflow registers. */
+export const HOOKS_DIR_SUFFIX = '/scripts/hooks/';
+/** The command ending devflow writes for a `run-hook <marker>` hook. */
+export function runHookSuffix(marker) {
+    return `${HOOKS_DIR_SUFFIX}run-hook ${marker}`;
+}
+/** The command devflow registers for the `run-hook <marker>` hook under `devflowDir`. */
+export function runHookCommand(devflowDir, marker) {
+    return `${path.join(devflowDir, 'scripts', 'hooks', 'run-hook')} ${marker}`;
+}
+/**
+ * A predicate matching a hook whose command ends in any of `suffixes`, read with
+ * surrounding whitespace trimmed and backslashes as slashes (a Windows install).
+ * A missing or non-string command — a hand-edited settings.json — matches nothing.
+ */
+export function endsWithAny(suffixes) {
+    return (hook) => {
+        const raw = hook.command;
+        if (typeof raw !== 'string')
+            return false;
+        const command = raw.trim().replace(/\\/g, '/');
+        return suffixes.some((suffix) => command.endsWith(suffix));
+    };
+}
+/**
+ * The ownership predicate for devflow's `run-hook <marker>` hooks.
+ *
+ * D-EXACT-HOOK-OWNER: a hook is devflow's when its command ENDS in
+ * `/scripts/hooks/run-hook <marker>` for one of `markers`, or in one of the
+ * module's named `legacySuffixes` (a form an earlier release registered, such as
+ * `/scripts/hooks/session-start-memory.sh`), under any directory — so installs made
+ * under a custom or retired devflow directory are still recognised. It is never
+ * devflow's because it merely CONTAINS a marker word: a user's `~/bin/memory-worker`,
+ * `echo capture-turn` or `/opt/tools/run-hook preamble` is theirs (applies ADR-024 —
+ * remove only what devflow can prove it wrote). Removal goes through `removeHooks`,
+ * one hook at a time. Every hook module builds its predicates here;
+ * D-AMBIENT-EXACT-HOOK is the ambient instance of this rule.
+ */
+export function devflowHookOwner(markers, legacySuffixes = []) {
+    return endsWithAny([...markers.map(runHookSuffix), ...legacySuffixes]);
+}
+/** A matcher group's hooks, or an empty list for a hand-edited group of another shape. */
+function hooksOf(matcher) {
+    return Array.isArray(matcher?.hooks) ? matcher.hooks : [];
+}
+/**
+ * Remove every hook matching `shouldRemove` from one event's matcher groups.
+ * Mutates `settings` (callers pass their own parsed copy). Returns true if any hook
+ * was removed.
+ *
+ * D-EXACT-HOOK-OWNER: removal is per HOOK, not per matcher group — a group keeps
+ * the user's sibling hooks, in their order, and is dropped only when nothing is left
+ * in it. A group whose `hooks` is not an array is kept as is. Empty event arrays and
+ * an empty `hooks` object are cleaned up.
+ */
+export function removeHooks(settings, eventName, shouldRemove) {
+    const matchers = settings.hooks?.[eventName];
+    if (!settings.hooks || !Array.isArray(matchers))
+        return false;
+    let removed = false;
+    const kept = [];
+    for (const matcher of matchers) {
+        const hooks = hooksOf(matcher);
+        const remaining = hooks.filter((hook) => !shouldRemove(hook));
+        if (remaining.length === hooks.length) {
+            kept.push(matcher);
+            continue;
+        }
+        removed = true;
+        if (remaining.length > 0)
+            kept.push({ ...matcher, hooks: remaining });
+    }
+    if (!removed)
+        return false;
+    if (kept.length === 0) {
+        delete settings.hooks[eventName];
+    }
+    else {
+        settings.hooks[eventName] = kept;
+    }
+    if (Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+    }
+    return true;
+}
+/** Whether any hook registered for `eventName` matches `isOurs`. */
+export function hasHook(settings, eventName, isOurs) {
+    const matchers = settings.hooks?.[eventName];
+    return Array.isArray(matchers) && matchers.some((m) => hooksOf(m).some(isOurs));
+}
+/**
+ * Append `entry` as a new matcher group for `eventName` unless a hook matching
+ * `isOurs` is already registered there. Mutates `settings`. Returns true when the
+ * entry was added.
+ */
+export function ensureHook(settings, eventName, isOurs, entry) {
+    if (hasHook(settings, eventName, isOurs)) {
+        return false;
+    }
+    settings.hooks ??= {};
+    settings.hooks[eventName] ??= [];
+    settings.hooks[eventName].push(entry);
+    return true;
+}
 //# sourceMappingURL=hooks.js.map

package/dist/targets/claude-code/installer.js

@@ -215,11 +215,10 @@ export async function chmodRecursive(dir, mode, _depth = 0) {
  * `tracker/` ({@link TRACKER_DESTINATION_ROOT}) holds the per-provider mechanics and `pr/`
  * ({@link PR_HOST_DESTINATION_ROOT}) the PR/review host bodies; the build emits both
  * wholesale, so anything inside them the manifest does not name is by construction a
- * leftover — a retired op, a provider the selection dropped, a shadow-supplied file, a
+ * leftover — a retired op, a provider the registry dropped, a shadow-supplied file, a
  * staging tree a crashed run stranded — and removing it is the only way the installed
- * tree can equal the manifest. `pr/` is wanted under EVERY provider (applies ADR-026), so
- * a provider switch neither adds nor removes the directory; what it converges is the
- * directory's CONTENTS, exactly as `tracker/`'s are converged. Both entries are the
+ * tree can equal the manifest. Every install carries both whole
+ * (D-INSTALL-ALL-PROVIDERS), so what the prune converges is each directory's CONTENTS. Both entries are the
  * registry's own constants, so a renamed destination root moves the build and the prune
  * together.
  *
@@ -1067,42 +1066,6 @@ export async function overlayGeneratedReferences(opts) {
     }
     return { overlaidRefs, unchangedRefs, overlayFailures, pruned };
 }
-/**
- * Converge the installed `devflow:git` references onto ONE provider's install set.
- *
- * The provider-scoped entry point to {@link overlayGeneratedReferences}: it
- * resolves the install manifest and the target directory from a claudeDir and a
- * provider, and changes nothing else. There is exactly ONE overlay spelling in
- * this codebase and this is its only wrapper — `devflow init` reaches the
- * overlay through `installViaFileCopy`, `devflow tracker --set` reaches it
- * through here, and both converge to the same manifest for the same provider.
- *
- * Convergence is two-directional by construction, because the underlying overlay
- * PRUNES everything under its converged subtrees the manifest does not name: a
- * jira → github change removes the jira tree and `_mcp.md` in the same call that
- * refreshes the github tree (applies PF-015). `references/pr/` is wanted under
- * every provider (applies ADR-026), so a provider change leaves it standing —
- * converged, not removed.
- *
- * Throws on an absent generated tree, exactly as its callee does — that is a
- * build artifact that was never produced, not an I/O degradation, and the
- * refusal lands before the target directory is created so a refused overlay
- * leaves the install as it found it.
- *
- * @param opts.provider - The RESOLVED tracker provider id.
- * @param opts.referencesRoot - The GENERATED tree to install from; defaults to
- *   `compiledSkillRefsDir()`. Injectable so the absent-tree refusal is provable
- *   without deleting `dist/` out from under a concurrent test run (applies
- *   PF-013 — a seam the caller can drive, not a global the test has to break).
- */
-export async function overlayInstalledReferences(opts) {
-    return overlayGeneratedReferences({
-        referencesTarget: path.join(opts.claudeDir, 'skills', prefixSkillName(SKILL_REFS_SKILL_NAME), 'references'),
-        sourceRoot: opts.referencesRoot,
-        manifest: installedReferenceManifest({ provider: opts.provider }),
-        warn: opts.warn,
-    });
-}
 /** The directory inside an installed skill that the reference overlay converges. */
 const SKILL_REFERENCES_DIRNAME = 'references';
 /**
@@ -1229,11 +1192,24 @@ function collectRelativeImports(source) {
 export async function composeScripts(scriptsTarget) {
     await fs.mkdir(scriptsTarget, { recursive: true });
     // (a) src/assets/scripts/ verbatim
+    //
+    // D-SCRIPTS-EXEC-SCOPE: only what this step copied is made executable — each of the
+    // source tree's top-level entries, at its destination. A chmod over the whole target
+    // would also reach what (b) and (c) wrote there on an earlier run (package.json, the
+    // mirrored dist/hud/ closure), so a re-run gave package.json an exec bit the first
+    // run never did and re-init stopped being a no-op on disk (#388 AC-3). Scoping the
+    // chmod to the copied entries makes the first and every later run agree.
     const srcScripts = scriptsDir();
     try {
         await copyDirectory(srcScripts, scriptsTarget);
         if (process.platform !== 'win32') {
-            await chmodRecursive(scriptsTarget, 0o755);
+            for (const entry of await fs.readdir(srcScripts, { withFileTypes: true })) {
+                const copied = path.join(scriptsTarget, entry.name);
+                if (entry.isDirectory())
+                    await chmodRecursive(copied, 0o755);
+                else if (entry.isFile())
+                    await fs.chmod(copied, 0o755);
+            }
         }
     }
     catch { /* scripts dir may not exist yet during development */ }
@@ -1392,11 +1368,11 @@ export async function installViaFileCopy(options) {
         // needed (D-OVERLAY-OWNERSHIP), for the same reason. The agent directory is
         // emptied AROUND the one file `convergeTrackerArtifacts` owns: taking it
         // would leave converge with nothing to byte-compare against, so a
-        // steady-state jira re-init would re-copy the agent and announce
+        // steady-state re-init would re-copy the agent and announce
         // `tracker agent installed` on every run. Everything else is removed
         // exactly as the unconditional wipe removed it, and the file is still
-        // converged on this run — under github converge deletes it, and drift in it
-        // is restored, so preserving it strands nothing.
+        // converged on this run — drift in it is restored, so preserving it strands
+        // nothing.
         try {
             await emptyDirectoryExcept(path.join(claudeDir, 'agents', 'devflow'), new Set([mdFileName(TRACKER_AGENT_NAME)]));
         }
@@ -1451,7 +1427,7 @@ export async function installViaFileCopy(options) {
     // file — including a reference at the references ROOT, which the overlay may replace
     // but never delete (D-OVERLAY-FLAT-UNIT) — does not survive a full install.
     if (!isPartialInstall) {
-        const overlayOwned = overlayOwnedSkillPaths(installedReferenceManifest({ provider: options.trackerProvider }));
+        const overlayOwned = overlayOwnedSkillPaths(installedReferenceManifest());
         for (const skill of skillsMap.keys()) {
             // Empty the prefixed directory (its contents are re-created during the install
             // phase), minus whatever another converger owns inside it.
@@ -1517,14 +1493,12 @@ export async function installViaFileCopy(options) {
     // build/packaging failure and throws rather than silently skipping (matches
     // command pattern); the message names the build step as well as the tree.
     //
-    // D-TRACKER-AGENT-OWNER: every declared agent but ONE. The Tracker agent's
-    // presence is conditional on the resolved provider, and `convergeTrackerArtifacts`
-    // owns that decision alone (plan A3) — it runs after this function in init and is
-    // the sole caller in `devflow tracker --set`. Copying it here too made every
-    // install do the work twice and the two owners contradict each other in both
-    // directions: a github run reported `tracker agent removed` for a file only that
-    // same run had written, and a fresh jira install never reported `installed`
-    // because converge found this loop's byte-identical copy already in place.
+    // D-TRACKER-AGENT-OWNER: every declared agent but ONE. The Tracker agent is
+    // converged by `convergeTrackerArtifacts` alone (plan A3), which runs after this
+    // function in init and reports whether this run wrote it. Copying it here too
+    // would make every install do the work twice, and a fresh install would never
+    // report `installed` because converge would find this loop's byte-identical copy
+    // already in place.
     //
     // The name is skipped from the COPY set only. It stays declared in
     // `devflow-core-skills.agents`, so the sweep below — which keys on the full
@@ -1598,10 +1572,9 @@ export async function installViaFileCopy(options) {
         if (skillName === SKILL_REFS_SKILL_NAME) {
             const overlay = await overlayGeneratedReferences({
                 referencesTarget: path.join(skillTarget, 'references'),
-                // Only the tracker mechanics this install can reach: {github} ∪ the
-                // selected provider. The overlay converges rather than merges, so a
-                // provider left behind by a previous selection is pruned here.
-                manifest: installedReferenceManifest({ provider: options.trackerProvider }),
+                // Every provider's mechanics (D-INSTALL-ALL-PROVIDERS). The overlay
+                // converges rather than merges, so a retired generated document is pruned.
+                manifest: installedReferenceManifest(),
                 warn,
             });
             report.overlaidRefs.push(...overlay.overlaidRefs);