cclaw-cli 0.5.4 → 0.5.6

package/README.md

@@ -27,10 +27,10 @@ sequenceDiagram
     participant U as User
     participant H as Harness
     participant V as cclaw Hooks + Skills
-    participant S as State + Learnings
+    participant S as State + Knowledge
     U->>H: /cc <idea>
     H->>V: Load stage contract + HARD-GATE
-    V->>S: Read context (state/learnings)
+    V->>S: Read context (state/knowledge)
     V-->>H: Structured execution guidance
     H->>S: Write artifacts + checkpoint
     S-->>U: Next stage is explicit
@@ -42,8 +42,8 @@ sequenceDiagram
 - **Installer-first architecture:** generates files and hooks; does not run a hidden control plane.
 - **Hard-gated quality:** each stage has non-skippable constraints that reduce AI drift.
 - **Cross-harness parity:** same behavior model across Claude Code, Cursor, Codex, OpenCode.
-- **Compounding context:** flow state + learnings get rehydrated on new sessions automatically.
-- **Run-scoped execution:** each flow works against an active run with explicit handoff state.
+- **Compounding context:** flow state + project knowledge get rehydrated on new sessions automatically.
+- **Incremental delivery:** active artifacts stay in one place; `cclaw archive` snapshots completed features into dated run folders.
 
 ## Compared To Top References
 
@@ -73,6 +73,7 @@ Core installer lifecycle:
 ```bash
 npx cclaw-cli sync
 npx cclaw-cli doctor
+npx cclaw-cli archive --name <feature-name>
 npx cclaw-cli upgrade
 npx cclaw-cli uninstall
 ```
@@ -113,14 +114,10 @@ Required repository secret:
 ├── commands/
 ├── hooks/
 ├── templates/
-├── artifacts/                # active mirror for current run (fallback path)
+├── artifacts/                # active feature artifacts
 ├── state/
-├── runs/
-│   └── <activeRunId>/
-│       ├── artifacts/        # canonical run artifacts
-│       ├── run.json
-│       └── handoff.md
-└── learnings.jsonl
+├── knowledge.md              # append-only rule/pattern/lesson log
+└── runs/                     # archived feature snapshots (YYYY-MM-DD-feature-name)
 ```
 
 ## License

package/dist/artifact-linter.js

@@ -3,20 +3,10 @@ import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
 import { exists } from "./fs-utils.js";
 import { orderedStageSchemas, stageSchema } from "./content/stage-schema.js";
-import { readFlowState } from "./runs.js";
 async function resolveArtifactPath(projectRoot, fileName) {
-    const fallbackRelPath = path.join(RUNTIME_ROOT, "artifacts", fileName);
-    const fallbackAbsPath = path.join(projectRoot, fallbackRelPath);
-    const { activeRunId } = await readFlowState(projectRoot);
-    const runId = activeRunId.trim();
-    if (runId.length > 0) {
-        const canonicalRelPath = path.join(RUNTIME_ROOT, "runs", runId, "artifacts", fileName);
-        const canonicalAbsPath = path.join(projectRoot, canonicalRelPath);
-        if (await exists(canonicalAbsPath)) {
-            return { absPath: canonicalAbsPath, relPath: canonicalRelPath };
-        }
-    }
-    return { absPath: fallbackAbsPath, relPath: fallbackRelPath };
+    const relPath = path.join(RUNTIME_ROOT, "artifacts", fileName);
+    const absPath = path.join(projectRoot, relPath);
+    return { absPath, relPath };
 }
 function normalizeHeadingTitle(title) {
     return title.trim().replace(/\s+/g, " ");

package/dist/cli.d.ts

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import type { HarnessId } from "./types.js";
-type CommandName = "init" | "sync" | "doctor" | "upgrade" | "uninstall";
+type CommandName = "init" | "sync" | "doctor" | "upgrade" | "uninstall" | "archive";
 interface ParsedArgs {
     command?: CommandName;
     harnesses?: HarnessId[];
     reconcileGates?: boolean;
+    archiveName?: string;
 }
 declare function parseHarnesses(raw: string): HarnessId[];
 declare function parseArgs(argv: string[]): ParsedArgs;

package/dist/cli.js

@@ -7,7 +7,8 @@ import { HARNESS_IDS } from "./types.js";
 import { doctorChecks, doctorSucceeded } from "./doctor.js";
 import { initCclaw, syncCclaw, uninstallCclaw, upgradeCclaw } from "./install.js";
 import { error, info } from "./logger.js";
-const INSTALLER_COMMANDS = ["init", "sync", "doctor", "upgrade", "uninstall"];
+import { archiveRun } from "./runs.js";
+const INSTALLER_COMMANDS = ["init", "sync", "doctor", "upgrade", "uninstall", "archive"];
 function usage() {
     return `cclaw - installer-first flow toolkit
 
