devflow-kit 2.3.0 → 2.5.0

package/dist/core/flags.js

@@ -11,6 +11,17 @@
  * point every caller reaches). applyFlags(settingsJson, FlagsRecord) is the
  * sole API; init.ts works directly with FlagsRecord (no legacy string[] bridge).
  */
+import { isDeepStrictEqual } from 'node:util';
+/**
+ * Type predicate that narrows `ClaudeCodeFlag` to `EnvBooleanFlagDef`.
+ * Narrows `f.onPayload` to `string` so callers writing to the env string-map
+ * avoid an `unknown` hop without an unsafe cast.
+ *
+ * Use in `buildPayload` and `applyFlags` only where the string type is load-bearing.
+ */
+export function isEnvBooleanFlag(f) {
+    return f.kind === 'boolean' && f.target.type === 'env';
+}
 // ─── Registry ─────────────────────────────────────────────────────────────────
 // Phase 0 probe findings: see docs/reference/claude-code-flags-probe.md
 /**
@@ -110,8 +121,8 @@ export const FLAG_REGISTRY = [
         kind: 'boolean',
         target: { type: 'setting', key: 'disableBundledSkills' },
         onPayload: true,
-        recommended: true,
-        defaultValue: true,
+        recommended: false,
+        defaultValue: false,
     },
     {
         id: 'pin-sonnet-4-6',
@@ -122,8 +133,8 @@ export const FLAG_REGISTRY = [
         kind: 'boolean',
         target: { type: 'env', key: 'ANTHROPIC_DEFAULT_SONNET_MODEL' },
         onPayload: 'claude-sonnet-4-6',
-        recommended: true,
-        defaultValue: true,
+        recommended: false,
+        defaultValue: false,
     },
     {
         // Devflow fan-outs routinely exceed the upstream default of 20.
@@ -309,6 +320,24 @@ export const FLAG_REGISTRY = [
         recommended: false,
         defaultValue: false,
     },
+    {
+        // D27: gates Claude Code's AI-attribution injection into git commits and PRs.
+        // When true, writes {"commit":"","pr":""} to settings.json which suppresses attribution.
+        // When false/null (neutral), removes the key ONLY when the current value is the exact
+        // devflow-managed shape (settingDeleteGuard). A custom attribution value (e.g. an org
+        // name) is never deleted — shape guard prevents erasure (D-ATTR-GUARD).
+        id: 'suppress-attribution',
+        label: 'Suppress AI attribution',
+        description: 'Remove AI-attribution labels from git commits and pull requests',
+        hint: 'Suppresses Claude attribution labels in git commits and pull requests',
+        blurb: 'hide AI attribution labels',
+        kind: 'boolean',
+        target: { type: 'setting', key: 'attribution' },
+        onPayload: { commit: '', pr: '' },
+        settingDeleteGuard: { commit: '', pr: '' },
+        recommended: false,
+        defaultValue: false,
+    },
     // ── Valued flags (number/enum/string) ────────────────────────────────────
     {
         // Domain: unset by default; set only when users want a non-default spawn depth.
@@ -837,6 +866,78 @@ export function migrateLegacyFlagsToRecord(enabledIds, knownIds, legacyViewMode)
     return result;
 }
 // ─── Apply / Strip ────────────────────────────────────────────────────────────
+/**
+ * Returns true when `value` equals the managed shape declared by `flag.settingDeleteGuard`.
+ * Returns false when: the flag has no guard, is not a setting-target boolean, or the value
+ * does not deep-equal the guard.
+ *
+ * Single equality oracle for managed-shape comparisons — used by `canDeleteSettingKey`,
+ * `settingHoldsManagedShape`, and the Step 2b adoption fold in `convergeFlagsIntoSettings`.
+ * All three delegate here so there is exactly one `isDeepStrictEqual` call for guard matching.
+ */
+export function settingValueHoldsManagedShape(flag, value) {
+    if (flag.kind !== 'boolean' || flag.target.type !== 'setting')
+        return false;
+    const guard = flag.settingDeleteGuard;
+    if (guard === undefined)
+        return false;
+    return isDeepStrictEqual(value, guard);
+}
+/**
+ * D-ATTR-GUARD single-source predicate (consistency-01 / ADR-024).
+ *
+ * Returns true when the settings.json string contains a value at the flag's
+ * target key that equals the flag's managed shape (`settingDeleteGuard`).
+ *
+ * This is the ONE place that decides "on-disk value equals the managed shape".
+ * All consumers — `resolveExistingAttributionSuppression` (seeding priority),
+ * and the guarded-boolean adoption fold in `convergeFlagsIntoSettings` — delegate
+ * here rather than hand-rolling their own comparison.
+ *
+ * Returns false when:
+ *   - settingsJson is malformed
+ *   - root is not a plain object
+ *   - flagId is not in the registry
+ *   - the flag has no settingDeleteGuard
+ *   - the flag is not a setting-target boolean
+ *   - the on-disk value does not deep-equal the guard
+ */
+export function settingHoldsManagedShape(settingsJson, flagId) {
+    try {
+        const parsed = JSON.parse(settingsJson);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return false;
+        const flag = FLAG_REGISTRY_MAP.get(flagId);
+        if (!flag)
+            return false;
+        const value = parsed[flag.target.key];
+        return settingValueHoldsManagedShape(flag, value);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * D-ATTR-GUARD: returns true when it is safe to delete a flag's target key from
+ * settings. For flags with a settingDeleteGuard the key is only deleted when the
+ * current on-disk value deep-equals the managed shape, preventing erasure of
+ * user-customized values (e.g. an organisation attribution block) on flag
+ * disable or uninstall. Flags without a guard are always safe to delete.
+ *
+ * Delegates to `settingValueHoldsManagedShape` — the single equality oracle for
+ * managed-shape comparisons — so there is exactly one `isDeepStrictEqual` call
+ * across the entire apply/strip pipeline (ADR-024 mechanism 3).
+ *
+ * Single-source invariant: both the disable path (applyFlags neutral branch) and
+ * the uninstall path (stripFlags) collapse to this predicate.
+ */
+function canDeleteSettingKey(flag, settings) {
+    if (flag.kind !== 'boolean')
+        return true;
+    if (flag.settingDeleteGuard === undefined)
+        return true;
+    return settingValueHoldsManagedShape(flag, settings[flag.target.key]);
+}
 /**
  * Return `v` as a `Record<string, unknown>` only when it is a plain object.
  * Returns undefined for arrays, null, or non-objects.
@@ -853,8 +954,17 @@ function asPlainObject(v) {
 /** Compute the value to write to settings.json for an active flag. */
 function buildPayload(flag, value) {
     switch (flag.kind) {
-        case 'boolean':
-            return flag.onPayload;
+        case 'boolean': {
+            // D-PAYLOAD-CLONE: return a structural clone for object payloads so the
+            // FLAG_REGISTRY entry is never aliased into the caller's settings tree.
+            // Primitives (string, boolean) are values and require no clone.
+            // isEnvBooleanFlag narrows onPayload to string for env flags — no clone needed,
+            // and the string type avoids an `unknown` hop into the env string-map.
+            if (isEnvBooleanFlag(flag))
+                return flag.onPayload; // string — no clone needed
+            const p = flag.onPayload;
+            return typeof p === 'object' && p !== null ? structuredClone(p) : p;
+        }
         case 'enum':
             return value;
         case 'number':
@@ -904,7 +1014,8 @@ export function applyFlags(settingsJson, flags) {
                     delete env[flag.target.key];
             }
             else {
-                delete settings[flag.target.key];
+                if (canDeleteSettingKey(flag, settings))
+                    delete settings[flag.target.key];
             }
         }
         else {
@@ -949,7 +1060,8 @@ export function stripFlags(settingsJson) {
                 delete env[flag.target.key];
         }
         else {
-            delete settings[flag.target.key];
+            if (canDeleteSettingKey(flag, settings))
+                delete settings[flag.target.key];
         }
     }
     if (env && Object.keys(env).length === 0) {
@@ -1116,6 +1228,35 @@ export function convergeFlagsIntoSettings(settingsJson, record, opts) {
             folded[flag.id] = coerced;
         }
     }
+    // ── Step 2b: adopt guarded boolean settings before the strip ─────────────
+    // D-ATTR-ADOPT (PF-050 / ADR-024): a delete guard is evidence about the VALUE,
+    // never about the record — a pre-existing on-disk key whose value matches the
+    // managed shape means devflow wrote it, so adopt it into the record now, before
+    // stripFlags can unconditionally remove it on the next line.
+    //
+    // Mirror of the view-mode fold (Step 1): adopt only when:
+    //   (a) the flag has a settingDeleteGuard (guarded boolean only)
+    //   (b) the record does NOT already claim the key — a claimed false or null still
+    //       deletes the managed block (the user intentionally disabled it)
+    //   (c) the pre-strip on-disk value holds the managed shape
+    //
+    // This fold runs before stripFlags so applyFlags rewrites the block from the
+    // now-claimed record and the block survives on BOTH the init and flags paths.
+    for (const flag of FLAG_REGISTRY) {
+        if (flag.kind !== 'boolean')
+            continue;
+        if (flag.target.type !== 'setting')
+            continue;
+        // Skip when the record already claims this flag (claimed false/null deletes the block)
+        const claimed = claimedIn !== null &&
+            Object.prototype.hasOwnProperty.call(claimedIn, flag.id);
+        if (claimed)
+            continue;
+        // Adopt only when the on-disk value matches the managed shape exactly
+        if (settingValueHoldsManagedShape(flag, parsed[flag.target.key])) {
+            folded[flag.id] = true;
+        }
+    }
     // ── Step 3: strip all managed keys, then apply the folded record ──────────
     const stripped = stripFlags(settingsJson);
     const settings = applyFlags(stripped, folded);

package/dist/core/manifest.js

@@ -3,6 +3,7 @@ import * as path from 'path';
 import { LEGACY_PLUGIN_NAMES, DELETED_PLUGIN_NAMES } from './plugins.js';
 import { VIEW_MODES, migrateLegacyFlagsToRecord, sanitizeFlagsRecord, } from './flags.js';
 import { normalizeComplianceFeature } from './compliance.js';
+import { normalizeTrackerFeature } from './tracker.js';
 import { writeFileAtomicExclusive } from './fs-atomic.js';
 /**
  * Parse features.flags across the three on-disk shapes; reports whether a heal is owed.
@@ -54,13 +55,14 @@ function parseManifestFlags(features, knownFlags) {
  * Read and parse the manifest file. Returns null if missing or corrupt.
  *
  * Self-heals the following on-disk inconsistencies (applies ADR-014):
- * - features.kb → features.knowledge rename
- * - features.decisions → features.learning rename
+ * - features.kb → features.knowledge rename (both absent → true, D-FEATURES-ABSENT-ON)
+ * - features.decisions → features.learning rename (both absent → true, D-FEATURES-ABSENT-ON)
  * - features.flags as string[] → FlagsRecord (via migrateLegacyFlagsToRecord)
  * - features.viewMode folded into flags['view-mode'] and stripped from result
  * - features.knownFlags stripped from result (folded into FlagsRecord key-presence)
  * - features.proxy absent → false
  * - features.compliance absent/malformed → {enabled:false, frameworks:[]}
+ * - features.tracker absent/malformed → {provider:'github'}
  *
  * D39: heal-write failure returns the migrated in-memory manifest (not null).
  * The on-disk format remains unhealed; next read triggers another attempt.
@@ -82,15 +84,33 @@ export async function readManifest(devflowDir) {
             typeof data.updatedAt !== 'string') {
             return null;
         }
-        // Self-heal: rename features.kb → features.knowledge on disk
+        // D-FEATURES-ABSENT-ON (a sub-decision of D-FEATURES-MACHINE-WIDE,
+        // src/core/feature-switch.ts): knowledge and learning are machine-wide
+        // switches, and every runtime gate — queue_read_gates in the hooks,
+        // isMachineFeatureOn in the CLI, the knowledge write-back prose gate — reads
+        // an ABSENT key as ON. This reader must agree: init seeds from it and every
+        // syncManifestFeature toggle writes its result back, so a `false` default
+        // here would persist "off" for a feature the runtime is running — a plain
+        // re-init or `devflow hud --enable` on an older manifest silently switching
+        // it off machine-wide. Explicit booleans (and their legacy names) are kept
+        // as they are. memory needs no default: it is in the hard-null set above,
+        // so a manifest without it reads as no prior install and init seeds
+        // FEATURE_DEFAULTS.memory (true).
+        //
+        // Self-heal: rename features.kb → features.knowledge on disk.
+        // Coalesce: features.knowledge wins; fall back to features.kb; default ON.
+        // D-KNOWLEDGE-LEGACY-KB: isMachineFeatureOn applies this exact precedence,
+        // so the legacy key is honoured before the heal lands.
         const knowledge = typeof features.knowledge === 'boolean' ? features.knowledge
             : typeof features.kb === 'boolean' ? features.kb
-                : false;
-        // Self-heal: rename features.decisions → features.learning on disk
-        // Coalesce: features.learning wins; fall back to features.decisions; default false.
+                : true;
+        // Self-heal: rename features.decisions → features.learning on disk (ADR-011).
+        // Coalesce: features.learning wins; fall back to features.decisions; default ON.
+        // D-LEARNING-LEGACY-DECISIONS: isMachineFeatureOn and queue_read_gates apply
+        // this exact precedence, so the legacy key is honoured before the heal lands.
         const learning = typeof features.learning === 'boolean' ? features.learning
             : typeof features.decisions === 'boolean' ? features.decisions
-                : false;
+                : true;
         // Self-heal: non-string-array or absent knownFlags/knownPlugins → undefined (never partial/garbage)
         const asStringArray = (val) => Array.isArray(val) && val.every(e => typeof e === 'string')
             ? val
@@ -138,6 +158,12 @@ export async function readManifest(devflowDir) {
                 proxy: typeof features.proxy === 'boolean' ? features.proxy : false,
                 // Self-heal: absent/malformed compliance → {enabled:false, frameworks:[]}
                 compliance: normalizeComplianceFeature(features.compliance),
+                // Self-heal: absent/malformed/unknown tracker → {provider:'github'} (AC-3.21).
+                // Deliberately NOT in the hard-null set above — see the field's doc comment.
+                // Healing here is silent and emits no DEGRADED: that is the correct
+                // ADR-014 behaviour, and a different condition from a per-repo config
+                // value outside the domain (which does emit `unknown tracker provider`).
+                tracker: normalizeTrackerFeature(features.tracker),
             },
             installedAt: data.installedAt,
             updatedAt: data.updatedAt,