cclaw-cli 0.41.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).
 
 ---
 
@@ -152,7 +173,7 @@ inside `/cc-ops` subcommands.
 |---|---|
 | **`/cc <idea>`** | Classify the task, discover origin docs (`docs/prd/**`, ADRs, root `PRD.md`, …), sniff the stack, recommend a track, then start the first stage of that track. `/cc` without arguments resumes the current flow. |
 | **`/cc-next`** | The one progression primitive. Reads `flow-state.json`, checks gates + mandatory subagent delegations, and either resumes the current stage or advances to the next. `/cc-next` in a new session is how you **resume**. |
-| **`/cc-ideate`** | Repository improvement discovery. Scans for TODOs, flaky tests, oversized modules, docs drift, and recurring knowledge-store lessons; returns a ranked backlog before you commit to a specific feature. |
+| **`/cc-ideate`** | Repository improvement discovery. Scans for TODOs, flaky tests, oversized modules, docs drift, and recurring knowledge-store lessons, **persists the ranked backlog** to `.cclaw/artifacts/ideation-<date>-<slug>.md`, and ends with a concrete handoff: launch `/cc` on the selected candidate in the same session, save-and-close, or discard. Resume check on next run reuses any ideation artifact younger than 30 days. Never mutates `flow-state.json`. |
 | **`/cc-view`** | Read-only flow visibility. `/cc-view status` (default) shows stage progress, mandatory delegations with their fulfillment mode (isolated / generic-dispatch / role-switch), the ship closeout substate (retro → compound → archive), and the active harness parity row. `/cc-view tree` renders the same picture as a tree with a closeout sub-branch under ship and a per-harness playbook summary. `/cc-view diff` shows stage/gate/closeout/delegation deltas since the last run. Never mutates state (except diff's snapshot baseline). |
 
 > Power-user surface: `/cc-ops` is an operational router for manual

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/content/ideate-command.d.ts

@@ -1,2 +1,9 @@
 export declare function ideateCommandContract(): string;
 export declare function ideateCommandSkillMarkdown(): string;
+/**
+ * Exposed for tests and docs that need to mention the artifact convention
+ * without hard-coding the path string in two places.
+ */
+export declare const IDEATION_ARTIFACT_PATH_PATTERN = ".cclaw/artifacts/ideation-<YYYY-MM-DD-slug>.md";
+export declare const IDEATION_ARTIFACT_GLOB_PATTERN = ".cclaw/artifacts/ideation-*.md";
+export declare const IDEATION_RESUME_WINDOW = 30;

package/dist/content/ideate-command.js

@@ -1,39 +1,62 @@
 import { RUNTIME_ROOT } from "../constants.js";
 const IDEATE_SKILL_FOLDER = "flow-ideate";
 const IDEATE_SKILL_NAME = "flow-ideate";
+/**
+ * Directory + filename convention for ideation artifacts. These are separate
+ * from stage artifacts (00-..08-*.md) because `/cc-ideate` runs outside the
+ * critical-path flow state machine and must not collide with stage numbering.
+ */
+const IDEATION_ARTIFACT_GLOB = ".cclaw/artifacts/ideation-*.md";
+const IDEATION_ARTIFACT_PATTERN = ".cclaw/artifacts/ideation-<YYYY-MM-DD-slug>.md";
+const IDEATION_RESUME_WINDOW_DAYS = 30;
+/**
+ * Structured-ask tool list reused across cclaw skills. Kept inline here (small
+ * enough) to avoid cross-module coupling; larger stage skills cite the shared
+ * protocol file instead.
+ */
+const STRUCTURED_ASK_TOOLS = "`AskUserQuestion` on Claude, `AskQuestion` on Cursor, " +
+    "`question` on OpenCode when `permission.question: \"allow\"` is set, " +
+    "`request_user_input` on Codex in Plan / Collaboration mode; " +
+    "fall back to a plain-text lettered list when the tool is hidden or errors";
 export function ideateCommandContract() {
     return `# /cc-ideate
 
 ## Purpose
 
-Repository-improvement discovery mode. Generate a ranked backlog of high-value
-improvements before committing to a specific feature request.
+Repository-improvement discovery mode. Generate a ranked backlog of
+high-value improvements, persist it as an artifact on disk, and end with
+an explicit handoff — either launch \`/cc\` on a chosen candidate in the
+same session, or save/discard the backlog.
 
 ## HARD-GATE
 
-- This is discovery mode only. Do not start implementation automatically.
-- Every recommendation must include evidence from the current repository.
-- End with a decision prompt: pick one candidate or cancel.
+- Discovery mode only. Never mutate \`.cclaw/state/flow-state.json\`.
+- Every recommendation cites evidence from the current repository
+  (file path, command output, or knowledge-store entry id).
+- Always write a persisted artifact to
+  \`${IDEATION_ARTIFACT_PATTERN}\`. Chat-only output is not acceptable —
+  the next session must be able to resume.
+- Always end with a structured handoff prompt, not an open question.
 
 ## Algorithm
 
-1. Scan repo signals:
-   - open TODO/backlog notes
-   - flaky or failing tests
-   - oversized modules / complexity hotspots
-   - docs drift vs changed code
-   - repeated learnings from \`.cclaw/knowledge.jsonl\`
-2. Produce 5-10 candidates with:
-   - impact (High/Medium/Low)
-   - effort (S/M/L)
-   - confidence (High/Medium/Low)
-   - evidence path(s)
-3. Rank candidates by impact/effort ratio.
-4. Present one recommendation as default.
-5. Ask user to choose:
-   - (A) start with recommended item
-   - (B) choose another candidate
-   - (C) cancel
+1. **Resume check.** Glob \`${IDEATION_ARTIFACT_GLOB}\`. If any artifact
+   has been modified within the last ${IDEATION_RESUME_WINDOW_DAYS} days,
+   offer the user: continue that backlog, start fresh, or cancel.
+2. **Scan repo signals:**
+   - open TODO/FIXME/XXX/HACK notes,
+   - flaky or failing tests,
+   - oversized modules / complexity hotspots,
+   - docs drift vs changed code,
+   - repeated entries in \`${RUNTIME_ROOT}/knowledge.jsonl\`.
+3. **Produce 5-10 candidates** with impact (High/Medium/Low),
+   effort (S/M/L), confidence (High/Medium/Low), and one evidence path
+   per candidate.
+4. **Rank by impact/effort**, recommend the top item.
+5. **Write the artifact** at
+   \`${IDEATION_ARTIFACT_PATTERN}\` using the schema in the skill.
+6. **Present the handoff prompt** with four concrete options — not A/B/C
+   letters. Default = "Start /cc on the top recommendation".
 
 ## Primary skill
 
@@ -43,31 +66,152 @@ improvements before committing to a specific feature request.
 export function ideateCommandSkillMarkdown() {
     return `---
 name: ${IDEATE_SKILL_NAME}
-description: "Repository ideation mode: detect and rank high-leverage improvements before implementation."
+description: "Repository ideation mode: detect and rank high-leverage improvements, persist a backlog artifact, and hand off to /cc or save/discard."
 ---
 
 # /cc-ideate
 
 ## Announce at start
 
-"Using flow-ideate to identify highest-leverage improvements in this repository."
+"Using flow-ideate to identify highest-leverage improvements in this
+repository. Will persist a ranked backlog to
+\`${IDEATION_ARTIFACT_PATTERN}\` and end with an explicit handoff."
 
 ## HARD-GATE
 
-Do not start coding in ideate mode. End with an explicit user choice.
+- Do not start coding in ideate mode.
+- Do not mutate \`.cclaw/state/flow-state.json\` — ideation sits outside
+  the critical-path flow.
+- Always produce the artifact file on disk before presenting the handoff.
+- Always end with a structured handoff that names the concrete follow-up
+  command for each option. No A/B/C letters without command context.
 
 ## Protocol
 
-1. Collect evidence from the current repo state.
-2. Build candidate improvements with impact/effort/confidence.
-3. Rank and recommend one candidate.
-4. Ask for explicit selection.
-5. If user selects a candidate, hand off to \`/cc <selected idea>\`.
+### Phase 0 — Resume check
 
-## Candidate format
+1. Use the harness's file-glob tool (\`Glob\` pattern
+   \`${IDEATION_ARTIFACT_GLOB}\` or equivalent \`ls\`/\`find\`).
+2. Filter to files modified within the last ${IDEATION_RESUME_WINDOW_DAYS} days.
+3. If one or more match, present **one** structured ask using the
+   harness's native tool (${STRUCTURED_ASK_TOOLS}) with options:
+   - **Continue the existing backlog** — read the most-recent
+     ideation-*.md and work from its candidate list; skip re-scanning.
+   - **Start a fresh scan** — proceed to Phase 1; the old artifact stays
+     on disk for history.
+   - **Cancel** — stop; do not scan or write anything.
+4. If no recent artifact exists, proceed to Phase 1 silently.
 
-| ID | Improvement | Impact | Effort | Confidence | Evidence |
-|---|---|---|---|---|---|
-| I-1 |  | High/Medium/Low | S/M/L | High/Medium/Low | path or command evidence |
+### Phase 1 — Collect evidence
+
+Scan the current repo. Examples of signals (not exhaustive):
+
+- \`rg -n 'TODO|FIXME|XXX|HACK|TBD'\` grouped by file.
+- Test-runner output (\`npm test\`, \`pytest\`, \`go test ./...\`) — note
+  failures, timeouts, deprecation warnings.
+- Module size outliers (\`wc -l\` or \`du\`) with weak direct test coverage.
+- Docs drift: check that \`README.md\` / \`docs/\` reference files that
+  still exist and flags/APIs that still match \`src/\`.
+- \`${RUNTIME_ROOT}/knowledge.jsonl\` entries with \`type: "heuristic"\`
+  or repeated \`subject:\` values.
+
+Record each finding with the exact file path or command that produced it.
+
+### Phase 2 — Build candidates
+
+For each high-signal finding, construct a candidate:
+
+- **ID** — \`I-1\`, \`I-2\`, …
+- **Title** — one short imperative phrase
+- **Impact** — High / Medium / Low
+- **Effort** — S / M / L
+- **Confidence** — High / Medium / Low
+- **Evidence** — path(s) or command output, inline if short
+- **Proposed handoff** — the exact \`/cc <phrase>\` the user would run
+  to act on this candidate
+
+Aim for 5–10 candidates. Do not invent candidates without evidence.
+
+### Phase 3 — Rank and write the artifact
+
+1. Sort by impact/effort ratio; break ties with confidence.
+2. Compute the artifact filename:
+   - \`slug\` = first 3–5 words of the top recommendation, lowercase,
+     non-alphanumeric collapsed to \`-\`, trimmed. When ideation is
+     focus-hinted (user passed an argument), use the focus hint instead.
+   - \`date\` = today in \`YYYY-MM-DD\` (local time).
+   - Path = \`.cclaw/artifacts/ideation-<date>-<slug>.md\`.
+3. Use the harness's write-file tool (\`Write\`, \`apply_patch\`, or shell
+   \`cat <<EOF > path\`) to create the artifact with this schema:
+
+   \`\`\`markdown
+   # Ideation — <date>
+
+   **Focus:** <user-supplied focus or "open-ended scan">
+   **Generated:** <ISO-8601 timestamp>
+   **Recommendation:** I-1
+
+   ## Ranked backlog
+
+   | ID | Improvement | Impact | Effort | Confidence | Evidence |
+   |---|---|---|---|---|---|
+   | I-1 | Fix feature-worktree test timeouts | High | S | High | tests/unit/feature-system.test.ts:31 |
+   | …   | …                                  | …    | … | …    | …                                     |
+
+   ## Candidate detail
+
+   ### I-1 — Fix feature-worktree test timeouts
+   - **Evidence:** \`npm test\` hangs 40s on tests/unit/feature-system.test.ts:31.
+   - **Handoff:** \`/cc Fix feature-worktree test timeouts on macOS\`
+
+   ### I-2 — …
+   \`\`\`
+
+4. Confirm in chat: "Wrote <path>."
+
+### Phase 4 — Handoff prompt
+
+Present **one** structured ask using the harness's native tool
+(${STRUCTURED_ASK_TOOLS}). Each option must name the concrete follow-up —
+no bare A/B/C.
+
+Required options, in this order:
+
+1. **Start /cc on the top recommendation** — the agent immediately loads
+   \`${RUNTIME_ROOT}/skills/using-cclaw/SKILL.md\` and invokes
+   \`/cc <I-1 handoff phrase>\` in the same turn. Default choice.
+2. **Pick a different candidate** — the agent asks which ID (I-2, I-3, …)
+   and then invokes \`/cc <that candidate's handoff phrase>\`.
+3. **Save and close** — leave the artifact on disk, do nothing else.
+   Next session: \`/cc-ideate\` will offer to resume it.
+4. **Discard** — delete the just-written artifact. Use only when the
+   scan produced nothing actionable.
+
+When the structured-ask tool is unavailable, fall back to a plain-text
+lettered list with the same four labels. Do not invent extra options.
+
+### Phase 5 — Execute the choice
+
+- **Start /cc on I-1** or **different candidate:** announce
+  "Handing off to /cc <phrase>" and load the \`using-cclaw\` router
+  skill. From there, the normal \`/cc\` classification and stage flow
+  takes over. Do not produce a second artifact; the ideation file is
+  preserved as the origin document for this run.
+- **Save and close:** reply with the artifact path and stop.
+- **Discard:** delete the artifact file, confirm deletion, stop.
+
+## Do not
+
+- Do not write into \`.cclaw/artifacts/0X-*.md\` (stage artifacts).
+- Do not mutate \`.cclaw/state/flow-state.json\` at any phase.
+- Do not end the turn with an ungrounded "pick one" question — every
+  option in the handoff prompt must reference a concrete command.
 `;
 }
+/**
+ * Exposed for tests and docs that need to mention the artifact convention
+ * without hard-coding the path string in two places.
+ */
+export const IDEATION_ARTIFACT_PATH_PATTERN = IDEATION_ARTIFACT_PATTERN;
+export const IDEATION_ARTIFACT_GLOB_PATTERN = IDEATION_ARTIFACT_GLOB;
+export const IDEATION_RESUME_WINDOW = IDEATION_RESUME_WINDOW_DAYS;

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.41.0",
+  "version": "0.43.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {