* feat(memory): typed provenance in AgentDB (ADR-323)
Corrects and implements the 2026-07-28 dream-cycle research proposal
(PR #2804, closed as superseded) for typed memory provenance in
AgentDB, addressing MemIR/MemSyco-Bench's "provenance-role collapse"
and memory-induced sycophancy findings.
The dream-cycle PR's proposed schema change targeted the wrong table
(`vector_indexes`, which is per-namespace HNSW index metadata, not
per-entry) and its filename collided with the already-merged
`ADR-322-metaharness-flywheel-integration.md` (#2817) — both corrected
here as ADR-323 against `memory_entries`, the real per-record table.
- memory-initializer.ts: `provenance_type` column (user_claim |
agent_output | system_observation | tool_result | unknown, default
unknown) on `memory_entries`, migrated for existing DBs via
`ensureSchemaColumns()`. `storeEntry()`/`searchEntries()` accept and
validate `provenanceType`/`provenanceFilter`.
- memory-bridge.ts: same wiring for the native better-sqlite3 AgentDB
v3 path (`bridgeStoreEntry`/`bridgeSearchEntries`).
- commands/memory.ts: `memory store --provenance <type>`, `memory
search --provenance-filter <types>` (comma-separated, OR semantics).
- mcp-tools/memory-tools.ts + cli-core/mcp-tools/memory-defs.ts:
`memory_store`'s `provenance_type` param, `memory_search`'s
`provenance_filter` param (kept in sync across both tool-def sets).
Found and fixed during implementation: an initial design skipped the
RaBitQ/HNSW acceleration paths entirely whenever a provenance filter
was requested (neither carries provenance_type on their candidates).
This reproducibly crashed the CLI process on exit (a libuv assertion
on Windows) after printing correct results. Fixed by never skipping
those paths — RaBitQ now fetches provenance_type in its existing
per-candidate query, HNSW does one batched (namespace, key) lookup
afterward — eliminating the crash across repeated runs. See ADR-323's
"Implementation note" for detail.
7 new end-to-end tests (adr-323-memory-provenance.test.ts), including
a repeated-run regression guard for the crash. Full existing memory
suite re-verified with no regressions (one pre-existing, environment-
specific #2558 test failure confirmed identical against unmodified
main — better-sqlite3's native bridge is unavailable in this dev
environment, unrelated to this change).
Closes the follow-up from dream-cycle PR #2804 (closed as superseded).
Co-Authored-By: claude-flow <ruv@ruv.net>
* fix(memory): enforce provenance across retrieval paths
* feat: add agentic policy engine
* fix: align Codex MCP integration
* fix: keep MetaHarness dependencies optional
* fix: declare MetaHarness as optional peers
* fix: sync workspace lockfile
* fix: document policy tool selection guidance
* test: cover governed in-process flywheel
* ci: make MetaHarness absence drill deterministic
* fix(codex): correct codex MCP server subcommand + sync package version
- mcp-bridge: `@openai/codex mcp serve` → `@openai/codex mcp-server`.
`codex mcp` manages *external* MCP servers (list/get/add/remove);
`codex mcp-server` is the "start Codex as an MCP server (stdio)"
command. `codex mcp serve` errors with "unrecognized subcommand
'serve'", so the `codex` MCP backend never started. Fixed in both
ruflo/src/mcp-bridge/index.js and ruflo/src/ruvocal/mcp-bridge/index.js.
- @claude-flow/codex: VERSION const was '3.0.0-alpha.8' while
package.json is '3.0.0-alpha.9' — `--version`/`info` reported the
wrong version. Synced to alpha.9.
Verified: `codex mcp serve` → error; `codex mcp-server` is valid.
@claude-flow/codex builds clean (tsc), 162 unit tests pass,
`claude-flow-codex` CLI (init/validate/doctor/templates/skills/dual)
all functional.
Co-Authored-By: RuFlo <ruv@ruv.net>
* feat(codex): W1 — dual-mode orchestrator spawns real `codex exec` for codex workers
Previously `codexCommand` defaulted to `'claude'` ("Both use claude CLI")
and every worker — claude or codex — was launched with Claude-CLI flags
(`-p`, `--output-format text`, `--max-turns`), so "dual-mode" was two
Claude instances. Now:
- `codexCommand` defaults to `'codex'`
- `executeHeadless` builds platform-specific args:
- claude: `-p <prompt> --output-format text [--max-turns N] [--model M]`
- codex: `exec --sandbox workspace-write --skip-git-repo-check [-m M] <prompt>`
(PROMPT is positional -> last; `codex exec` runs autonomously)
Remaining in W1 (next iterations): update `.claude/agents/dual-mode/
codex-worker.md` + `codex-coordinator.md` to invoke `codex exec` instead
of `claude -p`; add mocked-spawn smoke test (W4). Tracked: #1909.
Co-Authored-By: RuFlo <ruv@ruv.net>
* feat(codex): W1 (cont.) — dual-mode agent defs invoke `codex exec`, not `claude -p`
codex-worker.md / codex-coordinator.md described "headless Codex workers"
but every spawn example was `claude -p "..." --session-id X` with
Claude-only flags (--max-budget-usd, --allowedTools, --output-format).
Updated to match the W1 orchestrator change:
- spawn syntax → `codex exec --sandbox <workspace-write|read-only>
--skip-git-repo-check "<prompt>" &`
- dropped Claude-only flags; note that mixed-platform runs still use
`claude -p` for Claude workers
- swarm/memory CLI refs `claude-flow@v3alpha` → `ruflo@latest`
- MCP tool refs `mcp__claude-flow__*` / `mcp__ruv-swarm__*` → `mcp__ruflo__*`
W1 now complete (orchestrator + agent defs). dual-orchestrator.md left
as-is — it correctly documents the mixed Claude+Codex split. Smoke test
is W4. Tracked: #1909.
Co-Authored-By: RuFlo <ruv@ruv.net>
* feat(codex): W2 — `dual run --worker "<platform>:<role>:<prompt>"` + positional template
`dual run` only accepted `--template <name>` / `--config <path>`, so the
custom-worker syntax documented in CLAUDE.md (`dual run --worker
"claude:architect:..." --worker "codex:coder:..."`) didn't exist, and
`dual run feature` (positional) silently fell through to "specify
--template". Now:
- `dual run [template]` — positional alias for `--template`
- `-w, --worker "<platform>:<role>:<prompt>"` (repeatable; platform =
claude|codex; prompt may contain `:` — split on first two only).
Workers chain sequentially (each `dependsOn` the previous) unless
`--parallel-workers`. Unique ids derived from role.
- `parseWorkerSpecs()` exported for testing; clear errors on malformed
specs / bad platform.
- improved no-args usage text.
build clean (tsc), 162 tests pass. Tracked: #1909 (W2). Tests for
parseWorkerSpecs land in W4.
Co-Authored-By: RuFlo <ruv@ruv.net>
* feat(codex): W3 — standardize CLI ref claude-flow@alpha -> ruflo; fix MCP-server registration
The dual-mode orchestrator/CLI shelled out to `npx claude-flow@alpha
memory ...`, `claude-flow-codex init` registered the MCP server as
`codex mcp add claude-flow -- npx claude-flow mcp start`, and the
config.toml / migration generators emitted `[mcp_servers.claude-flow]`
with `args = ["-y", "@claude-flow/cli@latest"]` — the wrong package, an
inner-package name, and (in config-toml) **missing the `mcp start`
subcommand** so the server never actually started.
- dual-mode/{orchestrator,cli}.ts: `claude-flow@alpha` -> `ruflo@alpha`
- initializer.ts: `codex mcp add claude-flow -- npx claude-flow mcp start`
-> `codex mcp add ruflo -- npx ruflo mcp start`; "MCP server (ruflo)
registered"; `npx @claude-flow/cli mcp start` -> `npx ruflo mcp start`
- generators/config-toml.ts: default server `name: 'ruflo'`,
`args: ['-y', 'ruflo@latest', 'mcp', 'start']` (adds the missing
subcommand); `[mcp_servers.ruflo]` in all examples; the
already-configured check accepts both `ruflo` and legacy `claude-flow`
- generators/{agents-md,skill-md}.ts: `npx @claude-flow/cli ...` -> `npx ruflo ...`
- migrations/index.ts: default emitted server -> `[mcp_servers.ruflo]` /
`args = ["-y", "ruflo@latest", "mcp", "start"]` (user-provided servers
pass through unchanged)
- validators/index.ts: suggestion text -> `[mcp_servers.ruflo]`
- tests: updated generator/migration assertions to the new output
`npx vitest run` 162/162 pass. Note: `npm run build` (tsc) currently
fails on an UNRELATED uncommitted WIP file `src/loop/index.ts`
(exactOptionalPropertyTypes on prompt/command) — not from this change;
my files compile clean. Branding-only refs (config-toml header, repo
URLs in generated docs, remaining `@claude-flow/cli` in skill-md examples)
deferred to W7. Tracked: #1909 (W3).
Co-Authored-By: RuFlo <ruv@ruv.net>
* test(codex): W4 — dual-mode tests (parseWorkerSpecs, templates, orchestrator leveling, `dual` wiring)
New tests/dual-mode.test.ts (18 tests, no real workers spawned):
- parseWorkerSpecs: single spec, sequential chaining, --parallel-workers,
colons-in-prompt, id dedup, whitespace trim, and the 3 error paths
(too-few-colons / empty-prompt / unknown-platform)
- CollaborationTemplates: feature/security/refactor pipelines — ids,
platforms, dependsOn chains, task interpolation
- `dual` command wiring: run/templates/status subcommands; `run` exposes
--worker / --parallel-workers / --template and a positional [template]
- DualModeOrchestrator: safe defaults (codexCommand === 'codex'),
buildDependencyLevels for linear / fan-in / circular cases
Full suite: 184/184 pass (162 prior + 18 new + 4 loop). `npm run build`
still blocked on the unrelated uncommitted `src/loop/index.ts`. Deferred:
a full `CodexInitializer.initialize()` integration test (it shells out
`codex mcp add`, which would touch the user's real codex config — needs
a mock first). Tracked: #1909 (W4).
Co-Authored-By: RuFlo <ruv@ruv.net>
* feat(codex): W5 — generated SKILL.md frontmatter gets version/author/tags
`claude-flow-codex init` / `generate-skill` produced SKILL.md files with
only `name` + `description`, so `claude-flow-codex validate` flagged 3
"Consider adding field: version/author/tags" warnings per skill.
- SkillMdOptions: optional `version` ("1.0.0"), `author` ("rUv"), `tags`
(defaults to the skill name split on `-`)
- generateSkillMd emits `version: "..."`, `author: ...`, `tags: [...]`
in the frontmatter; built-in skills (via generateBuiltInSkill) inherit
the defaults automatically
Verified: a generated built-in skill validates with 0 warnings (was 3);
a bare `generate-skill` stub now has 1 warning ("No examples provided",
expected for a skill with no commands — out of scope here). `init →
validate → doctor` clean on the local build. `npm run build` + 184/184
tests pass. (The ~150 repo `.agents/skills/*/SKILL.md` are generated by
@claude-flow/cli, not this generator — out of scope.) Tracked: #1909 (W5).
Co-Authored-By: RuFlo <ruv@ruv.net>
* ci(codex): W6 — codex-integration-audit guard + workflow
`scripts/audit-codex-integration.mjs` — pure-Node static checks for the
Codex ↔ Ruflo invariants (issue #1909), exits non-zero on any failure:
- `codex` MCP backend uses `mcp-server` (not the invalid `mcp serve`) in
both ruflo/src/mcp-bridge and ruvocal/mcp-bridge
- @claude-flow/codex VERSION const === its package.json version
- dual-mode orchestrator: `codexCommand` defaults to 'codex', codex
workers spawn `codex exec --sandbox …`, no 'claude' fallback
- dual-mode agent defs reference `codex exec`, no legacy
`claude -p … --session-id` worker pattern
- no `claude-flow@alpha` / `@claude-flow/cli@latest` left in codex src
- `dual run` exposes `--worker <spec>` + positional `[template]`,
`parseWorkerSpecs` exported
- generateSkillMd emits version/author/tags frontmatter
- config.toml generator default MCP server = `ruflo` w/ `mcp start`
`.github/workflows/codex-integration-audit.yml` runs it on PRs / pushes
touching the codex package, mcp-bridge, dual-mode agents, or the script.
No `npm install` needed — build + tests stay in the main CI.
Audit passes on current branch. `npm run build` + 184/184 tests pass.
Tracked: #1909 (W6).
Co-Authored-By: RuFlo <ruv@ruv.net>
* feat(codex): claude-flow-codex loop runner — Codex-native /loop equivalent
Codex doesn't expose Claude Code's ScheduleWakeup, so this is a
process-based runner with the same behaviour:
- `loop run [prompt]` — repeated `codex exec` runs (or a custom
`--command`), bounded by `--max-iterations`/`--interval`, with
`--dry-run`, model/sandbox options, and a completion-marker-file
contract
- `loop status [--name <name>]` / `loop stop [--name <name>]`
- state persisted to `.codex/loop/<name>.json`; stop-file aware
- wired into the CLI (`src/cli.ts`), exported (`src/index.ts`), with a
`./loop` package export and README docs
(Implemented by rUv; landing it here so it isn't sitting dirty in the
worktree while the #1909 loop commits around it. `npm run build` +
184/184 tests pass; `git diff --check` clean.)
Co-Authored-By: RuFlo <ruv@ruv.net>
* chore(codex): W7 — package.json hygiene + repo URLs ruvnet/claude-flow -> ruvnet/ruflo
- package.json: drop dead `"templates"` from `files` (no templates/ dir
at the package root — templates compile to dist/templates/); repository
/ homepage / bugs URLs -> ruvnet/ruflo; description -> "Ruflo (claude-flow)"
- src/index.ts: PACKAGE_INFO.repository -> ruvnet/ruflo
- src/initializer.ts, generators/{agents-md,config-toml}.ts: generated
AGENTS.md / config.toml doc URLs -> ruvnet/ruflo (+ "Ruflo:" label)
- README.md: badge + footer URLs -> ruvnet/ruflo
- tests: assertion for the config.toml Documentation line
`npm run build` + 184/184 tests pass; codex-integration audit passes.
(Committed `.agents/AGENTS.md` / `.agents/config.toml` in the repo still
carry old URLs — generated artifacts; the generators are now fixed so
re-init produces ruvnet/ruflo. The published `claude-flow-codex`
package name stays as-is.) Tracked: #1909 (W7).
Co-Authored-By: RuFlo <ruv@ruv.net>
---------
Co-authored-by: Reuven <cohen@ruv-mac-mini.local>
Automatic checkpoint created by Claude Code
- Branch: feature/codex-integration
- Timestamp: 2026-02-07T16:43:49Z
- Changes: 1 file(s)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Automatic checkpoint created by Claude Code
- Branch: feature/codex-integration
- Timestamp: 2026-02-07T16:43:42Z
- Changes: 1 file(s)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Automatic checkpoint created by Claude Code
- Branch: feature/codex-integration
- Timestamp: 2026-02-07T16:39:55Z
- Changes: 1 file(s)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Automatic checkpoint created by Claude Code
- Branch: feature/codex-integration
- Timestamp: 2026-02-07T16:39:47Z
- Changes: 1 file(s)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Automatic checkpoint created by Claude Code
- Branch: feature/codex-integration
- Timestamp: 2026-02-07T16:39:32Z
- Changes: 1 file(s)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Automatic checkpoint created by Claude Code
- Branch: feature/codex-integration
- Timestamp: 2026-02-07T16:39:25Z
- Changes: 2 file(s)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Automatic checkpoint created by Claude Code
- Branch: feature/codex-integration
- Timestamp: 2026-02-07T16:38:57Z
- Changes: 1 file(s)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Automatic checkpoint created by Claude Code
- Branch: feature/codex-integration
- Timestamp: 2026-02-07T16:38:50Z
- Changes: 1 file(s)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Automatic checkpoint created by Claude Code
- Branch: feature/codex-integration
- Timestamp: 2026-02-07T16:36:41Z
- Changes: 1 file(s)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
rUv