@@ -15,6 +16,7 @@ Usage:
   cclaw init [--harnesses=claude,cursor,opencode,codex]
   cclaw sync
   cclaw doctor [--reconcile-gates]
+  cclaw archive [--name=feature-name]
   cclaw upgrade
   cclaw uninstall
 `;
@@ -43,6 +45,10 @@ function parseArgs(argv) {
         }
         if (flag === "--reconcile-gates") {
             parsed.reconcileGates = true;
+            continue;
+        }
+        if (flag.startsWith("--name=")) {
+            parsed.archiveName = flag.replace("--name=", "").trim();
         }
     }
     return parsed;
@@ -80,6 +86,11 @@ async function runCommand(parsed, ctx) {
         info(ctx, "Upgraded .cclaw runtime and regenerated generated files");
         return 0;
     }
+    if (command === "archive") {
+        const archived = await archiveRun(ctx.cwd, parsed.archiveName);
+        info(ctx, `Archived active artifacts to ${archived.archivePath}. Flow state reset to brainstorm.`);
+        return 0;
+    }
     await uninstallCclaw(ctx.cwd);
     info(ctx, "Removed .cclaw runtime and generated shim files");
     return 0;

package/dist/config.js

@@ -12,8 +12,6 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "flowVersion",
     "harnesses",
     "autoAdvance",
-    "globalLearnings",
-    "globalLearningsPath",
     "promptGuardMode",
     "gitHookGuards"
 ]);
@@ -37,7 +35,6 @@ export function createDefaultConfig(harnesses = DEFAULT_HARNESSES) {
         flowVersion: FLOW_VERSION,
         harnesses,
         autoAdvance: false,
-        globalLearnings: false,
         promptGuardMode: "advisory",
         gitHookGuards: false
     };
@@ -79,20 +76,6 @@ export async function readConfig(projectRoot) {
         : DEFAULT_HARNESSES;
     const autoAdvanceRaw = parsed.autoAdvance;
     const autoAdvance = typeof autoAdvanceRaw === "boolean" ? autoAdvanceRaw : false;
-    const globalLearningsRaw = parsed.globalLearnings;
-    if (Object.prototype.hasOwnProperty.call(parsed, "globalLearnings") &&
-        typeof globalLearningsRaw !== "boolean") {
-        throw configValidationError(fullPath, `"globalLearnings" must be a boolean`);
-    }
-    const globalLearnings = typeof globalLearningsRaw === "boolean" ? globalLearningsRaw : false;
-    const globalLearningsPathRaw = parsed.globalLearningsPath;
-    if (Object.prototype.hasOwnProperty.call(parsed, "globalLearningsPath") &&
-        typeof globalLearningsPathRaw !== "string") {
-        throw configValidationError(fullPath, `"globalLearningsPath" must be a string`);
-    }
-    const globalLearningsPath = typeof globalLearningsPathRaw === "string" && globalLearningsPathRaw.trim().length > 0
-        ? globalLearningsPathRaw.trim()
-        : undefined;
     const promptGuardModeRaw = parsed.promptGuardMode;
     if (Object.prototype.hasOwnProperty.call(parsed, "promptGuardMode") &&
         promptGuardModeRaw !== "advisory" &&
@@ -111,8 +94,6 @@ export async function readConfig(projectRoot) {
         flowVersion: parsed.flowVersion ?? FLOW_VERSION,
         harnesses,
         autoAdvance,
-        globalLearnings,
-        globalLearningsPath,
         promptGuardMode,
         gitHookGuards
     };

package/dist/content/contracts.js

@@ -6,13 +6,7 @@ export function commandContract(stage) {
     const reads = schema.crossStageTrace.readsFrom;
     const readsLine = reads.length > 0 ? reads.join(", ") : "(first stage)";
     const hydrationLines = reads.length > 0
-        ? reads
-            .map((readPath) => {
-            const parts = readPath.split("/");
-            const fileName = parts[parts.length - 1] ?? readPath;
-            return `- Canonical: \`.cclaw/runs/<activeRunId>/artifacts/${fileName}\` (fallback: \`${readPath}\`)`;
-        })
-            .join("\n")
+        ? reads.map((readPath) => `- \`${readPath}\``).join("\n")
         : "- (first stage — no upstream artifacts)";
     const gateIds = schema.requiredGates
         .map((g) => `\`${g.id}\``)
