cclaw-cli 0.42.0 → 0.43.0

package/README.md

@@ -135,10 +135,31 @@ Plus harness-specific shims:
   folders are auto-cleaned on sync.)
 - `AGENTS.md` with a managed routing block (includes a Codex-specific note)
 
-`.cclaw/config.yaml` holds every tunable key (prompt guard strictness,
-TDD enforcement, git-hook guards, language rule packs, track heuristics).
-Edit it directly — `cclaw-cli upgrade` preserves your changes. Full key
-reference: [`docs/config.md`](./docs/config.md).
+### `.cclaw/config.yaml` — the minimal surface
+
+`cclaw init` writes five keys, on purpose:
+
+```yaml
+version: 0.43.0
+flowVersion: 1.0.0
+harnesses:
+  - codex
+strictness: advisory     # advisory | strict — one knob for prompt-guard + TDD
+gitHookGuards: false     # opt in to managed .git/hooks/pre-commit + pre-push
+```
+
+If cclaw detects a Node / Python / Go project at init time, a sixth
+`languageRulePacks` line appears (auto-populated from `package.json`,
+`pyproject.toml` / `requirements.txt`, `go.mod`). That is the full
+default surface — a new user sees nothing they need to understand yet.
+
+Advanced knobs (`promptGuardMode` / `tddEnforcement` per-axis overrides,
+`tddTestGlobs`, `defaultTrack`, `trackHeuristics`, `sliceReview`) are
+**opt-in**: add them by hand when you need them. `cclaw upgrade`
+preserves exactly what you wrote — it never silently reintroduces
+defaults you removed.
+
+Full key-by-key reference: [`docs/config.md`](./docs/config.md).
 
 ---
 

package/dist/cli.js

@@ -827,6 +827,11 @@ async function runCommand(parsed, ctx) {
         }
         const trackNote = effectiveTrack ? ` (track=${effectiveTrack})` : "";
         info(ctx, `Initialized .cclaw runtime and generated harness shims${trackNote}`);
+        // Point new users at the one config surface they might actually flip —
+        // `strictness` and `gitHookGuards` — without overselling the other knobs
+        // (those live behind docs/config.md until someone needs them).
+        info(ctx, "Config: .cclaw/config.yaml (strictness=advisory, gitHookGuards=false).");
+        info(ctx, "Need stricter guards or language rule packs? See docs/config.md.");
         await maybeEnableCodexHooksFlag(effectiveHarnesses, parsed, ctx);
         return 0;
     }

package/dist/config.d.ts

@@ -1,5 +1,66 @@
-import type { FlowTrack, HarnessId, VibyConfig } from "./types.js";
+import type { FlowTrack, HarnessId, LanguageRulePack, VibyConfig } from "./types.js";
 export declare function configPath(projectRoot: string): string;
+/**
+ * Default test-file globs used by workflow-guard.sh to detect when a write
+ * targets a test file during TDD. Users rarely need to override this — the
+ * defaults cover TypeScript / JavaScript / Python / Go / Rust / Java layouts.
+ * Exposed so `install.ts` can reuse the same list when seeding the shell
+ * guard script, even though the field is no longer written to the default
+ * `config.yaml` template.
+ */
+export declare const DEFAULT_TDD_TEST_GLOBS: readonly string[];
+/**
+ * Populated runtime view of config values that downstream callers (install,
+ * observe, doctor) consume. Always has the derived guard modes populated,
+ * regardless of whether the user wrote `strictness`, the legacy keys, both,
+ * or neither.
+ */
 export declare function createDefaultConfig(harnesses?: HarnessId[], defaultTrack?: FlowTrack): VibyConfig;
+/**
+ * Probe common project-root manifests to infer which language rule packs the
+ * user would reasonably want. Pure-functional best-effort: any filesystem
+ * error is swallowed, producing an empty list — the user can always override
+ * by hand.
+ *
+ * Called from `cclaw init` only (not `readConfig`), so subsequent upgrades
+ * never surprise a user who intentionally cleared the list.
+ */
+export declare function detectLanguageRulePacks(projectRoot: string): Promise<LanguageRulePack[]>;
 export declare function readConfig(projectRoot: string): Promise<VibyConfig>;
