cclaw-cli 0.15.1 → 0.18.0

package/dist/artifact-linter.js

@@ -188,6 +188,66 @@ function lineContainsVagueAdjective(text) {
     }
     return null;
 }
+const FRONTMATTER_REQUIRED_KEYS = [
+    "stage",
+    "schema_version",
+    "version",
+    "feature",
+    "locked_decisions",
+    "inputs_hash"
+];
+const PLACEHOLDER_PATTERNS = [
+    { label: "TODO", regex: /\bTODO\b/iu },
+    { label: "TBD", regex: /\bTBD\b/iu },
+    { label: "FIXME", regex: /\bFIXME\b/iu },
+    { label: "<fill-in>", regex: /<fill-in>/iu },
+    { label: "<your-*-here>", regex: /<your-[^>]*-here>/iu },
+    { label: "xxx", regex: /\bxxx\b/iu },
+    { label: "ellipsis", regex: /\.{3}/u }
+];
+const SCOPE_REDUCTION_PATTERNS = [
+    { label: "v1", regex: /\bv1\b/iu },
+    { label: "for now", regex: /\bfor now\b/iu },
+    { label: "later", regex: /\blater\b/iu },
+    { label: "temporary", regex: /\btemporary\b/iu },
+    { label: "placeholder", regex: /\bplaceholder\b/iu },
+    { label: "mock for now", regex: /\bmock for now\b/iu },
+    { label: "hardcoded for now", regex: /\bhardcoded for now\b/iu },
+    { label: "will improve later", regex: /\bwill improve later\b/iu }
+];
+function parseFrontmatter(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---") {
+        return { hasFrontmatter: false, values: {} };
+    }
+    const endIndex = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+    if (endIndex < 0) {
+        return { hasFrontmatter: false, values: {} };
+    }
+    const values = {};
+    for (const line of lines.slice(1, endIndex)) {
+        const match = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/u.exec(line.trim());
+        if (!match)
+            continue;
+        const key = match[1];
+        const value = match[2].trim();
+        values[key] = value;
+    }
+    return { hasFrontmatter: true, values };
+}
+function extractDecisionIds(text) {
+    const ids = text.match(/\bD-\d+\b/gu) ?? [];
+    return [...new Set(ids)];
+}
+function collectPatternHits(text, patterns) {
+    const hits = [];
+    for (const pattern of patterns) {
+        if (pattern.regex.test(text)) {
+            hits.push(pattern.label);
+        }
+    }
+    return hits;
+}
 function validateSectionBody(sectionBody, rule, sectionName) {
     const bodyLines = sectionBody.split(/\r?\n/).map((line) => line.trim());
     const meaningful = meaningfulLineCount(sectionBody);
@@ -336,6 +396,37 @@ export async function lintArtifact(projectRoot, stage) {
     }
     const raw = await fs.readFile(absFile, "utf8");
     const sections = extractH2Sections(raw);
+    const parsedFrontmatter = parseFrontmatter(raw);
+    const frontmatterMissingKeys = FRONTMATTER_REQUIRED_KEYS.filter((key) => {
+        const value = parsedFrontmatter.values[key];
+        return typeof value !== "string" || value.trim().length === 0;
+    });
+    const frontmatterStage = parsedFrontmatter.values.stage?.replace(/^['"]|['"]$/gu, "");
+    const frontmatterSchemaVersion = parsedFrontmatter.values.schema_version?.replace(/^['"]|['"]$/gu, "");
+    const frontmatterInputsHash = parsedFrontmatter.values.inputs_hash?.replace(/^['"]|['"]$/gu, "");
+    const frontmatterValid = parsedFrontmatter.hasFrontmatter &&
+        frontmatterMissingKeys.length === 0 &&
+        frontmatterStage === stage &&
+        frontmatterSchemaVersion === "1" &&
+        /^sha256:(?:pending|[a-f0-9]{64})$/iu.test(frontmatterInputsHash ?? "");
+    const requireFrontmatter = parsedFrontmatter.hasFrontmatter;
+    findings.push({
+        section: "Frontmatter",
+        required: requireFrontmatter,
+        rule: "Artifact must include frontmatter keys (stage, schema_version=1, version, feature, locked_decisions, inputs_hash=sha256:pending|sha256:<64hex>).",
+        found: parsedFrontmatter.hasFrontmatter ? frontmatterValid : true,
+        details: !parsedFrontmatter.hasFrontmatter
+            ? "Legacy artifact without YAML frontmatter (allowed for backward compatibility)."
+            : frontmatterMissingKeys.length > 0
+                ? `Frontmatter missing required key(s): ${frontmatterMissingKeys.join(", ")}.`
+                : frontmatterStage !== stage
+                    ? `Frontmatter stage must be "${stage}" (found "${frontmatterStage ?? "(missing)"}").`
+                    : frontmatterSchemaVersion !== "1"
+                        ? `Frontmatter schema_version must be "1" (found "${frontmatterSchemaVersion ?? "(missing)"}").`
+                        : !/^sha256:(?:pending|[a-f0-9]{64})$/iu.test(frontmatterInputsHash ?? "")
+                            ? "Frontmatter inputs_hash must be sha256:pending or sha256:<64 hex chars>."
+                            : "Frontmatter integrity checks passed."
+    });
     const isTrivialOverride = schema.trivialOverrideSections &&
         schema.trivialOverrideSections.length > 0 &&
         /trivial.change|mini.design|escape.hatch/iu.test(raw);
@@ -362,6 +453,69 @@ export async function lintArtifact(projectRoot, stage) {
                 : validation.details
         });
     }
+    if (stage === "plan") {
+        const strictPlanGuards = parsedFrontmatter.hasFrontmatter ||
+            headingPresent(sections, "No-Placeholder Scan") ||
+            headingPresent(sections, "No Scope Reduction Language Scan") ||
+            headingPresent(sections, "Locked Decision Coverage");
+        const taskListBody = sectionBodyByName(sections, "Task List") ?? raw;
+        const placeholderHits = collectPatternHits(taskListBody, PLACEHOLDER_PATTERNS);
+        findings.push({
+            section: "No Placeholder Enforcement",
+            required: strictPlanGuards,
+            rule: "Task List must not contain placeholders (TODO/TBD/FIXME/<fill-in>/<your-*-here>/xxx/ellipsis).",
+            found: placeholderHits.length === 0,
+            details: placeholderHits.length === 0
+                ? "No placeholder tokens detected in Task List."
+                : `Detected placeholder token(s) in Task List: ${placeholderHits.join(", ")}.`
+        });
+        const scopePath = path.join(projectRoot, RUNTIME_ROOT, "artifacts", "02-scope.md");
+        const scopeRaw = (await exists(scopePath)) ? await fs.readFile(scopePath, "utf8") : "";
+        const scopeDecisionIds = extractDecisionIds(scopeRaw);
+        const missingDecisionRefs = scopeDecisionIds.filter((id) => !raw.includes(id));
+        findings.push({
+            section: "Locked Decision Traceability",
+            required: strictPlanGuards && scopeDecisionIds.length > 0,
+            rule: "Every locked decision ID (D-XX) in scope must be referenced in plan.",
+            found: missingDecisionRefs.length === 0,
+            details: scopeDecisionIds.length === 0
+                ? "No D-XX IDs found in scope artifact; traceability check skipped."
+                : missingDecisionRefs.length === 0
+                    ? `All ${scopeDecisionIds.length} scope decision IDs are referenced in plan.`
+                    : `Missing scope decision reference(s) in plan: ${missingDecisionRefs.join(", ")}.`
+        });
+        const reductionHits = collectPatternHits(taskListBody, SCOPE_REDUCTION_PATTERNS);
+        findings.push({
+            section: "No Scope Reduction Language",
+            required: strictPlanGuards && scopeDecisionIds.length > 0,
+            rule: "Task List must not include scope-reduction language when locked decisions exist.",
+            found: reductionHits.length === 0,
+            details: scopeDecisionIds.length === 0
+                ? "No locked decisions found in scope artifact; scope-reduction scan is advisory."
+                : reductionHits.length === 0
+                    ? "No scope-reduction phrases detected in Task List."
+                    : `Detected scope-reduction phrase(s) in Task List: ${reductionHits.join(", ")}.`
+        });
+    }
+    if (stage === "scope") {
+        const strictScopeGuards = parsedFrontmatter.hasFrontmatter ||
+            headingPresent(sections, "Locked Decisions (D-XX)");
+        const scopeSections = [
+            sectionBodyByName(sections, "In Scope / Out of Scope") ?? "",
+            sectionBodyByName(sections, "Scope Summary") ?? "",
+            sectionBodyByName(sections, "Locked Decisions (D-XX)") ?? ""
+        ].join("\n");
+        const reductionHits = collectPatternHits(scopeSections, SCOPE_REDUCTION_PATTERNS);
+        findings.push({
+            section: "No Scope Reduction Language",
+            required: strictScopeGuards,
+            rule: "Scope boundary sections must not use reduction placeholders (`v1`, `for now`, `later`, `temporary`, `placeholder`).",
+            found: reductionHits.length === 0,
+            details: reductionHits.length === 0
+                ? "No scope-reduction phrases detected in scope boundary sections."
+                : `Detected scope-reduction phrase(s): ${reductionHits.join(", ")}.`
+        });
+    }
     const passed = findings.every((f) => !f.required || f.found);
     return { stage, file: relFile, passed, findings };
 }

package/dist/cli.js

@@ -122,7 +122,8 @@ function buildInitSurfacePreview(harnesses) {
         ".cclaw/rules/**",
         ".cclaw/adapters/*.md",
         ".cclaw/custom-skills/README.md",
-        ".cclaw/features/**",
+        ".cclaw/worktrees/**",
+        ".cclaw/features/** (legacy snapshots, read-only migration)",
         ".cclaw/runs/**",
         ".cclaw/artifacts/**",
         ".cclaw/knowledge.jsonl",

package/dist/constants.d.ts

@@ -4,9 +4,9 @@ export declare const RUNTIME_ROOT = ".cclaw";
 export declare const CCLAW_VERSION = "0.1.1";
 export declare const FLOW_VERSION = "1.0.0";
 export declare const DEFAULT_HARNESSES: HarnessId[];
-export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/contexts", ".cclaw/templates", ".cclaw/artifacts", ".cclaw/features", ".cclaw/state", ".cclaw/runs", ".cclaw/rules", ".cclaw/adapters", ".cclaw/agents", ".cclaw/hooks", ".cclaw/custom-skills"];
+export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/contexts", ".cclaw/templates", ".cclaw/artifacts", ".cclaw/worktrees", ".cclaw/state", ".cclaw/runs", ".cclaw/rules", ".cclaw/adapters", ".cclaw/agents", ".cclaw/hooks", ".cclaw/custom-skills"];
 export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", ".claude/commands/cc-*.md", ".claude/commands/cc.md", ".cursor/commands/cc-*.md", ".cursor/commands/cc.md", ".opencode/commands/cc-*.md", ".opencode/commands/cc.md", ".codex/commands/cc-*.md", ".codex/commands/cc.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".codex/hooks.json", ".opencode/plugins/cclaw-plugin.mjs", ".cursor/rules/cclaw-workflow.mdc"];
 export declare const COMMAND_FILE_ORDER: FlowStage[];
-export declare const UTILITY_COMMANDS: readonly ["learn", "next", "view", "status", "tree", "diff", "ops", "feature", "tdd-log", "retro", "archive", "rewind", "rewind-ack"];
+export declare const UTILITY_COMMANDS: readonly ["learn", "next", "view", "status", "tree", "diff", "ops", "feature", "tdd-log", "retro", "archive", "rewind"];
 export declare const SUBAGENT_SKILL_FOLDERS: readonly ["subagent-dev", "parallel-dispatch"];
 export type UtilityCommand = (typeof UTILITY_COMMANDS)[number];

package/dist/constants.js

@@ -15,7 +15,7 @@ export const REQUIRED_DIRS = [
     `${RUNTIME_ROOT}/contexts`,
     `${RUNTIME_ROOT}/templates`,
     `${RUNTIME_ROOT}/artifacts`,
-    `${RUNTIME_ROOT}/features`,
+    `${RUNTIME_ROOT}/worktrees`,
     `${RUNTIME_ROOT}/state`,
     `${RUNTIME_ROOT}/runs`,
     `${RUNTIME_ROOT}/rules`,
@@ -63,8 +63,7 @@ export const UTILITY_COMMANDS = [
     "tdd-log",
     "retro",
     "archive",
-    "rewind",
-    "rewind-ack"
+    "rewind"
 ];
 export const SUBAGENT_SKILL_FOLDERS = [
     "subagent-dev",

package/dist/content/contracts.js

@@ -34,7 +34,7 @@ ${schema.hardGate}
 2. Resolve active artifact root: \`.cclaw/artifacts/\`.
 3. Load required upstream artifacts for this stage:
 ${hydrationLines}
-4. Stream \`.cclaw/knowledge.jsonl\` and apply relevant JSON-line entries (strict schema: type, trigger, action, confidence, domain, stage, created, project).
+4. Stream \`.cclaw/knowledge.jsonl\` and apply relevant JSON-line entries (strict schema: type, trigger, action, confidence, domain, stage, origin_stage, origin_feature, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project).
 5. Write stage output to ${writeStepPaths}.
 6. Do NOT copy artifacts into \`.cclaw/runs/\`; archival is handled by \`/cc-ops archive\` (agent-facing wrapper over archive runtime).
 

package/dist/content/doctor-references.js

@@ -11,7 +11,7 @@ Reference docs for \`cclaw doctor\` checks.
 - \`hooks-and-lifecycle.md\` - hook wiring and harness lifecycle integration
 - \`harness-and-routing.md\` - harness shims, AGENTS/CLAUDE routing blocks, cursor rule
 - \`state-and-gates.md\` - flow-state integrity and gate evidence contracts
-- \`delegation-and-preamble.md\` - mandatory delegations and preamble budget controls
+- \`delegation-and-preamble.md\` - mandatory delegations and lightweight announce discipline
 - \`traceability.md\` - spec/plan/tdd trace matrix expectations
 - \`tooling-capabilities.md\` - local runtime prerequisites (bash/node/python/jq)
 - \`config-and-policy.md\` - config schema, rules policy, and validation references
@@ -84,18 +84,19 @@ Reference docs for \`cclaw doctor\` checks.
 - mandatory delegations for the current stage must be completed or waived
 - waivers should include an explicit reason
 - stale entries from previous runs are ignored by current-run checks
+- delegation entries use span-compatible fields (\`spanId\`, \`startTs\`, \`endTs\`, \`retryCount\`, \`evidenceRefs\`)
 
-## Preamble budget contract
+## Announce discipline contract
 
-- preamble events are logged to \`.cclaw/state/preamble-log.jsonl\`
-- repeated entries inside cooldown windows indicate noisy preamble behavior
-- in TDD wave mode, emit once per wave unless plan materially changes
+- no dedicated preamble runtime log is required
+- substantial turns should still start with a concise announce (stage + goal + next action)
+- do not spam repeated announces when intent did not change
 
 ## Typical fixes
 
 1. Append missing delegation records with \`completed\` or \`waived\` status.
 2. Record harness-limitation waivers when native delegation is unavailable.
-3. Reduce repeated preamble emissions and keep logs structured (\`ts/stage/trigger/hash\`).
+3. Keep announces concise and only refresh when plan/risk materially changes.
 `,
     "traceability.md": `# Traceability
 

package/dist/content/feature-command.js

@@ -1,66 +1,71 @@
 import { RUNTIME_ROOT } from "../constants.js";
-const FEATURE_SKILL_FOLDER = "feature-workspaces";
-const FEATURE_SKILL_NAME = "feature-workspaces";
+const FEATURE_SKILL_FOLDER = "using-git-worktrees";
+const FEATURE_SKILL_NAME = "using-git-worktrees";
 function activeFeaturePath() {
     return `${RUNTIME_ROOT}/state/active-feature.json`;
 }
-function featuresRoot() {
-    return `${RUNTIME_ROOT}/features`;
+function worktreeRegistryPath() {
+    return `${RUNTIME_ROOT}/state/worktrees.json`;
 }
-function runtimeArtifactsPath() {
-    return `${RUNTIME_ROOT}/artifacts`;
+function managedWorktreesRoot() {
+    return `${RUNTIME_ROOT}/worktrees`;
 }
-function runtimeStatePath() {
-    return `${RUNTIME_ROOT}/state`;
+function legacyFeaturesRoot() {
+    return `${RUNTIME_ROOT}/features`;
 }
 export function featureCommandContract() {
     return `# /cc-ops feature
 
 ## Purpose
 
-Manage multi-feature workspaces without flow-state/artifact collisions.
-
-The active runtime remains:
-- \`${runtimeArtifactsPath()}\` (active artifacts)
-- \`${runtimeStatePath()}\` (active state)
+Manage parallel feature execution using git worktrees (git-native isolation).
 
-Feature snapshots live under \`${featuresRoot()}/<feature-id>/\`.
+Runtime state/artifacts are **never** copied between features anymore. Isolation is branch/worktree-level.
 
 ## HARD-GATE
 
-- Never overwrite another feature snapshot silently.
-- Before switching feature, snapshot the current active runtime first.
-- Keep \`${activeFeaturePath()}\` as the single source of "current feature".
+- Do not mutate feature context by copying \`${RUNTIME_ROOT}/artifacts\` or \`${RUNTIME_ROOT}/state\` between feature IDs.
+- Use \`git worktree add\` for new feature execution paths.
+- Keep \`${activeFeaturePath()}\` + \`${worktreeRegistryPath()}\` as the feature routing source of truth.
+- Treat \`${legacyFeaturesRoot()}/\` as read-only migration data.
 
 ## Subcommands
 
 ### \`/cc-ops feature status\`
-Show active feature id and snapshot location.
+Show:
+- active feature id from \`${activeFeaturePath()}\`
+- resolved worktree entry from \`${worktreeRegistryPath()}\`
+- active workspace path
 
 ### \`/cc-ops feature list\`
-List all feature ids in \`${featuresRoot()}/\` (directory names).
+List registered feature worktrees from \`${worktreeRegistryPath()}\` and mark active entry.
 
 ### \`/cc-ops feature new <feature-id>\`
-Create \`${featuresRoot()}/<feature-id>/artifacts\` and \`${featuresRoot()}/<feature-id>/state\`.
+1. Validate \`feature-id\` (lowercase slug, letters/numbers/dashes).
+2. Create worktree under \`${managedWorktreesRoot()}/<feature-id>\`.
+3. Create/switch branch using \`git worktree add\` (prefer \`feature/<feature-id>\` naming).
+4. Register entry in \`${worktreeRegistryPath()}\`.
 
-Optional flag:
-- \`--clone-active\`: clone current active runtime into the new feature snapshot.
+Optional flags:
+- \`--clone-active\`: seed from active branch HEAD (default behavior).
+- \`--switch\`: mark new feature as active after registration.
 
 ### \`/cc-ops feature switch <feature-id>\`
-1. Snapshot current active runtime into \`${featuresRoot()}/<active>/\`.
-2. Restore target snapshot from \`${featuresRoot()}/<feature-id>/\` into active runtime:
-   - \`${runtimeArtifactsPath()}\`
-   - \`${runtimeStatePath()}\` (preserve \`active-feature.json\`)
-3. Update \`${activeFeaturePath()}\` with \`activeFeature=<feature-id>\`.
+1. Validate that \`<feature-id>\` exists in \`${worktreeRegistryPath()}\`.
+2. Update \`${activeFeaturePath()}\`.
+3. Print target worktree path and instruct the operator/agent to continue from that workspace root.
+
+## Migration note
 
-If the target snapshot is empty, initialize runtime as a fresh flow.
+Legacy snapshot folders under \`${legacyFeaturesRoot()}/\` are supported as read-only references during migration and should not be used for new execution.
 
 ## Output
 
 Always print:
 - active feature before
 - active feature after
-- whether snapshot/restore changed files
+- target workspace path
+- workspace source (\`git-worktree\` | \`workspace\` | \`legacy-snapshot\`)
 
 ## Primary skill
 
@@ -70,51 +75,49 @@ Always print:
 export function featureCommandSkillMarkdown() {
     return `---
 name: ${FEATURE_SKILL_NAME}
-description: "Manage cclaw multi-feature workspaces (status/list/new/switch) while preserving active flow runtime."
+description: "Manage cclaw feature isolation using git worktrees (status/list/new/switch)."
 ---
 
-# /cc-ops feature — Feature Workspace Manager
+# /cc-ops feature — Git Worktree Manager
 
 ## HARD-GATE
 
-Do not switch feature by editing only \`active-feature.json\`. A valid switch must snapshot current runtime and restore target runtime.
+Do not implement feature switching by copying runtime files between feature IDs. Use git worktrees and registry updates only.
 
 ## Paths
 
 - Active pointer: \`${activeFeaturePath()}\`
-- Feature snapshots: \`${featuresRoot()}/<feature-id>/\`
-- Active runtime artifacts: \`${runtimeArtifactsPath()}\`
-- Active runtime state: \`${runtimeStatePath()}\`
+- Worktree registry: \`${worktreeRegistryPath()}\`
+- Managed worktree root: \`${managedWorktreesRoot()}\`
+- Legacy snapshots (read-only): \`${legacyFeaturesRoot()}\`
 
 ## Protocol
 
 ### status
 1. Read \`${activeFeaturePath()}\`.
-2. Print active feature id and its snapshot folder.
+2. Resolve active entry in \`${worktreeRegistryPath()}\`.
+3. Print active id + workspace path + source.
 
 ### list
-1. Enumerate directories in \`${featuresRoot()}/\`.
+1. Enumerate entries in \`${worktreeRegistryPath()}\`.
 2. Mark the active one.
+3. Highlight any \`legacy-snapshot\` entries as migration-only.
 
-### new <feature-id> [--clone-active]
-1. Validate \`feature-id\` (lowercase slug, letters/numbers/dashes).
-2. Create snapshot dirs:
-   - \`${featuresRoot()}/<feature-id>/artifacts\`
-   - \`${featuresRoot()}/<feature-id>/state\`
-3. If \`--clone-active\`: copy active runtime artifacts/state into the new snapshot.
-4. Do not change active feature unless the user explicitly requests switch.
+### new <feature-id> [--clone-active] [--switch]
+1. Validate \`feature-id\` and ensure not already registered.
+2. Run \`git worktree add\` to create \`${managedWorktreesRoot()}/<feature-id>\`.
+3. Register entry in \`${worktreeRegistryPath()}\` with branch + path + source.
+4. If \`--switch\`, update \`${activeFeaturePath()}\`.
 
 ### switch <feature-id>
-1. Read current active feature id.
-2. Snapshot current runtime into current feature snapshot.
-3. Restore target snapshot into active runtime.
-4. Update \`${activeFeaturePath()}\`.
-5. Report stage/run after restore (\`flow-state.json\`).
+1. Validate target exists in \`${worktreeRegistryPath()}\`.
+2. Update \`${activeFeaturePath()}\`.
+3. Report target path and require continuation from that workspace root.
 
 ## Safety checks
 
 - If target feature does not exist: block and suggest \`/cc-ops feature new <id>\`.
-- If snapshot copy fails: abort switch, keep current active feature unchanged.
-- Preserve global pointer file \`active-feature.json\` when restoring state.
+- If \`git worktree add\` fails: do not write partial registry updates.
+- If active feature maps to \`legacy-snapshot\`, report read-only migration warning.
 `;
 }

package/dist/content/harnesses-doc.js

@@ -75,12 +75,12 @@ Read-only subcommands:
 - \`/cc-view diff\` - before/after flow-state diff map
 
 Operations subcommands:
-- \`/cc-ops feature ...\` - multi-feature workspace management
+- \`/cc-ops feature ...\` - git-worktree feature isolation and routing
 - \`/cc-ops tdd-log ...\` - explicit RED/GREEN/REFACTOR evidence log
 - \`/cc-ops retro\` - mandatory retrospective gate before archive
 - \`/cc-ops archive\` - archive active run from harness flow
 - \`/cc-ops rewind ...\` - rewind flow and invalidate downstream stages
-- \`/cc-ops rewind-ack ...\` - clear stale stage markers after redo
+- \`/cc-ops rewind --ack ...\` - clear stale stage markers after redo
 
 Stage order remains canonical:
 \`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship\`

package/dist/content/hooks.js

@@ -457,7 +457,7 @@ if [ -n "$ROUTING_MISSING" ]; then
 fi
 
 # --- Build context message ---
-CTX="cclaw loaded. Flow: stage=$STAGE ($COMPLETED/8 completed, run=$ACTIVE_RUN, feature=$ACTIVE_FEATURE). Active artifacts: ${RUNTIME_ROOT}/artifacts/. Feature snapshots: ${RUNTIME_ROOT}/features/$ACTIVE_FEATURE/. Learnings: $LEARNINGS_COUNT entries."
+CTX="cclaw loaded. Flow: stage=$STAGE ($COMPLETED/8 completed, run=$ACTIVE_RUN, feature=$ACTIVE_FEATURE). Active artifacts: ${RUNTIME_ROOT}/artifacts/. Feature registry: ${RUNTIME_ROOT}/state/worktrees.json (managed roots: ${RUNTIME_ROOT}/worktrees/). Learnings: $LEARNINGS_COUNT entries."
 if [ -n "$VERSION_NOTE" ]; then
   CTX="$CTX
 $VERSION_NOTE"
@@ -496,7 +496,7 @@ To disable suggestions persistently set ${RUNTIME_ROOT}/state/suggestion-memory.
 fi
 if [ -n "$STALE_STAGES" ]; then
   CTX="$CTX
-Stale stages pending acknowledgement: $STALE_STAGES (use /cc-ops rewind-ack <stage> after redo)."
+Stale stages pending acknowledgement: $STALE_STAGES (use /cc-ops rewind --ack <stage> after redo)."
 fi
 if [ -n "$KNOWLEDGE_DIGEST" ]; then
   CTX="$CTX

package/dist/content/learnings.d.ts

@@ -2,6 +2,6 @@
  * Canonical JSONL field order (matches the reference spec).
  * Exported for tests and any programmatic writer that wants the exact shape.
  */
-export declare const KNOWLEDGE_JSONL_FIELDS: readonly ["type", "trigger", "action", "confidence", "domain", "stage", "created", "project"];
+export declare const KNOWLEDGE_JSONL_FIELDS: readonly ["type", "trigger", "action", "confidence", "domain", "stage", "origin_stage", "origin_feature", "frequency", "universality", "maturity", "created", "first_seen_ts", "last_seen_ts", "project"];
 export declare function learnSkillMarkdown(): string;
 export declare function learnCommandContract(): string;

package/dist/content/learnings.js

@@ -20,7 +20,14 @@ export const KNOWLEDGE_JSONL_FIELDS = [
     "confidence",
     "domain",
     "stage",
+    "origin_stage",
+    "origin_feature",
+    "frequency",
+    "universality",
+    "maturity",
     "created",
+    "first_seen_ts",
+    "last_seen_ts",
     "project"
 ];
 export function learnSkillMarkdown() {
@@ -51,10 +58,10 @@ Do not invent alternate stores (no markdown mirror, no SQLite, no per-stage file
 ## Entry format — strict JSONL schema
 
 Exactly one JSON object per line. Fields must appear in the order:
-\`type, trigger, action, confidence, domain, stage, created, project\`.
+\`type, trigger, action, confidence, domain, stage, origin_stage, origin_feature, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project\`.
 
 \`\`\`json
-{"type":"pattern","trigger":"when reviewing external payloads","action":"parse through zod before touching service layer","confidence":"high","domain":"api","stage":"review","created":"2026-04-14T12:00:00Z","project":"cclaw"}
+{"type":"pattern","trigger":"when reviewing external payloads","action":"parse through zod before touching service layer","confidence":"high","domain":"api","stage":"review","origin_stage":"review","origin_feature":"payload-hardening","frequency":1,"universality":"project","maturity":"raw","created":"2026-04-14T12:00:00Z","first_seen_ts":"2026-04-14T12:00:00Z","last_seen_ts":"2026-04-14T12:00:00Z","project":"cclaw"}
 \`\`\`
 
 | field | type | required | notes |
@@ -65,7 +72,14 @@ Exactly one JSON object per line. Fields must appear in the order:
 | \`confidence\` | \`"high" \\| "medium" \\| "low"\` | yes | Write \`medium\` when unsure; do not omit. |
 | \`domain\` | string \\| null | yes | Free-form taxonomy (\`api\`, \`infra\`, \`ui\`, \`security\`, \`testing\`, …). Use \`null\` when cross-cutting. |
 | \`stage\` | \`FlowStage\` \\| null | yes | One of brainstorm / scope / design / spec / plan / tdd / review / ship, or \`null\` when cross-stage. |
+| \`origin_stage\` | \`FlowStage\` \\| null | yes | Stage where this learning was first observed. |
+| \`origin_feature\` | string \\| null | yes | Feature/worktree label where it was observed first. |
+| \`frequency\` | integer >= 1 | yes | Number of times this same trigger/action pair has been observed. |
+| \`universality\` | \`"project" \\| "personal" \\| "universal"\` | yes | Scope of applicability. |
+| \`maturity\` | \`"raw" \\| "lifted-to-rule" \\| "lifted-to-enforcement"\` | yes | Lifecycle state of the learning. |
 | \`created\` | ISO 8601 UTC string | yes | \`date -u +%Y-%m-%dT%H:%M:%SZ\`. |
+| \`first_seen_ts\` | ISO 8601 UTC string | yes | First observed timestamp (usually equals \`created\`). |
+| \`last_seen_ts\` | ISO 8601 UTC string | yes | Last re-confirmed timestamp. |
 | \`project\` | string \\| null | yes | Repo or scope name. Use \`null\` when the entry crosses projects. |
 
 Rules:
@@ -96,10 +110,13 @@ Rules:
 - Return the matched lines pretty-printed (do not mutate the file).
 
 ### \`/cc-learn add\`
-- Ask for required fields in order: \`type\`, \`trigger\`, \`action\`, \`confidence\`, \`domain\`, \`stage\`, \`project\`.
+- Ask for required user-facing fields in order: \`type\`, \`trigger\`, \`action\`, \`confidence\`, \`domain\`, \`stage\`, \`universality\`, \`project\`.
 - \`confidence\` must be one of \`high\`, \`medium\`, \`low\`. Default to \`medium\` if the user declines to set it.
 - \`domain\`, \`stage\`, and \`project\` may be explicitly \`null\`.
-- \`created\` is set automatically to the current UTC ISO timestamp.
+- \`origin_stage\` defaults to \`stage\`; \`origin_feature\` defaults to active feature (or \`null\` if unknown).
+- \`frequency\` starts at \`1\`.
+- \`maturity\` starts at \`raw\`.
+- \`created\`, \`first_seen_ts\`, and \`last_seen_ts\` are set automatically to current UTC ISO timestamp.
 - Append exactly one JSON line to \`${KNOWLEDGE_PATH}\` with the field order from the schema table above.
 - Re-read the file tail to confirm the new line is valid JSON and parses back to the same object.
 
@@ -130,7 +147,7 @@ Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\`
 |---|---|---|
 | (default) | — | Show recent knowledge entries (tail of JSONL, pretty-printed). |
 | \`search\` | \`<query>\` | Stream-filter the JSONL for matching \`trigger\`, \`action\`, \`domain\`, \`project\`. |
-| \`add\` | — | Append one JSON line (\`rule\` / \`pattern\` / \`lesson\` / \`compound\`) with the strict 8-field schema. |
+| \`add\` | — | Append one JSON line (\`rule\` / \`pattern\` / \`lesson\` / \`compound\`) with the strict 15-field schema. |
 | \`curate\` | — | Hand off to the **knowledge-curation** skill: read-only audit + soft-archive plan when the file exceeds the curation threshold. |
 `;
 }

package/dist/content/meta-skill.js

@@ -28,7 +28,7 @@ Task arrives
   ├─ Resume existing flow? -> /cc or /cc-next
   ├─ Knowledge operation? -> /cc-learn
   ├─ Read-only workspace view? -> /cc-view [status|tree|diff]
-  └─ Workspace operation? -> /cc-ops [feature|tdd-log|retro|archive|rewind|rewind-ack]
+  └─ Workspace operation? -> /cc-ops [feature|tdd-log|retro|archive|rewind]
 \`\`\`
 
 ## Task classification
@@ -72,7 +72,7 @@ Do not inline these protocols in stage skills; cite by path:
 
 - Decision protocol: \`${DECISION_PROTOCOL_REL_PATH}\`
 - Completion/resume protocol: \`${COMPLETION_PROTOCOL_REL_PATH}\`
-- Engineering ethos + preamble rules: \`${ETHOS_PROTOCOL_REL_PATH}\`
+- Engineering ethos + announce discipline: \`${ETHOS_PROTOCOL_REL_PATH}\`
 
 ## Knowledge guidance
 

package/dist/content/next-command.js

@@ -39,7 +39,7 @@ This is the only progression command the user needs to drive the entire flow. St
 
 1. Read **\`${flowPath}\`**. If missing → **BLOCKED** (state missing).
 2. Parse JSON. Capture \`currentStage\` and \`stageGateCatalog[currentStage]\`.
-3. If \`staleStages[currentStage]\` exists, do not advance automatically. Re-run the stage artifact work, then clear the marker with \`/cc-ops rewind-ack <currentStage>\`.
+3. If \`staleStages[currentStage]\` exists, do not advance automatically. Re-run the stage artifact work, then clear the marker with \`/cc-ops rewind --ack <currentStage>\`.
 4. Let \`G\` = \`requiredGates\` for **\`currentStage\`** from the stage schema.
 5. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state.
 6. **Satisfied** for gate id \`g\`: \`g\` in \`catalog.passed\` and \`g\` not in \`catalog.blocked\`.
@@ -124,7 +124,7 @@ Do **not** mark gates satisfied from memory alone. Cite **artifact evidence** (p
 
 1. Open **\`${flowPath}\`**.
 2. Record \`currentStage\` and \`stageGateCatalog[currentStage]\`.
-3. If \`staleStages[currentStage]\` exists, re-run the stage and clear marker via \`/cc-ops rewind-ack <currentStage>\` before advancing.
+3. If \`staleStages[currentStage]\` exists, re-run the stage and clear marker via \`/cc-ops rewind --ack <currentStage>\` before advancing.
 4. If the file is missing or invalid JSON → **BLOCKED** (report and stop).
 
 ### Step 2: Evaluate gates

package/dist/content/observe.js

@@ -819,7 +819,8 @@ if command -v jq >/dev/null 2>&1; then
     --arg phase "$PHASE" \\
     --arg stage "$STAGE" \\
     --arg runId "$ACTIVE_RUN" \\
-    '{ts:$ts,event:$event,tool:$tool,phase:$phase,stage:$stage,runId:$runId}' 2>/dev/null || echo "")
+    --arg schemaVersion "1" \\
+    '{ts:$ts,event:$event,tool:$tool,phase:$phase,stage:$stage,runId:$runId,schemaVersion:($schemaVersion|tonumber)}' 2>/dev/null || echo "")
 else
   EVENT_JSON=$(printf '{"ts":"%s","event":"%s","tool":"%s","phase":"%s","stage":"%s","runId":"%s","data":"%s"}' \\
     "$(escape_json "$TS")" \\
@@ -829,7 +830,7 @@ else
     "$(escape_json "$STAGE")" \\
     "$(escape_json "$ACTIVE_RUN")" \\
     "$(escape_json "$PAYLOAD")")
-  ACTIVITY_JSON=$(printf '{"ts":"%s","event":"%s","tool":"%s","phase":"%s","stage":"%s","runId":"%s"}' \\
+  ACTIVITY_JSON=$(printf '{"ts":"%s","event":"%s","tool":"%s","phase":"%s","stage":"%s","runId":"%s","schemaVersion":1}' \\
     "$(escape_json "$TS")" \\
     "$(escape_json "$EVENT")" \\
     "$(escape_json "$TOOL")" \\

package/dist/content/ops-command.js

@@ -14,7 +14,6 @@ Subcommands:
 - \`retro\` -> \`/cc-ops retro\`
 - \`archive\` -> \`/cc-ops archive\`
 - \`rewind\` -> \`/cc-ops rewind\`
-- \`rewind-ack\` -> \`/cc-ops rewind-ack\`
 
 ## HARD-GATE
 
@@ -30,7 +29,6 @@ Subcommands:
    - \`retro\` -> \`${RUNTIME_ROOT}/commands/retro.md\`
    - \`archive\` -> \`${RUNTIME_ROOT}/commands/archive.md\`
    - \`rewind\` -> \`${RUNTIME_ROOT}/commands/rewind.md\`
-   - \`rewind-ack\` -> \`${RUNTIME_ROOT}/commands/rewind-ack.md\`
 3. Unknown subcommand -> print supported values and stop.
 
 ## Primary skill
@@ -52,7 +50,7 @@ This wrapper only dispatches. It must not apply state mutations itself.
 
 ## Protocol
 
-1. Require a subcommand (\`feature|tdd-log|retro|archive|rewind|rewind-ack\`).
+1. Require a subcommand (\`feature|tdd-log|retro|archive|rewind\`).
 2. Route to the matching command contract + skill pair.
 3. Preserve pass-through args after the subcommand (e.g. \`/cc-ops rewind design\`).
 4. Echo which subcommand was dispatched for auditability.