@@ -26,16 +20,17 @@ ${schema.hardGate}
 
 ## In / Out
 - **Reads:** ${readsLine}
-- **Writes:** \`.cclaw/artifacts/${schema.artifactFile}\` (run snapshot under \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\` is synchronized by cclaw runtime)
+- **Writes:** \`.cclaw/artifacts/${schema.artifactFile}\`
 - **Next:** \`/cc-next\` (updates flow-state and loads the next stage)
 
 ## Context Hydration (mandatory before stage work)
-1. Read \`.cclaw/state/flow-state.json\` and capture \`activeRunId\`.
-2. Resolve canonical artifact root: \`.cclaw/runs/<activeRunId>/artifacts/\`.
+1. Read \`.cclaw/state/flow-state.json\`.
+2. Resolve active artifact root: \`.cclaw/artifacts/\`.
 3. Load required upstream artifacts for this stage:
 ${hydrationLines}
-4. If a canonical run artifact is missing, fallback to the matching file under \`.cclaw/artifacts/\` and record that fallback in the stage artifact.
-5. Write stage output to \`.cclaw/artifacts/${schema.artifactFile}\`. Do NOT manually copy into run directories; cclaw sync/runtime keeps run snapshots aligned.
+4. Load \`.cclaw/knowledge.md\` and apply relevant entries.
+5. Write stage output to \`.cclaw/artifacts/${schema.artifactFile}\`.
+6. Do NOT copy artifacts into \`.cclaw/runs/\`; archival is handled only by \`cclaw archive\`.
 
 ## Gates
 ${gateIds}

package/dist/content/examples.js

@@ -1,69 +1,51 @@
 const STAGE_EXAMPLES = {
-    brainstorm: `### Clarification sequence (Socratic)
+    brainstorm: `### Context
 
-**Q1 (PURPOSE):** "What decision will this demo help your audience make, and who exactly is that audience?"  
-**A1:** "Internal platform team; they should see whether our release flow can be trusted."
+- **Project state:** Monorepo with CI pipeline using custom release scripts. Release checks are scattered across shell scripts with no shared validation logic.
+- **Relevant existing code/patterns:** \`scripts/pre-publish.sh\` does metadata checks. \`src/release/\` has partial validation helpers.
 
-**Q2 (SCOPE):** "Which outcomes are explicitly OUT of scope for this demo so we avoid accidental expansion?"  
-**A2:** "No production rollout automation; only release metadata validation + publish safety checks."
+### Problem
 
-**Q3 (BOUNDARIES):** "When release metadata is missing or invalid, what should happen and what should NEVER happen?"  
-**A3:** "Must block release with a clear reason; must never auto-publish anyway."
+- **What we're solving:** release checks are fragile and inconsistent between CI and local runs. Invalid metadata sometimes reaches npm publish.
+- **Success criteria:** invalid release preconditions are caught before publish with explicit operator feedback, in both CI and local workflows.
+- **Constraints:** no new runtime dependencies; must work within existing CI pipeline structure.
 
-**Q4 (ENVIRONMENT):** "Where will this run in practice: local only, CI only, or both? How is it installed and invoked?"  
-**A4:** "CI-first in GitHub Actions, but reproducible locally with npm scripts."
+### Clarifying Questions
 
-**Q5 (CONSTRAINTS):** "What constraints are non-negotiable (runtime deps, latency, compatibility, policy)?"  
-**A5:** "No new runtime dependencies; checks should stay under 2 minutes; compatible with current workflow."
-
-### One-question-per-message discipline
-
-**Bad (bundled):** "Where will this run? Which Python version? Stdlib only? Any perf limits?"
-
-**Good (single ask):** "Where will this run in practice: local only, CI only, or both?"
-
-**Then next turn:** "Which runtime version should we lock as minimum?"
-
-**Then next turn:** "Should we treat 'stdlib-only' as a hard dependency constraint?"
-
-### Premise challenge and boundary stress-test
-
-**Premise challenge:** "If the goal is only to demonstrate filesystem I/O, why is a CLI better than a tiny script or notebook for this demo?"
-
-**Boundary stress-test:** "When a write fails midway (permissions or partial path issues), what outcome should NEVER happen?"
-
-### Alternatives comparison
-
-| Approach | Pros | Cons | Effort | Recommendation |
-| --- | --- | --- | --- | --- |
-| REST + polling | Simple to deploy; works through strict proxies; easy to cache | Higher latency; wasted requests; battery use on mobile | Low | Good default when real-time is not required |
-| WebSocket | Lowest latency; bidirectional; efficient for bursts | More ops complexity; reconnect/state sync; harder through some gateways | Medium | Prefer when server must push frequently or conversationally |
-| SSE | One-way server push over HTTP; simpler than WebSockets for “notify only” | Unidirectional; browser connection limits; proxy buffering quirks | Low–Medium | Prefer for live dashboards and one-way event streams |
+| # | Question | Answer | Decision impact |
+| --- | --- | --- | --- |
+| 1 | If release metadata is invalid, should we block publishing hard or only warn? | Block hard. | Validation becomes a mandatory gate — no warning-only fallback. |
+| 2 | Should the validation logic live in a reusable module or stay as shell scripts? | Reusable module. | Architecture: shared TypeScript module imported by CI and local tooling, not duplicated shell scripts. |
+| 3 | For v1, prioritize rapid delivery or maximum configurability? | Rapid delivery. | Minimal deterministic validation surface; defer plugin/config system to v2. |
 
-### Approved Direction
+### Approaches
 
-We will ship **SSE for server-originated notifications** to the web client first, because the UX requires timely delivery without bidirectional chat. We will keep a **REST fallback** for environments where SSE is unreliable, and we will defer WebSockets until we have a concrete bidirectional requirement (collaborative editing).
+| Approach | Architecture | Trade-offs | Recommendation |
+| --- | --- | --- | --- |
+| A: Reusable validation module | Shared TS module with typed validators, imported by CI scripts and local CLI. Existing \`pre-publish.sh\` calls the module. | Medium upfront effort, high reuse. Requires test coverage for the module. | **Recommended** — best balance of reuse and delivery speed. |
+| B: Hardened shell scripts | Keep existing script approach, add stricter checks and error messages. | Lowest effort. Weak reuse, CI/local divergence risk grows over time. | Viable fallback if TS module is blocked. |
+| C: Full release framework | New release orchestrator with plugin system, config files, rollback commands. | Maximum flexibility. High risk, delivery delay, over-engineered for current needs. | Not recommended for v1. |
 
-### Open Questions
+### Selected Direction
 
-- Do we need guaranteed delivery semantics (at-least-once vs best-effort) for in-app banners?
-- What is the maximum event rate we must support per user session without degrading the UI thread?
-- Should mobile clients reuse the same event channel contract or expose a separate polling endpoint?
+- **Approach:** A — Reusable validation module
+- **Rationale:** shared TS module gives consistent behavior in CI and local, avoids script duplication, and stays within the no-new-dependency constraint.
+- **Approval:** approved
 
-### Assumptions (explicit)
+### Design
 
-- Users are authenticated; anonymous traffic does not receive personalized streams.
-- “Notification” means **account-scoped operational messages**, not third-party ads.
-- The first release optimizes for **web**; native clients can lag by one sprint.
+- **Architecture:** single \`release-validator\` module in \`src/release/\` exporting typed check functions. CI script and local CLI both import and run the same checks.
+- **Key components:** \`validateMetadata()\`, \`validateChangelog()\`, \`validateVersion()\` — each returns a typed result with error details. A \`runAll()\` orchestrator runs checks and exits non-zero on any failure.
+- **Data flow:** package.json + CHANGELOG.md → validator module → structured result → CI/CLI renders human-readable report.
 
-### Constraints
+### Assumptions and Open Questions
 
-- No new infrastructure class (managed broker) unless latency goals are missed in a spike.
-- Compliance requires auditability: who saw what, when — at least at coarse granularity.
+- **Assumptions:** CI remains the primary execution path; existing release metadata files remain the source of truth; v1 prioritizes determinism over customization.
+- **Open questions:** What exact rollback sequence for failed publish? Should status output include machine-readable JSON alongside markdown?
 
 ### Notes for the next stage
 
-Capture the chosen direction as a **single paragraph decision** (above) and ensure open questions are either answered in scope or explicitly deferred with an owner + date.`,
+Carry the no-new-dependency constraint and hard-block behavior directly into scope in/out boundaries.`,
     scope: `### Scope contract
 
 **Mode selected:** SELECTIVE EXPANSION

package/dist/content/hooks.d.ts

@@ -1,20 +1,18 @@
 /**
  * Hook generators for all supported harnesses.
  *
- * SessionStart: injects using-cclaw + flow state + learnings + checkpoint/activity summary.
+ * SessionStart: injects using-cclaw + flow state + knowledge + checkpoint/activity summary.
  * Stop: writes checkpoint.json and reminds about flow consistency.
- * PreToolUse/PostToolUse and summarize chain are generated in observe.ts.
+ * Harness hook JSON wiring is generated in observe.ts.
  */
 export interface HookRuntimeOptions {
-    globalLearningsEnabled?: boolean;
-    globalLearningsPath?: string;
 }
 /** Shared bash preamble for generated hook scripts. */
 export declare const RUNTIME_SHELL_DETECT_ROOT = "HARNESS=\"codex\"\nif [ -n \"${CLAUDE_PROJECT_DIR:-}\" ]; then\n  HARNESS=\"claude\"\nelif [ -n \"${CURSOR_PROJECT_DIR:-}\" ] || [ -n \"${CURSOR_PROJECT_ROOT:-}\" ]; then\n  HARNESS=\"cursor\"\nelif [ -n \"${OPENCODE_PROJECT_DIR:-}\" ] || [ -n \"${OPENCODE_PROJECT_ROOT:-}\" ]; then\n  HARNESS=\"opencode\"\nfi\n\nROOT=\"\"\nfor candidate in \"${CCLAW_PROJECT_ROOT:-}\" \"${CLAUDE_PROJECT_DIR:-}\" \"${CURSOR_PROJECT_DIR:-}\" \"${CURSOR_PROJECT_ROOT:-}\" \"${OPENCODE_PROJECT_DIR:-}\" \"${OPENCODE_PROJECT_ROOT:-}\" \"${PWD:-}\"; do\n  if [ -n \"$candidate\" ] && [ -d \"$candidate/.cclaw\" ]; then\n    ROOT=\"$candidate\"\n    break\n  fi\ndone\nif [ -z \"$ROOT\" ]; then\n  ROOT=\"${CCLAW_PROJECT_ROOT:-${CLAUDE_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-${CURSOR_PROJECT_ROOT:-${OPENCODE_PROJECT_DIR:-${OPENCODE_PROJECT_ROOT:-${PWD}}}}}}}\"\nfi";
-export declare function sessionStartScript(options?: HookRuntimeOptions): string;
+export declare function sessionStartScript(_options?: HookRuntimeOptions): string;
 export declare function stopCheckpointScript(): string;
 export { claudeHooksJsonWithObservation as claudeHooksJson } from "./observe.js";
 export { cursorHooksJsonWithObservation as cursorHooksJson } from "./observe.js";
 export { codexHooksJsonWithObservation as codexHooksJson } from "./observe.js";
-export declare function opencodePluginJs(options?: HookRuntimeOptions): string;
+export declare function opencodePluginJs(_options?: HookRuntimeOptions): string;
 export declare function hooksAgentsMdBlock(): string;