-export declare function writeConfig(projectRoot: string, config: VibyConfig): Promise<void>;
+/**
+ * Fields that live on the populated runtime `VibyConfig` but are considered
+ * "advanced" — we keep them in the in-memory object so downstream callers
+ * don't have to branch, but we do **not** write them to `config.yaml` unless
+ * the user set them explicitly. Keeps the default template small and honest:
+ * only knobs a new user would meaningfully flip show up.
+ */
+type AdvancedConfigKey = "promptGuardMode" | "tddEnforcement" | "tddTestGlobs" | "defaultTrack" | "languageRulePacks" | "trackHeuristics" | "sliceReview";
+/**
+ * Options controlling the serialisation shape of `config.yaml`.
+ *
+ * - `"full"` (default): write every field on the `VibyConfig` object that
+ *   isn't `undefined`. Preserves existing shapes and keeps legacy callers
+ *   working without migration.
+ * - `"minimal"`: write only the user-facing knobs (`MINIMAL_CONFIG_KEYS`)
+ *   plus any non-empty `languageRulePacks` (so auto-detected values survive
+ *   a fresh `cclaw init`). Use this when generating the default template;
+ *   power users can still add advanced keys by hand.
+ *
+ * `advancedKeysPresent` upgrades an otherwise-minimal serialisation by
+ * including the listed advanced keys. `cclaw upgrade` uses it to preserve
+ * the exact shape a user hand-authored, while still re-minimising configs
+ * where the user stayed at defaults.
+ */
+export interface WriteConfigOptions {
+    mode?: "full" | "minimal";
+    advancedKeysPresent?: ReadonlySet<AdvancedConfigKey>;
+}
+export declare function writeConfig(projectRoot: string, config: VibyConfig, options?: WriteConfigOptions): Promise<void>;
+/**
+ * Enumerate which advanced keys are currently set in the on-disk config.
+ * Used by `cclaw upgrade` to preserve the user's existing shape — if they
+ * wrote `tddTestGlobs` by hand, the upgrade keeps it; if they didn't, the
+ * upgrade stays minimal.
+ */
+export declare function detectAdvancedKeys(projectRoot: string): Promise<ReadonlySet<AdvancedConfigKey>>;
+export {};

package/dist/config.js

@@ -15,6 +15,7 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "version",
     "flowVersion",
     "harnesses",
+    "strictness",
     "promptGuardMode",
     "tddEnforcement",
     "tddTestGlobs",
@@ -24,6 +25,21 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "trackHeuristics",
     "sliceReview"
 ]);
+/**
+ * Config keys always present in the minimal init template. Everything else
+ * is "advanced" — parsed when present, but not pre-populated by `cclaw init`.
+ *
+ * Deliberately small: a first-time user should only see knobs they might
+ * actually flip. Power users override by adding more keys by hand; the
+ * reference lives in `docs/config.md`.
+ */
+const MINIMAL_CONFIG_KEYS = [
+    "version",
+    "flowVersion",
+    "harnesses",
+    "strictness",
+    "gitHookGuards"
+];
 const DEFAULT_SLICE_REVIEW_THRESHOLD = 5;
 const DEFAULT_SLICE_REVIEW_TRACKS = ["standard"];
 function configFixExample() {
@@ -57,19 +73,78 @@ function validateStringArray(value, fieldName, configFilePath) {
 export function configPath(projectRoot) {
     return path.join(projectRoot, CONFIG_PATH);
 }
+/**
+ * Default test-file globs used by workflow-guard.sh to detect when a write
+ * targets a test file during TDD. Users rarely need to override this — the
+ * defaults cover TypeScript / JavaScript / Python / Go / Rust / Java layouts.
+ * Exposed so `install.ts` can reuse the same list when seeding the shell
+ * guard script, even though the field is no longer written to the default
+ * `config.yaml` template.
+ */
+export const DEFAULT_TDD_TEST_GLOBS = [
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**"
+];
+/**
+ * Populated runtime view of config values that downstream callers (install,
+ * observe, doctor) consume. Always has the derived guard modes populated,
+ * regardless of whether the user wrote `strictness`, the legacy keys, both,
+ * or neither.
+ */
 export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, defaultTrack = "standard") {
     return {
         version: CCLAW_VERSION,
         flowVersion: FLOW_VERSION,
         harnesses,
+        strictness: "advisory",
         promptGuardMode: "advisory",
         tddEnforcement: "advisory",
-        tddTestGlobs: ["**/*.test.*", "**/*.spec.*", "**/test/**"],
+        tddTestGlobs: [...DEFAULT_TDD_TEST_GLOBS],
         gitHookGuards: false,
         defaultTrack,
         languageRulePacks: []
     };
 }
+/**
+ * Probe common project-root manifests to infer which language rule packs the
+ * user would reasonably want. Pure-functional best-effort: any filesystem
+ * error is swallowed, producing an empty list — the user can always override
+ * by hand.
+ *
+ * Called from `cclaw init` only (not `readConfig`), so subsequent upgrades
+ * never surprise a user who intentionally cleared the list.
+ */
+export async function detectLanguageRulePacks(projectRoot) {
+    const detected = [];
+    const pkgPath = path.join(projectRoot, "package.json");
+    if (await exists(pkgPath)) {
+        try {
+            const pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+            const deps = {
+                ...pkg.dependencies,
+                ...pkg.devDependencies
+            };
+            if ("typescript" in deps || typeof pkg.types === "string") {
+                detected.push("typescript");
+            }
+        }
+        catch {
+            // Malformed package.json — skip; user can set the pack manually later.
+        }
+    }
+    const pythonMarkers = ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"];
+    for (const marker of pythonMarkers) {
+        if (await exists(path.join(projectRoot, marker))) {
+            detected.push("python");
+            break;
+        }
+    }
+    if (await exists(path.join(projectRoot, "go.mod"))) {
+        detected.push("go");
+    }
+    return [...new Set(detected)];
+}
 export async function readConfig(projectRoot) {
     const fullPath = configPath(projectRoot);
     if (!(await exists(fullPath))) {
@@ -105,23 +180,39 @@ export async function readConfig(projectRoot) {
     const harnesses = hasHarnessesField
         ? [...new Set(validatedHarnesses)]
         : DEFAULT_HARNESSES;
+    const strictnessRaw = parsed.strictness;
+    if (Object.prototype.hasOwnProperty.call(parsed, "strictness") &&
+        strictnessRaw !== "advisory" &&
+        strictnessRaw !== "strict") {
+        throw configValidationError(fullPath, `"strictness" must be "advisory" or "strict"`);
+    }
+    const strictness = strictnessRaw === "strict" ? "strict" : "advisory";
+    // Legacy guard fields — keep honouring explicit values for power users who
+    // want asymmetric behaviour (e.g. strict prompt guard + advisory TDD).
+    // When the user only set `strictness`, both axes inherit from it.
+    const hasExplicitPromptGuard = Object.prototype.hasOwnProperty.call(parsed, "promptGuardMode");
     const promptGuardModeRaw = parsed.promptGuardMode;
-    if (Object.prototype.hasOwnProperty.call(parsed, "promptGuardMode") &&
+    if (hasExplicitPromptGuard &&
         promptGuardModeRaw !== "advisory" &&
         promptGuardModeRaw !== "strict") {
         throw configValidationError(fullPath, `"promptGuardMode" must be "advisory" or "strict"`);
     }
-    const promptGuardMode = promptGuardModeRaw === "strict" ? "strict" : "advisory";
+    const promptGuardMode = hasExplicitPromptGuard
+        ? (promptGuardModeRaw === "strict" ? "strict" : "advisory")
+        : strictness;
+    const hasExplicitTddEnforcement = Object.prototype.hasOwnProperty.call(parsed, "tddEnforcement");
     const tddEnforcementRaw = parsed.tddEnforcement;
-    if (Object.prototype.hasOwnProperty.call(parsed, "tddEnforcement") &&
+    if (hasExplicitTddEnforcement &&
         tddEnforcementRaw !== "advisory" &&
         tddEnforcementRaw !== "strict") {
         throw configValidationError(fullPath, `"tddEnforcement" must be "advisory" or "strict"`);
     }
-    const tddEnforcement = tddEnforcementRaw === "strict" ? "strict" : "advisory";
+    const tddEnforcement = hasExplicitTddEnforcement
+        ? (tddEnforcementRaw === "strict" ? "strict" : "advisory")
+        : strictness;
     const tddTestGlobsRaw = parsed.tddTestGlobs;
     const tddTestGlobs = validateStringArray(tddTestGlobsRaw, "tddTestGlobs", fullPath)
-        ?? ["**/*.test.*", "**/*.spec.*", "**/test/**"];
+        ?? [...DEFAULT_TDD_TEST_GLOBS];
     const gitHookGuardsRaw = parsed.gitHookGuards;
     if (Object.prototype.hasOwnProperty.call(parsed, "gitHookGuards") &&
         typeof gitHookGuardsRaw !== "boolean") {
@@ -232,6 +323,7 @@ export async function readConfig(projectRoot) {
         version: parsed.version ?? CCLAW_VERSION,
         flowVersion: parsed.flowVersion ?? FLOW_VERSION,
         harnesses,
+        strictness,
         promptGuardMode,
         tddEnforcement,
         tddTestGlobs,
@@ -242,6 +334,88 @@ export async function readConfig(projectRoot) {
         sliceReview
     };
 }
-export async function writeConfig(projectRoot, config) {
-    await writeFileSafe(configPath(projectRoot), stringify(config));
+function isMinimalKey(key) {
+    return MINIMAL_CONFIG_KEYS.includes(key);
+}
+function buildSerializableConfig(config, options = {}) {
+    const mode = options.mode ?? "full";
+    const advanced = options.advancedKeysPresent;
+    const output = {};
+    const ordered = [
+        "version",
+        "flowVersion",
+        "harnesses",
+        "strictness",
+        "promptGuardMode",
+        "tddEnforcement",
+        "tddTestGlobs",
+        "gitHookGuards",
+        "defaultTrack",
+        "languageRulePacks",
+        "trackHeuristics",
+        "sliceReview"
+    ];
+    for (const key of ordered) {
+        const value = config[key];
+        if (value === undefined)
+            continue;
+        if (mode === "full") {
+            output[key] = value;
+            continue;
+        }
+        // Minimal mode: always include the short list; advanced keys only when
+        // the caller explicitly opted in, or for auto-detected non-empty
+        // `languageRulePacks`.
+        if (isMinimalKey(key)) {
+            output[key] = value;
+            continue;
+        }
+        if (advanced?.has(key)) {
+            output[key] = value;
+            continue;
+        }
+        if (key === "languageRulePacks" && Array.isArray(value) && value.length > 0) {
+            output[key] = value;
+        }
+    }
+    return output;
+}
+export async function writeConfig(projectRoot, config, options = {}) {
+    const serialisable = buildSerializableConfig(config, options);
+    await writeFileSafe(configPath(projectRoot), stringify(serialisable));
+}
+/**
+ * Enumerate which advanced keys are currently set in the on-disk config.
+ * Used by `cclaw upgrade` to preserve the user's existing shape — if they
+ * wrote `tddTestGlobs` by hand, the upgrade keeps it; if they didn't, the
+ * upgrade stays minimal.
+ */
+export async function detectAdvancedKeys(projectRoot) {
+    const fullPath = configPath(projectRoot);
+    if (!(await exists(fullPath)))
+        return new Set();
+    try {
+        const parsedUnknown = parse(await fs.readFile(fullPath, "utf8"));
+        if (!isRecord(parsedUnknown))
+            return new Set();
+        const advancedCandidates = [
+            "promptGuardMode",
+            "tddEnforcement",
+            "tddTestGlobs",
+            "defaultTrack",
+            "languageRulePacks",
+            "trackHeuristics",
+            "sliceReview"
+        ];
+        const present = new Set();
+        for (const key of advancedCandidates) {
+            if (Object.prototype.hasOwnProperty.call(parsedUnknown, key)) {
+                present.add(key);
+            }
+        }
+        return present;
+    }
+    catch {
+        return new Set();
+    }
 }

package/dist/install.d.ts

@@ -9,13 +9,12 @@ export declare function syncCclaw(projectRoot: string): Promise<void>;
 /**
  * Refresh generated files in `.cclaw/` without touching user-authored
  * artifacts, state, or custom config keys. Only the `version` + `flowVersion`
- * stamps are rewritten so the on-disk config reflects the installed CLI;
- * `promptGuardMode`, `tddEnforcement`, `gitHookGuards`, `languageRulePacks`,
- * `trackHeuristics`, and `sliceReview` are preserved verbatim from the
- * existing config.
+ * stamps are rewritten so the on-disk config reflects the installed CLI.
  *
- * For an explicit reset, run `cclaw-cli uninstall && cclaw-cli init`
- * (after optionally archiving the current run via `/cc-ops archive`).
+ * Shape preservation: if the user previously hand-authored advanced keys
+ * (e.g. `tddTestGlobs`, `trackHeuristics`, `sliceReview`), those stay in the
+ * yaml. If their existing config is minimal, the upgrade keeps it minimal —
+ * advanced knobs are never silently added.
  */
 export declare function upgradeCclaw(projectRoot: string): Promise<void>;
 export declare function uninstallCclaw(projectRoot: string): Promise<void>;

package/dist/install.js

@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 import { CCLAW_VERSION, COMMAND_FILE_ORDER, FLOW_VERSION, REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
-import { writeConfig, createDefaultConfig, readConfig, configPath } from "./config.js";
+import { writeConfig, createDefaultConfig, readConfig, configPath, detectLanguageRulePacks, detectAdvancedKeys } from "./config.js";
 import { commandContract } from "./content/contracts.js";
 import { contextModeFiles, createInitialContextModeState } from "./content/contexts.js";
 import { learnSkillMarkdown, learnCommandContract } from "./content/learnings.js";
@@ -1156,13 +1156,24 @@ async function materializeRuntime(projectRoot, config, forceStateReset) {
     await ensureGitignore(projectRoot);
 }
 export async function initCclaw(options) {
-    const config = createDefaultConfig(options.harnesses, options.track);
-    await writeConfig(options.projectRoot, config);
+    const baseConfig = createDefaultConfig(options.harnesses, options.track);
+    // Best-effort auto-detect: a Node project gets `typescript`, a Go module
+    // gets `go`, etc. Skipped entirely when the project root has no manifests.
+    const detectedPacks = await detectLanguageRulePacks(options.projectRoot);
+    const config = {
+        ...baseConfig,
+        languageRulePacks: detectedPacks
+    };
+    // Write a minimal `config.yaml` — advanced knobs live in docs/config.md
+    // and only appear in the on-disk file when the user sets them explicitly
+    // or a non-default value was detected (e.g. languageRulePacks).
+    await writeConfig(options.projectRoot, config, { mode: "minimal" });
     await materializeRuntime(options.projectRoot, config, true);
 }
 export async function syncCclaw(projectRoot) {
+    const configExists = await exists(configPath(projectRoot));
     const config = await readConfig(projectRoot);
-    if (!(await exists(configPath(projectRoot)))) {
+    if (!configExists) {
         await writeConfig(projectRoot, createDefaultConfig(config.harnesses));
     }
     await materializeRuntime(projectRoot, config, false);
@@ -1170,22 +1181,25 @@ export async function syncCclaw(projectRoot) {
 /**
  * Refresh generated files in `.cclaw/` without touching user-authored
  * artifacts, state, or custom config keys. Only the `version` + `flowVersion`
- * stamps are rewritten so the on-disk config reflects the installed CLI;
- * `promptGuardMode`, `tddEnforcement`, `gitHookGuards`, `languageRulePacks`,
- * `trackHeuristics`, and `sliceReview` are preserved verbatim from the
- * existing config.
+ * stamps are rewritten so the on-disk config reflects the installed CLI.
  *
- * For an explicit reset, run `cclaw-cli uninstall && cclaw-cli init`
- * (after optionally archiving the current run via `/cc-ops archive`).
+ * Shape preservation: if the user previously hand-authored advanced keys
+ * (e.g. `tddTestGlobs`, `trackHeuristics`, `sliceReview`), those stay in the
+ * yaml. If their existing config is minimal, the upgrade keeps it minimal —
+ * advanced knobs are never silently added.
  */
 export async function upgradeCclaw(projectRoot) {
+    const advancedKeysPresent = await detectAdvancedKeys(projectRoot);
     const existing = await readConfig(projectRoot);
     const upgraded = {
         ...existing,
         version: CCLAW_VERSION,
         flowVersion: FLOW_VERSION
     };
-    await writeConfig(projectRoot, upgraded);
+    await writeConfig(projectRoot, upgraded, {
+        mode: "minimal",
+        advancedKeysPresent
+    });
     await materializeRuntime(projectRoot, upgraded, false);
 }
 function stripManagedHookCommands(value) {

package/dist/types.d.ts

@@ -92,9 +92,30 @@ export interface VibyConfig {
     version: string;
     flowVersion: string;
     harnesses: HarnessId[];
-    /** Prompt guard behavior for runtime write-risk detection hooks. */
+    /**
+     * Single-knob strictness for both guard families. When set, cclaw derives
+     * `promptGuardMode` and `tddEnforcement` from this value unless the legacy
+     * fields are explicitly provided. Default: "advisory".
+     *
+     * Added in v0.43.0 to collapse two fields that always moved together for
+     * ~99% of users. Power users who want asymmetric strictness (e.g. strict
+     * prompt guard, advisory TDD) can still set the legacy fields directly —
+     * explicit per-axis values override the derived strictness.
+     */
+    strictness?: "advisory" | "strict";
+    /**
+     * Prompt guard behavior for runtime write-risk detection hooks.
+     *
+     * Since v0.43.0 this is an advanced override. Prefer `strictness` in new
+     * configs; set this explicitly only when you need strict prompt guarding
+     * while keeping TDD advisory, or vice versa.
+     */
     promptGuardMode?: "advisory" | "strict";
-    /** TDD red->green->refactor enforcement mode used by workflow guard hooks. */
+    /**
+     * TDD red->green->refactor enforcement mode used by workflow guard hooks.
+     *
+     * Since v0.43.0 this is an advanced override — see `strictness`.
+     */
     tddEnforcement?: "advisory" | "strict";
     /** Optional test file globs used by guard guidance and /cc-ops tdd-log docs. */
     tddTestGlobs?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {