@cleocode/core 2026.4.14 → 2026.4.16

package/src/paths.ts

@@ -15,6 +15,7 @@
  * @task T4458
  */
 
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -22,6 +23,76 @@ import { ExitCode } from '@cleocode/contracts';
 import { CleoError } from './errors.js';
 import { getPlatformPaths } from './system/platform-paths.js';
 
+// ============================================================================
+// Worktree Scope (T380/ADR-041 §D3)
+// ============================================================================
+
+/**
+ * Async context payload set by the spawn adapter when launching a subagent
+ * inside a git worktree (ADR-041 §D3).
+ *
+ * @remarks
+ * When `worktreeScope.run(scope, fn)` is active, `getProjectRoot()` returns
+ * `scope.worktreeRoot` instead of walking ancestors. All DB path functions
+ * that delegate to `getProjectRoot()` therefore direct their I/O to the
+ * worktree's `.cleo/` directory, closing the T335 worktree-leak root cause.
+ *
+ * For processes that were spawned with `CLEO_WORKTREE_ROOT` in their
+ * environment (but where AsyncLocalStorage is not in scope), callers should
+ * populate the store via:
+ * ```ts
+ * worktreeScope.run(
+ *   { worktreeRoot: process.env.CLEO_WORKTREE_ROOT, projectHash: process.env.CLEO_PROJECT_HASH },
+ *   () => { ... }
+ * );
+ * ```
+ *
+ * @task T380
+ * @public
+ */
+export interface WorktreeScope {
+  /**
+   * Absolute path to the worktree directory (value of `CLEO_WORKTREE_ROOT`).
+   */
+  worktreeRoot: string;
+  /**
+   * Project hash used to scope the worktree under the XDG worktree root
+   * (value of `CLEO_PROJECT_HASH`).
+   */
+  projectHash: string;
+}
+
+/**
+ * AsyncLocalStorage instance that carries the active {@link WorktreeScope}
+ * for the current async execution context.
+ *
+ * @remarks
+ * Set by the spawn adapter (or any caller that wants to redirect CLEO path
+ * resolution to a worktree directory) before invoking subagent logic.
+ * `getProjectRoot()` checks this store BEFORE the `CLEO_ROOT` env-var and
+ * ancestor-walk, so scoped callers transparently receive the worktree root.
+ *
+ * Callers outside a worktree context receive `undefined` from
+ * `worktreeScope.getStore()` and fall through to the existing resolution
+ * order unchanged.
+ *
+ * @example
+ * ```ts
+ * import { worktreeScope } from '@cleocode/core/paths';
+ *
+ * worktreeScope.run(
+ *   { worktreeRoot: '/path/to/worktree', projectHash: 'abc123' },
+ *   async () => {
+ *     const root = getProjectRoot(); // returns '/path/to/worktree'
+ *   }
+ * );
+ * ```
+ *
+ * @task T380
+ * @public
+ */
+export const worktreeScope = new AsyncLocalStorage<WorktreeScope>();
+
 /**
  * Check if a CLEO project is initialized at the given root.
  * Checks for tasks.db.
@@ -209,6 +280,14 @@ export function getCleoDirAbsolute(cwd?: string): string {
  * ```
  */
 export function getProjectRoot(cwd?: string): string {
+  // 0. AsyncLocalStorage worktree scope (T380/ADR-041 §D3) — checked FIRST.
+  //    When a spawn adapter wraps execution in worktreeScope.run(...), the
+  //    scoped root wins over all env-var and walk-based resolution.
+  const scope = worktreeScope.getStore();
+  if (scope !== undefined) {
+    return scope.worktreeRoot;
+  }
+
   // 1. Honour CLEO_ROOT env var — bypass walk entirely
   if (process.env['CLEO_ROOT']) {
     return process.env['CLEO_ROOT'];

package/src/store/brain-accessor.ts

@@ -251,6 +251,8 @@ export class BrainDataAccessor {
       project?: string;
       sourceType?: (typeof brainSchema.BRAIN_OBSERVATION_SOURCE_TYPES)[number];
       sourceSessionId?: string;
+      /** T417: filter by agent provenance name (Wave 8 mental models). */
+      agent?: string;
       limit?: number;
     } = {},
   ): Promise<BrainObservationRow[]> {
@@ -268,6 +270,9 @@ export class BrainDataAccessor {
     if (params.sourceSessionId) {
       conditions.push(eq(brainSchema.brainObservations.sourceSessionId, params.sourceSessionId));
     }
+    if (params.agent) {
+      conditions.push(eq(brainSchema.brainObservations.agent, params.agent));
+    }
 
     let query = this.db
       .select()

package/src/store/brain-schema.ts

@@ -172,6 +172,8 @@ export const brainObservations = sqliteTable(
     sourceType: text('source_type', { enum: BRAIN_OBSERVATION_SOURCE_TYPES })
       .notNull()
       .default('agent'),
+    /** T383/T417: agent provenance — identifies the spawned agent that produced this observation. Null for legacy entries. */
+    agent: text('agent'), // nullable — null for legacy observations
     contentHash: text('content_hash'), // SHA-256 prefix for dedup
     discoveryTokens: integer('discovery_tokens'), // cost to produce this observation
     createdAt: text('created_at').notNull().default(sql`(datetime('now'))`),
@@ -187,6 +189,8 @@ export const brainObservations = sqliteTable(
     index('idx_brain_observations_content_hash_created_at').on(table.contentHash, table.createdAt),
     // T033: type + project compound filter optimization
     index('idx_brain_observations_type_project').on(table.type, table.project),
+    // T417: agent provenance index for memory.find --agent filter
+    index('idx_brain_observations_agent').on(table.agent),
   ],
 );
 

package/src/store/nexus-validation-schemas.ts

@@ -14,11 +14,11 @@
  */
 
 import { createSchemaFactory } from 'drizzle-orm/zod';
-import { z } from 'zod/v4';
+import { z } from 'zod';
 
-// Use factory to bind our zod/v4 instance — ensures drizzle-orm/zod uses
+// Use factory to bind our zod instance — ensures drizzle-orm/zod uses
 // the same z we use everywhere. The type assertion is needed because
-// drizzle-orm beta.18's CoerceOptions type doesn't match zod/v4's coerce
+// drizzle-orm beta.18's CoerceOptions type doesn't match zod's coerce
 // namespace shape (works correctly at runtime).
 const { createInsertSchema, createSelectSchema } = createSchemaFactory(
   z as unknown as Parameters<typeof createSchemaFactory>[0],

package/src/store/validation-schemas.ts

@@ -13,11 +13,11 @@
  */
 
 import { createSchemaFactory } from 'drizzle-orm/zod';
-import { z } from 'zod/v4';
+import { z } from 'zod';
 
-// Use factory to bind our zod/v4 instance — ensures drizzle-orm/zod uses
+// Use factory to bind our zod instance — ensures drizzle-orm/zod uses
 // the same z we use everywhere. The type assertion is needed because
-// drizzle-orm beta.18's CoerceOptions type doesn't match zod/v4's coerce
+// drizzle-orm beta.18's CoerceOptions type doesn't match zod's coerce
 // namespace shape (works correctly at runtime).
 const { createInsertSchema, createSelectSchema } = createSchemaFactory(
   z as unknown as Parameters<typeof createSchemaFactory>[0],

package/src/validation/protocols/cant/architecture-decision.cant

@@ -8,13 +8,23 @@ type: conditional
 audience: "llm-agent, orchestrator"
 tags: "adr, architecture, decisions"
 skillRef: ct-adr-recorder
-lastUpdated: 2026-04-07
+lastUpdated: 2026-04-08
 enforcement: advisory
+stage: "architecture-decision"
+consult-when: "Recording a formal architecture decision after consensus reaches PROVEN verdict; superseding an existing ADR; any task carrying --protocol adr flag"
+input:
+  consensus_manifest_id: "string — ID of the originating consensus manifest (required)"
+  decision_title: "string — short title for the ADR"
+  options_evaluated: "string[] — options that were considered"
+output:
+  adr_id: "string — canonical ADR identifier (ADR-NNN)"
+  status: "proposed | accepted | superseded"
+  stored_at: "string — path to .cleo/adrs/<id>.md and decisions table row"
 ---
 
 # Architecture Decision Record (ADR) Protocol
 #
-# Provenance: @task T4798 (ADR-006 Implementation)
+# Provenance: @task T4798 (ADR-006 Implementation), @task T428 (gap patch)
 # Type: Conditional Protocol
 # Stage: RCADSD - A (ADR)
 # Max Active: 3 protocols (including base)

package/src/validation/protocols/cant/artifact-publish.cant

@@ -8,12 +8,22 @@ type: cross-cutting
 audience: "llm-agent, orchestrator"
 tags: "artifact, publish, distribution"
 skillRef: ct-artifact-publisher
-lastUpdated: 2026-04-07
+lastUpdated: 2026-04-08
 enforcement: advisory
+stage: "release"
+consult-when: "Publishing artifacts to any registry (npm, cargo, docker, PyPI, GitHub releases); any task with --protocol artifact-publish; release pipeline artifact phase"
+input:
+  artifact_type: "npm-package | python-wheel | python-sdist | go-module | cargo-crate | ruby-gem | docker-image | github-release | generic-tarball"
+  version: "string — version string consistent with release config"
+  dry_run: "boolean — MUST be true on first invocation"
+output:
+  published_artifacts: "object[] — array of {type, name, registry_url, sha256, slsa_level}"
+  rollback_manifest: "string | null — path to rollback manifest if partial failure"
 ---
 
 # Artifact Publish Protocol
 #
+# Provenance: @task T428 (gap patch)
 # Type: Conditional Protocol
 # Max Active: 3 protocols (including base)
 #

package/src/validation/protocols/cant/consensus.cant

@@ -8,8 +8,19 @@ type: conditional
 audience: "llm-agent, orchestrator"
 tags: "consensus, voting, validation"
 skillRef: ct-consensus-voter
-lastUpdated: 2026-04-07
+lastUpdated: 2026-04-08
 enforcement: strict
+stage: "consensus"
+consult-when: "Reaching a decision that two or more agents must vote on; architecture choices, tool selection, policy decisions; any task carrying agent_type:analysis; phrases like 'reach consensus', 'vote on options', 'resolve the debate'"
+input:
+  topic: "string — the question or decision to vote on"
+  options: "string[] — candidate options agents vote on"
+  agents: "string[] — agent IDs participating in the vote"
+output:
+  verdict: "PROVEN | REFUTED | CONTESTED | INSUFFICIENT_EVIDENCE"
+  confidence: "number — weighted confidence score 0.0–1.0"
+  voting_matrix: "object — per-agent votes with rationale and confidence"
+  hitl_required: "boolean — true when threshold not reached"
 ---
 
 # Consensus Protocol

package/src/validation/protocols/cant/contribution.cant

@@ -8,8 +8,18 @@ type: cross-cutting
 audience: "llm-agent, orchestrator"
 tags: "contribution, commit, pr"
 skillRef: ct-contribution
-lastUpdated: 2026-02-24
+lastUpdated: 2026-04-08
 enforcement: strict
+stage: "cross-cutting"
+consult-when: "Submitting work via git commit or PR; multi-agent consensus contribution; task carries 'contribution protocol', 'submit contribution', or 'consensus workflow'; any cross-cutting attribution recording"
+input:
+  task_id: "string — task being contributed"
+  commit_message: "string — conventional commit message"
+  contributors: "string[] — agent or human contributor IDs"
+output:
+  commit_sha: "string — resulting commit SHA"
+  pr_url: "string | null — pull request URL if opened"
+  attribution_recorded: "boolean — true when contribution row persisted"
 ---
 
 # Contribution Protocol

package/src/validation/protocols/cant/decomposition.cant

@@ -8,9 +8,19 @@ type: conditional
 audience: "llm-agent, orchestrator"
 tags: "decomposition, hierarchy, atomicity, planning"
 skillRef: ct-epic-architect
-lastUpdated: 2026-02-24
+lastUpdated: 2026-04-08
 provenanceTask: T3155
 enforcement: strict
+stage: "decomposition"
+consult-when: "Breaking a large initiative into atomic tasks; creating epics; planning parallel wave execution; any task with 'decompose', 'break down', 'epic architect', or 'plan tasks'"
+input:
+  epic_title: "string — high-level initiative title"
+  scope: "string — description of the work to decompose"
+  constraints: "string[] — known constraints or exclusions"
+output:
+  tasks: "object[] — array of {id, title, size, dependencies, wave} atomic tasks"
+  dependency_graph: "object — DAG of task dependencies"
+  wave_plan: "object[] — array of {wave, tasks[]} parallel execution waves"
 ---
 
 # Decomposition Protocol

package/src/validation/protocols/cant/implementation.cant

@@ -8,8 +8,18 @@ type: base
 audience: "llm-agent"
 tags: "implementation, coding, development"
 skillRef: ct-task-executor
-lastUpdated: 2026-02-24
+lastUpdated: 2026-04-08
 enforcement: strict
+stage: "implementation"
+consult-when: "Implementing code, fixing bugs, building features, writing programs; any task with 'implement', 'build', 'create', 'fix', 'patch'; IVT loop implementation phase"
+input:
+  task_id: "string — task being implemented"
+  spec_ref: "string | null — path or ID of the governing specification"
+  acceptance_criteria: "string[] — conditions that must be true on completion"
+output:
+  files_changed: "string[] — list of modified/created files"
+  tests_added: "string[] — new test files or test names"
+  manifest_entry: "object — implementation summary for MANIFEST.jsonl"
 ---
 
 # Implementation Protocol

package/src/validation/protocols/cant/provenance.cant

@@ -8,12 +8,24 @@ type: cross-cutting
 audience: "llm-agent, orchestrator"
 tags: "provenance, traceability, lineage"
 skillRef: ct-provenance-keeper
-lastUpdated: 2026-04-07
+lastUpdated: 2026-04-08
 enforcement: advisory
+stage: "release"
+consult-when: "Generating in-toto attestations, SLSA provenance, or SBOMs; signing artifacts; any task with 'provenance', 'attest', 'sbom', 'cosign', 'checksum', or 'supply chain'; invoked by artifact-publish at signing step"
+input:
+  artifact_paths: "string[] — paths to built artifacts requiring provenance"
+  source_commit: "string — git SHA of the source commit"
+  build_environment: "string — description of build environment"
+output:
+  attestation_path: "string — path to in-toto attestation JSON"
+  sbom_path: "string | null — path to CycloneDX or SPDX SBOM"
+  slsa_level: "1 | 2 | 3 | 4 — achieved SLSA Build Level"
+  digests: "object — map of artifact_path to sha256 digest"
 ---
 
 # Provenance Protocol
 #
+# Provenance: @task T428 (gap patch)
 # Type: Conditional Protocol
 # Max Active: 3 protocols (including base)
 #

package/src/validation/protocols/cant/release.cant

@@ -8,8 +8,19 @@ type: conditional
 audience: "llm-agent, orchestrator"
 tags: "release, semver, changelog"
 skillRef: ct-release-orchestrator
-lastUpdated: 2026-04-07
+lastUpdated: 2026-04-08
 enforcement: strict
+stage: "release"
+consult-when: "Shipping a new version; running 'cleo release ship'; promoting a completed epic to released status; any task with 'release', 'version bump', 'changelog', 'tag', 'publish'"
+input:
+  version: "string — CalVer YYYY.MM.patch target version"
+  changelog_entries: "string[] — summarized changes since last release"
+  artifact_config: "object | null — artifact publish config; null for source-only releases"
+output:
+  release_tag: "string — git tag created (e.g. v2026.4.5)"
+  changelog_path: "string — path to updated CHANGELOG file"
+  artifacts_published: "boolean — true when artifact phase ran"
+  release_manifest: "object — release summary for MANIFEST.jsonl"
 ---
 
 # Release Protocol

package/src/validation/protocols/cant/research.cant

@@ -8,8 +8,19 @@ type: base
 audience: "llm-agent, orchestrator"
 tags: "research, investigation, evidence"
 skillRef: ct-research-agent
-lastUpdated: 2026-02-24
+lastUpdated: 2026-04-08
 enforcement: strict
+stage: "research"
+consult-when: "Investigating unknown territory; gathering evidence before a consensus or specification; any task with 'research', 'investigate', 'explore', 'study', 'discover', 'analyze'; tasks that explicitly must NOT modify code"
+input:
+  topic: "string — subject of investigation"
+  scope: "string — boundaries of the research (what to include/exclude)"
+  output_dir: "string — directory for findings (default: .cleo/agent-outputs/)"
+output:
+  findings_path: "string — path to the research output markdown file"
+  manifest_entry: "object — 3–7 key findings for MANIFEST.jsonl"
+  confidence_levels: "object — per-finding confidence 0.0–1.0"
+  sources: "string[] — cited URLs or file paths"
 ---
 
 # Research Protocol

package/src/validation/protocols/cant/specification.cant

@@ -8,8 +8,18 @@ type: conditional
 audience: "llm-agent, orchestrator"
 tags: "specification, requirements, rfc2119"
 skillRef: ct-spec-writer
-lastUpdated: 2026-02-24
+lastUpdated: 2026-04-08
 enforcement: strict
+stage: "specification"
+consult-when: "Writing technical specifications, API contracts, or requirements documents; any task with 'spec', 'specification', 'requirements', 'rfc'; Specification stage only unlocks after an accepted ADR"
+input:
+  adr_id: "string — accepted ADR that governs this specification"
+  scope: "string — what the spec covers"
+  audience: "llm-agent | human | both — intended readers"
+output:
+  spec_path: "string — path to the written specification file"
+  requirement_count: "number — total MUST/SHOULD/MAY requirements"
+  testable_criteria: "string[] — acceptance criteria derivable from the spec"
 ---
 
 # Specification Protocol

package/src/validation/protocols/cant/testing.cant

@@ -8,8 +8,19 @@ type: base
 audience: "llm-agent, orchestrator"
 tags: "testing, ivt-loop, autonomous, framework-agnostic, compliance"
 skillRef: ct-ivt-looper
-lastUpdated: 2026-04-07
+lastUpdated: 2026-04-08
 enforcement: strict
+stage: "testing"
+consult-when: "Running the IVT loop after implementation; verifying acceptance criteria; any task with 'implement and verify', 'run IVT', 'ship this task', 'verify against spec', or implementation tasks with acceptance criteria"
+input:
+  task_id: "string — task under test"
+  spec_ref: "string | null — specification or acceptance criteria reference"
+  worktree: "string — git worktree path for test execution"
+output:
+  test_framework: "vitest | jest | mocha | pytest | cargo-test | go-test | rspec | phpunit | bats | other"
+  convergence_iterations: "number — IVT loop iterations to convergence"
+  test_results: "object — {passed, failed, skipped} counts"
+  manifest_entry: "object — convergence metrics for MANIFEST.jsonl"
 ---
 
 # Testing Protocol - Project-Agnostic IVT Loop

package/src/validation/protocols/cant/validation.cant

@@ -8,8 +8,18 @@ type: base
 audience: "llm-agent, orchestrator"
 tags: "validation, quality, compliance"
 skillRef: ct-validator
-lastUpdated: 2026-02-24
+lastUpdated: 2026-04-08
 enforcement: strict
+stage: "validation"
+consult-when: "Validating compliance against a schema, spec, or standard; running quality checks; any task with 'validate', 'compliance', 'verify', 'audit'; post-implementation quality gate"
+input:
+  target: "string — file path, document, or system under validation"
+  schema_ref: "string | null — schema or standard reference"
+  validation_type: "schema | code-style | protocol | document | custom"
+output:
+  passed: "boolean — overall validation result"
+  violations: "object[] — array of {rule, severity, location, message}"
+  report_path: "string — path to detailed validation report"
 ---
 
 # Validation Protocol