From 9524d049604c8a54c4be4c444e16a5aa54a79d05 Mon Sep 17 00:00:00 2001 From: rebel Date: Wed, 15 Jul 2026 16:51:00 +0530 Subject: [PATCH] lighten CLI and align release truth --- PROJECT_STATUS.json | 8 +- README.md | 51 ++-- REPOSITORY_MANIFEST.json | 37 +-- apps/cli/help.mjs | 401 ++++++++++++++++++++++++++ apps/cli/oaf.mjs | 405 +-------------------------- docs/release/1.0-PROVENANCE.json | 2 +- docs/release/1.0-READINESS-REPORT.md | 2 +- docs/release/1.0-REPRODUCIBILITY.md | 2 +- scripts/consumer-browser-smoke.mjs | 9 + tests/usage-docs.test.mjs | 16 +- 10 files changed, 487 insertions(+), 446 deletions(-) create mode 100644 apps/cli/help.mjs diff --git a/PROJECT_STATUS.json b/PROJECT_STATUS.json index 3084e7c..dc8bfb6 100644 --- a/PROJECT_STATUS.json +++ b/PROJECT_STATUS.json @@ -86,7 +86,7 @@ "One running local server remains bound to one repository; the repository control documents how to start recall serve elsewhere rather than claiming hot switching", "Dependency-free routed shell; no production frontend framework", "Uses the loopback Control API only and does not read storage directly", - "OAF-024 views are read-only and do not add approval mutation endpoints", + "Memory evidence views keep reads separate from confirm-gated proposal approval through the authenticated loopback API; they do not add write-capable MCP tools or external writes", "Fabric Map is a read-only visualization over existing local dashboard state; it does not add telemetry, model calls, external adapters, or external writes" ] }, @@ -785,8 +785,8 @@ "docs/release/1.0-RELEASE-CHECKLIST.md" ], "limitations": [ - "Release-candidate readiness evidence is merged to main; npm metadata is publish-ready, but product 1.0 is not published", - "Final merge, tag creation, artifact signing, and product release publication require explicit maintainer approval", + "memory-recall 1.0.5 is published; the 1.1.0 source release candidate on main is not yet published to npm", + "Publishing, tagging, or signing the 1.1.0 release candidate requires explicit maintainer approval", "No signing keys, release credentials, hosted publishing automation, external writes, or external adapter activation are added" ] }, @@ -1048,7 +1048,7 @@ "npm run consumer:smoke", "npm run consumer:browser-smoke" ], - "testsExpected": 659, + "testsExpected": 660, "protocolFixturesExpected": 182, "evaluationsExpected": 144, "note": "Counts are a dated snapshot; command results and HANDOFF_VERIFICATION.json are authoritative." diff --git a/README.md b/README.md index 4e30ff9..782aa8a 100644 --- a/README.md +++ b/README.md @@ -22,15 +22,22 @@ Memory Recall turns a repository into a governed context source. New agent sessions get reviewed repo facts, changed-file impact, required local reads, and proof of what was sent instead of a giant pasted transcript. +The current source checkout is the 1.1.0 release candidate. npm still serves +1.0.5, which does not include Recall Map. Until 1.1.0 is published, run the +current quickstart from a source checkout: + ```bash -npm install -g memory-recall -recall setup -recall map --root . --sqlite .local/memory.sqlite --format summary -recall handoff +git clone https://github.com/rebel0789/Memory-Recall.git +cd Memory-Recall +npm install +npm run recall -- setup +npm run recall -- map --root . --sqlite .local/memory.sqlite --format summary +npm run recall -- handoff ``` `recall setup` creates only local state. `recall map` is the explicit first -read-only repository scan; it does not run silently during setup. +read-only repository scan; it does not run silently during setup. After 1.1.0 +is published, the global `recall` commands are the equivalent installed path. Normal quickstarts use `recall`. The [developer-first product contract](docs/product/memory-recall-developer-first.md) defines the `implemented`, `experimental`, and `unsupported` capability @@ -52,28 +59,30 @@ for preserved legacy names and URIs. ## Five-Minute Path ```bash -# Install the CLI. -npm install -g memory-recall +# Install the current source release candidate. +git clone https://github.com/rebel0789/Memory-Recall.git +cd Memory-Recall +npm install # Create local state only. This does not scan the repository. -recall setup +npm run recall -- setup # Run the first explicit read-only repository map. -recall map --root . --sqlite .local/memory.sqlite --format summary +npm run recall -- map --root . --sqlite .local/memory.sqlite --format summary # Run the handoff verification gate. -recall verify +npm run recall -- verify # Preview local agent setup. This writes nothing. -recall connect codex --dry-run --format json -recall mcp install --client claude-code --dry-run --format json +npm run recall -- connect codex --dry-run --format json +npm run recall -- mcp install --client claude-code --dry-run --format json # Build governed memory proposals. Facts are not trusted until reviewed. -recall memory ingest --root . --sqlite .local/memory.sqlite --format json -recall memory review --root . --sqlite .local/memory.sqlite --format summary +npm run recall -- memory ingest --root . --sqlite .local/memory.sqlite --format json +npm run recall -- memory review --root . --sqlite .local/memory.sqlite --format summary # Produce the compact handoff for the next coding agent. -recall handoff +npm run recall -- handoff ``` The default path is local and explicit: no hosted account, no model API key, no @@ -84,9 +93,9 @@ consented provider request to create pending proposals from selected documentation. Start with the body-free plan: ```bash -recall semantic plan --harness codex --root . --dry-run -recall semantic task --harness codex --root . -recall semantic import --input semantic-result.json --root . --sqlite .local/memory.sqlite +npm run recall -- semantic plan --harness codex --root . --dry-run +npm run recall -- semantic task --harness codex --root . +npm run recall -- semantic import --input semantic-result.json --root . --sqlite .local/memory.sqlite ``` The CLI does not invoke the harness. Direct API execution requires a user-owned @@ -243,12 +252,12 @@ boundaries. ## Status -Development kit: **1.0.5**. +Source release candidate: **1.1.0**. Published npm version: **1.0.5**. | Surface | Status | | --- | --- | -| Source checkout | Local-ready reference path | -| npm package | Published as `memory-recall` | +| Source checkout | 1.1.0 local-ready release candidate | +| npm package | 1.0.5 published; Recall Map quickstart awaits the 1.1.0 release | | CLI | `recall` | | Marketplace / plugin registry | Manifest prepared; not submitted | | Client hooks | Opt-in Codex/Claude connect writer; dry-run/manual fallback | diff --git a/REPOSITORY_MANIFEST.json b/REPOSITORY_MANIFEST.json index a0d1509..f20c354 100644 --- a/REPOSITORY_MANIFEST.json +++ b/REPOSITORY_MANIFEST.json @@ -1,9 +1,9 @@ { "schemaVersion": "1.0.0", "project": "memory-recall", - "generatedAt": "2026-07-15T10:17:11.564Z", - "fileCount": 922, - "totalBytes": 6425642, + "generatedAt": "2026-07-15T11:16:55.792Z", + "fileCount": 923, + "totalBytes": 6428286, "exclusions": [ ".git/**", ".local/**", @@ -450,10 +450,15 @@ "bytes": 566, "sha256": "b4dd09cbbf368a7138af69fa727cff125161dede497c728783d15a3587659c17" }, + { + "path": "apps/cli/help.mjs", + "bytes": 25248, + "sha256": "0c0117d86106ec7e5f9cd65a3481ef92b06d5daf63fab94cb26517a9d7ac766d" + }, { "path": "apps/cli/oaf.mjs", - "bytes": 484685, - "sha256": "8927c21f14affef6c6d12e701e234db4201b5292c00ef49632644489de02b2ad" + "bytes": 459579, + "sha256": "fa7200d942591e92ef954ac3879cf1d9556cf1aa907a52658066ad1002ea9a4b" }, { "path": "apps/web/AGENTS.md", @@ -1088,12 +1093,12 @@ { "path": "docs/release/1.0-PROVENANCE.json", "bytes": 2414, - "sha256": "b784ca3507a140e11fa2d72e4b7f83ac98997ccbdfcb8c96b7888079b6645393" + "sha256": "fb281b9df61cd9cf0012eebec67a668dd74635666fd2ea623ff8d983359de1cc" }, { "path": "docs/release/1.0-READINESS-REPORT.md", "bytes": 3391, - "sha256": "e4d95f4d9edc743526107b519a63db07955dc225c8e0d3f325261bc8e3919b9c" + "sha256": "5ed33403f42cfc4fa86ba01c06c797ca7d641ea1db80b26e8764c9d39e023df6" }, { "path": "docs/release/1.0-RELEASE-CHECKLIST.md", @@ -1103,7 +1108,7 @@ { "path": "docs/release/1.0-REPRODUCIBILITY.md", "bytes": 1723, - "sha256": "488b7a0c79b1554135d42f9805f58d1af8915985b88af9a28e9774e14796b758" + "sha256": "b099296e900294decc60d6b48c5ad0ff4b6d1f6a2b34181c50499573b2ce4f2d" }, { "path": "docs/release/1.0-SBOM.json", @@ -3442,8 +3447,8 @@ }, { "path": "PROJECT_STATUS.json", - "bytes": 60779, - "sha256": "2da0461472309a658fac2798db0faba3e0895ce84e499d41022fe44b39b29318" + "bytes": 60855, + "sha256": "d69f9d5cd81b825dd4421b13a48e47090ed422a84fa10746a3f965291ba2d9f2" }, { "path": "providers/AGENTS.md", @@ -3657,8 +3662,8 @@ }, { "path": "README.md", - "bytes": 14006, - "sha256": "aea69b08f5576a4586e7dd7b3713a5744ec2b299bbda93b8928b81188cd1910b" + "bytes": 14677, + "sha256": "6290d03d15a62bd121fea8007824b5c14327a6e7ce4e20f45f0d11b6f584aa23" }, { "path": "REPOSITORY_MAP.md", @@ -3752,8 +3757,8 @@ }, { "path": "scripts/consumer-browser-smoke.mjs", - "bytes": 23703, - "sha256": "27c6584db7a5234a170387769b8aa7c6d8742e87836ba4c40c911cb9b96ff4d6" + "bytes": 24218, + "sha256": "dc17608ad6af8d0c1afd4670410b6611d68dfb2c47a85917954a23fc5955f6e9" }, { "path": "scripts/consumer-smoke.mjs", @@ -4522,8 +4527,8 @@ }, { "path": "tests/usage-docs.test.mjs", - "bytes": 16402, - "sha256": "ce39f08fdfeafcc92dab38e137fda17936a0fcbcaf96a179d96a4ab5f205ae07" + "bytes": 17642, + "sha256": "b48a48ba58941a19d4fcca4cc7a7a7cc2cce3ef53d743dc7d8b0cbf7e2b7ca70" }, { "path": "tests/web-shell.test.mjs", diff --git a/apps/cli/help.mjs b/apps/cli/help.mjs new file mode 100644 index 0000000..7f74275 --- /dev/null +++ b/apps/cli/help.mjs @@ -0,0 +1,401 @@ +import path from 'node:path'; +import process from 'node:process'; + +function helpCommandName() { + if (process.env.npm_lifecycle_event === 'recall') return 'recall'; + return path.basename(process.argv[1] ?? '') === 'recall' ? 'recall' : 'oaf'; +} + +function renderHelpText(text) { + const command = helpCommandName(); + if (command === 'oaf') return text; + return text + .replace( + /\boaf (?=(status|setup|verify|doctor|connect|disconnect|task|demo|serve|check|eval|manifest|map|semantic|handoff|token-saver|context|loop|skill|measure|benchmark|bench|memory|mcp|harness|hook|version)\b)/g, + `${command} ` + ); +} + +export function printHelp(topic, subtopic) { + const topicHelp = helpTopic(topic, subtopic); + if (topicHelp) { + console.log(renderHelpText(topicHelp)); + return; + } + + console.log(renderHelpText(`Memory Recall CLI + +Usage: + oaf status + oaf setup + oaf verify + oaf doctor + oaf connect codex --dry-run --format json + oaf disconnect codex --dry-run --format json + oaf task + oaf demo [objective] + oaf demo memory-loop --root . --format json + oaf serve + oaf check + oaf eval + oaf manifest + oaf map --root . --sqlite .local/memory.sqlite --format summary + oaf semantic plan --harness codex --root . --dry-run + oaf semantic task --harness codex --root . + oaf semantic import --input semantic-result.json --root . --sqlite .local/memory.sqlite + oaf semantic run --provider gemini --allow-network --root . --sqlite .local/memory.sqlite + oaf handoff + oaf handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed-from-git --format summary + oaf token-saver + oaf token-saver --all-shards + oaf token-saver --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed-from-git --format summary + oaf context --request request.json --records records.json + oaf context profile --records memory-export.json --objective "Ship safely" --step "select compact memory" --token-budget 4096 --format json + oaf context scan --from codex --root . --dry-run + oaf context preview --from codex --root . --objective "Ship safely" --step "select context" --include-file notes/handoff.md --dry-run + oaf context pack --from codex --root . --objective "Ship safely" --step "handoff" --target codex --include-file notes/handoff.md --changed src/auth.ts --changed-from-git --dry-run --format markdown + oaf context pack --from codex --root . --objective "Ship safely" --step "handoff" --target codex --write --out context-packs/CONTEXT_PACK.md --use-out context-packs/CONTEXT_PACK.use.json --format json + oaf context pack --from codex --root . --objective "Ship safely" --step "handoff" --target codex --write --pin --out context-packs/CONTEXT_PACK.md --format json + oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --memory-config oaf.memory.json --format json + oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format summary + oaf context receive --read-only --root . --target codex --format json + oaf context receive --read-only --root . --target codex --format summary + oaf context retrieve workspace://AGENTS.md --read-only --root . --format json + oaf context retrieve workspace://AGENTS.md --read-only --root . --format summary + oaf context registry status --read-only --format json + oaf context graph preview --root . --query "approve token reset" --trace runAuthWorkflow --changed src/auth.ts --changed-from-git --dry-run --format summary + oaf graph stats --root . --format summary + oaf graph search --root . --query "route registration hooks" --format summary + oaf graph trace --root . --symbol runAuthWorkflow --direction outbound --format summary + oaf graph impact --root . --changed src/auth.ts --format summary + oaf loop plan --read-only --root . --objective "Ship safely" --stop-condition "focused tests pass" --validation "node --test tests/web-shell.test.mjs" --format json + oaf loop observe --root . --plan loop-plan.json --execute-commands --format json + oaf loop verify --root . --plan loop-plan.json --worktree ../isolated-worktree --sqlite .local/memory.sqlite --execute-commands --format json + oaf loop run --root . --plan loop-plan.json --worktree ../isolated-worktree --sqlite .local/memory.sqlite --execute-commands --format json + oaf loop schedule --read-only --root . --plan loop-plan.json --kind triage --cadence manual --format json + oaf skill catalog --read-only --root . --format json + oaf skill load-plan --read-only --root . --id skill:oaf-memory --format json + oaf skill load-plan --read-only --root . --id skill:oaf-memory --format summary + oaf measure savings --read-only --root . --objective "Ship safely" --step "measure savings" --format json + oaf measure savings --read-only --root . --objective "Ship safely" --step "measure savings" --format summary + oaf measure context-pack --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed src/auth.ts --format json + oaf measure context-pack --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed src/auth.ts --format summary + oaf benchmark truth-floor --suite benchmark-truth-floor --dataset evals/benchmark-truth-floor/cases.v1.json --format json + oaf bench sufficiency --read-only --root . --format json + oaf bench temporal --read-only --root . --format json + oaf bench session --read-only --root . --format json + oaf bench realqa --read-only --root . --format json + oaf bench locomo --read-only --root . --dataset evals/locomo/smoke.v1.json --format json + oaf memory profile --records memory-export.json --root . --dry-run --format json + oaf memory remember --root . --sqlite .local/memory.sqlite --subject auth --predicate token_expiry --object "15 minutes" --supersedes-subject auth --supersedes-predicate token_expiry --source workspace://DECISIONS.md --format json + oaf memory remember --batch facts.json --root . --sqlite .local/memory.sqlite --format json + oaf memory ingest --root . --sqlite .local/memory.sqlite --format json + oaf memory review --root . --sqlite .local/memory.sqlite --format summary + oaf memory approve mpq_status --root . --sqlite .local/memory.sqlite --format json + oaf memory approve --all-from workspace://PROJECT_STATUS.json --root . --sqlite .local/memory.sqlite --format json + oaf memory approve --all --root . --sqlite .local/memory.sqlite --format json + oaf memory reject mpq_status --root . --sqlite .local/memory.sqlite --format json + oaf memory review approve --root . --sqlite .local/memory.sqlite --proposal mpq_status --format json + oaf memory refine --read-only --root . --sqlite .local/memory.sqlite --target-active-facts 200 --format json + oaf memory refine --read-only --root . --sqlite .local/memory.sqlite --target-active-facts 200 --min-confidence 0.5 --format summary + oaf memory proposals --records memory-export.json --root . --dry-run --format json + oaf memory proposals --from memoryPaths --config oaf.memory.json --root . --dry-run --format json + oaf memory sgrep "context manifest" --records memory-export.json --workspace ws_local --dry-run --format json + oaf memory fact add --sqlite .local/memory.sqlite --workspace ws_local --scope workspace --subject project:memory-recall --predicate release_status --object release-candidate --text "Memory Recall release status is release-candidate." --source workspace://memory/status.md --proposal mpq_status --episode-id mep_status --episode-source workspace://memory/status.md --episode-summary "Reviewed status note." --format json + oaf memory fact get --sqlite .local/memory.sqlite --workspace ws_local --scope workspace --subject project:memory-recall --predicate release_status --at 2026-06-26T00:00:00.000Z --format json + oaf memory fact history --sqlite .local/memory.sqlite --workspace ws_local --scope workspace --subject project:memory-recall --predicate release_status --format json + oaf memory search "release" --sqlite .local/memory.sqlite --workspace ws_local --scope workspace --format json + oaf memory path --root . --sqlite .local/memory.sqlite --workspace ws_local --scope workspace --from project:memory-recall --to temporal-memory --max-hops 6 --format json + oaf memory explain --root . --sqlite .local/memory.sqlite --workspace ws_local --scope workspace --entity auth --depth 1 --format json + oaf mcp inspect --read-only --root . --format json + oaf mcp resources --read-only --workspace ws_local --format json + oaf mcp resources --read-only --uri oaf://workspace/ws_local/skills/catalog --format json + oaf mcp resources --read-only --uri oaf://workspace/ws_local/tools/catalog --format summary + oaf mcp resources --read-only --memory-refine --uri oaf://workspace/ws_local/memory/refine --format summary + oaf mcp resources --read-only --context-pack --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --changed-from-git --uri oaf://workspace/ws_local/context-pack/current --format json + oaf mcp resources --read-only --context-pack-use context-packs/CONTEXT_PACK.use.json --uri oaf://workspace/ws_local/context-pack/use-plan/current --format json + oaf mcp resources --read-only --context-pack-registry --uri oaf://workspace/ws_local/context-pack/registry/current --format json + oaf mcp smoke context-pack --read-only --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --changed-from-git --format json + oaf mcp resources --read-only --stdio + oaf mcp server --read-only --root . --stdio + oaf mcp stats --read-only --root . --format json + oaf mcp install --client claude-code --dry-run --format json + oaf harness setup status --client codex --dry-run --format json + oaf harness setup plan --client cursor --server oaf --dry-run --format json + oaf harness setup uninstall --client cursor --server oaf --dry-run --format json + oaf hook install --agent codex --dry-run --format json + oaf hook uninstall --agent codex --dry-run --format json + oaf hook context --read-only --format text + oaf version + +Start with oaf status; if it says Next task: none, run the First safe handoff command it prints. +Run oaf task only when npm run status names a next task. +oaf setup creates only local state in the current repository; it does not scan source files. Use oaf map for the first explicit read-only scan and oaf harness setup plan/status for dry-run wiring previews. +The default bootstrap is local-only and enables no external writes.`)); +} + +const TOPIC_HELP = new Map([ + ['setup', `Memory Recall CLI: setup + +Usage: + oaf setup + +Creates only local Recall state in the current repository. It does not scan +source files, run Recall Map, configure MCP clients, install harness servers, +activate memory, or enable external writes. + +Run the explicit first read-only map next: + oaf map --root . --sqlite .local/memory.sqlite --format summary + +Use harness setup for client wiring previews: + oaf harness setup status --client codex --dry-run --format json + oaf harness setup plan --client codex --server oaf --dry-run --format json`], + ['map', `Memory Recall CLI: map + +Usage: + oaf map --root . --sqlite .local/memory.sqlite --format summary + oaf map --root . --changed src/auth.ts --query "token reset" --format json + oaf map --root . --changed-from-git --format markdown + +Options: + --root Target repository; defaults to the current directory. + --sqlite Local SQLite memory store; defaults to .local/memory.sqlite. + --changed Add a reviewed changed workspace path; repeatable. + --changed-from-git Detect changed paths with local git only. + --query Search the bounded JS/TS source graph. + --format Emit the full safe report or a compact rendering. + +Builds a bounded local repository map from the implemented JS/TS static graph +and the governed local SQLite memory store. It does not write files, call +models, use network access, enable external adapters, or expose raw source +bodies.`], + ['semantic', `Memory Recall CLI: semantic + +Usage: + oaf semantic plan --harness codex --root . --dry-run + oaf semantic task --harness codex --root . + oaf semantic import --input semantic-result.json --root . --sqlite .local/memory.sqlite + oaf semantic run --provider gemini --allow-network --root . --sqlite .local/memory.sqlite + oaf semantic run --provider openai-compatible --endpoint https://api.example.test/v1/chat/completions --model model-id --api-key-env MODEL_API_KEY --allow-network --root . + +Plan emits a body-free JSON report and task emits only the bounded raw harness +task. Import reads one workspace-relative JSON result. Run performs exactly one +explicitly consented model request. Import and run normalize untrusted results +into pending SQLite proposals only; neither command creates active memory.`], + ['connect', `Memory Recall CLI: connect + +Usage: + oaf connect codex --dry-run --format json + oaf connect codex --yes --format json + oaf disconnect codex --dry-run --format json + +Previews or applies local harness client configuration through the governed +connection wrapper. It is dry-run by default. --yes writes only the local +harness client config for the selected agent; it does not enable external +writes, grant authority, activate memory, or call models.`], + ['disconnect', `Memory Recall CLI: disconnect + +Usage: + oaf disconnect codex --dry-run --format json + oaf disconnect codex --yes --format json + +Previews or applies removal of local OAF harness client configuration through +the governed connection wrapper. It is dry-run by default. --yes removes only +matching local harness config entries; it does not touch project state, memory, +models, or external services.`], + ['harness setup', `Memory Recall CLI: harness setup + +Usage: + oaf harness setup status --client codex --dry-run --format json + oaf harness setup plan --client cursor --server oaf --dry-run --format json + oaf harness setup uninstall --client cursor --server oaf --dry-run --format json + +Builds dry-run reports for local harness client wiring. This command is preview +only: it requires --dry-run, does not mutate home config, does not write local +files, does not grant authority, and does not enable external writes.`], + ['context', `Memory Recall CLI: context + +Usage: + oaf handoff + oaf context scan --from codex --root . --dry-run + oaf context preview --from codex --root . --objective "Ship safely" --step "select context" --include-file notes/handoff.md --dry-run + oaf context pack --from codex --root . --objective "Ship safely" --step "handoff" --target codex --include-file notes/handoff.md --changed src/auth.ts --dry-run --format json + oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format json + oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format summary + oaf context receive --read-only --root . --target codex --format json + oaf context receive --read-only --root . --target codex --format summary + oaf context retrieve workspace://AGENTS.md --read-only --root . --format summary + oaf context graph preview --root . --query "approve token reset" --trace runAuthWorkflow --changed src/auth.ts --dry-run --format summary + oaf context registry status --read-only --format json + +Context commands select local handoff context, preview harness inputs, and read +pinned context-pack state. Graph preview is dry-run only. Read-only commands do +not write files, call models, use network access, or expose raw source bodies. +Retrieve summary verifies locator/hash metadata without printing file content.`], + ['graph', `Memory Recall CLI: graph + +Usage: + oaf graph stats --root . --format summary + oaf graph search --root . --query "route registration hooks" --format summary + oaf graph trace --root . --symbol runAuthWorkflow --direction outbound --format summary + oaf graph impact --root . --changed src/auth.ts --format summary + oaf graph impact --root . --changed-from-git --format json + +Graph commands build a bounded local JS/TS source graph and return locator-only +stats, search, trace, or changed-file impact reports. They are read-only by default: +no files are written, no model calls are made, no network calls are made, and +raw source bodies are not included.`], + ['context handoff', `Memory Recall CLI: context handoff + +Usage: + oaf handoff + oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format json + oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format summary + +Options: + --from Source harness families to inspect. + --target Receiver harness. + --include-file Add reviewed workspace-relative files. + --changed Add reviewed changed files. + --changed-from-git Detect changed files with local git. + --memory-config Preflight selected memory source paths. + --format json|summary Emit the validated report or compact operator summary. + +Builds a read-only local agent handoff with context-pack proof, MCP readback, +harness setup dry-run status, and zero-tool MCP proof. It requires --read-only +and does not write files, import harness history, call models, use network +access, or expose raw source bodies.`], + ['handoff', `Memory Recall CLI: handoff + +Usage: + oaf handoff + oaf handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed-from-git --format summary + oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format json + +Runs the read-only context handoff flow. With no flags it defaults to a compact +Codex summary for the current repository and local git changes. It does not +write files, import harness history, call models, use network access, enable +external adapters, create active memory, or expose raw source bodies.`], + ['token-saver', `Memory Recall CLI: token-saver + +Usage: + oaf token-saver + oaf token-saver --all-shards + oaf token-saver --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed-from-git --format summary + oaf measure context-pack --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed src/auth.ts --format json + +Runs the read-only context-pack measurement flow. With no flags it measures the +current repository and local git changes. It does not write files, call models, +use network access, enable external adapters, include raw source bodies, or +claim provider billing-token savings.`], + ['context receive', `Memory Recall CLI: context receive + +Usage: + oaf context receive --read-only --root . --target codex --format json + oaf context receive --read-only --root . --target codex --format summary + +Reads the pinned local context-pack registry, current pointer, and use plan +without rebuilding or writing files. JSON returns the versioned receiver packet; +summary prints state, recipient proof, packet parts, required reads, and report +fingerprint. It rejects task text, write flags, MCP stdio mode, raw Markdown +bodies, source bodies, credentials, provider URLs, and absolute local paths.`], + ['context registry', `Memory Recall CLI: context registry + +Usage: + oaf context registry status --read-only --format json + +Reads the pinned local context-pack registry and verifies the current pointer, +artifact hashes, and source hashes. It requires --read-only and does not rebuild +packs, write artifacts, call models, use network access, or expose raw source +bodies.`], + ['skill', `Memory Recall CLI: skill + +Usage: + oaf skill catalog --read-only --root . --format json + oaf skill catalog --read-only --root . --format summary + oaf skill load-plan --read-only --root . --id skill:oaf-memory --format json + oaf skill load-plan --read-only --root . --id skill:oaf-memory --format summary + +Skill commands inspect local OAF skill manifests. They do not grant tool +authority or load raw skill text into the report.`], + ['skill catalog', `Memory Recall CLI: skill catalog + +Usage: + oaf skill catalog --read-only --root . --format json + oaf skill catalog --read-only --root . --format summary + +Reports side-effect classes, tool IDs, manifest fingerprints, and +catalog/report fingerprints for workspace skills. It requires --read-only and +does not include raw skill text, expose absolute filesystem paths, grant tool +authority, start MCP stdio, call models, use network access, or write local +files.`], + ['skill load-plan', `Memory Recall CLI: skill load-plan + +Usage: + oaf skill load-plan --read-only --root . --id skill:oaf-memory --format json + oaf skill load-plan --read-only --root . --id skill:oaf-memory --format summary + +Returns the ordered local reads for one skill: manifest, SKILL.md, and declared +references. It requires --read-only and does not include raw skill text, grant +tool authority, start MCP stdio, call models, use network access, or write local +files.`], + ['measure', `Memory Recall CLI: measure + +Usage: + oaf measure savings --read-only --root . --objective "Ship safely" --step "measure savings" --format json + oaf measure context-pack --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed src/auth.ts --format json + +Measure commands emit local evidence about context delivery. They do not claim +provider billing savings, call models, use network access, or perform external +writes.`], + ['measure context-pack', `Memory Recall CLI: measure context-pack + +Usage: + oaf measure context-pack --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed src/auth.ts --format json + oaf measure context-pack --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed-from-git --format summary + +Measures the same read-only context-pack path used for handoff: selected and +delivered token estimates, changed-file coverage, MCP readback, timings, and +safeguards. It requires --read-only and does not include raw source bodies, +call models, use network access, or write local files.`], + ['mcp', `Memory Recall CLI: mcp + +Usage: + oaf mcp inspect --read-only --root . --format json + oaf mcp inspect --read-only --root . --format summary + oaf mcp resources --read-only --workspace ws_local --format json + oaf mcp resources --read-only --uri oaf://workspace/ws_local/skills/catalog --format json + oaf mcp resources --read-only --uri oaf://workspace/ws_local/tools/catalog --format summary + oaf mcp resources --read-only --memory-refine --uri oaf://workspace/ws_local/memory/refine --format summary + oaf mcp resources --read-only --context-pack --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format json + oaf mcp server --read-only --root . --stdio + oaf mcp stats --read-only --root . --format json + oaf mcp smoke context-pack --read-only --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format json + oaf mcp install --client claude-code --dry-run --format json + +MCP commands inspect or expose local read-only resources, run the stdio bridge, +preview install plans, or report delivery stats. Resource summaries require +--uri and do not dump full resource bodies. Resource/server paths require +--read-only; install remains dry-run unless explicitly confirmed by the install +flow.`], + ['memory refine', `Memory Recall CLI: memory refine + +Usage: + oaf memory refine --read-only --root . --sqlite .local/memory.sqlite --format json + oaf memory refine --read-only --root . --sqlite .local/memory.sqlite --target-active-facts 200 --format json + oaf memory refine --read-only --root . --sqlite .local/memory.sqlite --target-active-facts 200 --min-confidence 0.5 --format summary + +Scans governed local memory for duplicate, conflicting, stale, and lineage +residue candidates without applying changes. It also reports ACTIVE facts below +--min-confidence, which defaults to 0.5. --target-active-facts adds a read-only +budget preflight from existing candidates only. Summary output prints counts, +budget status, safeguards, and fingerprint only. It requires +--read-only and does not create active memory, write proposals, delete facts, +call models, use network access, or expose raw private bodies. Missing or stale +SQLite memory schemas return state: "unavailable" with zero candidates.`] +]); + +function helpTopic(topic, subtopic) { + const key = [topic, subtopic].filter(Boolean).join(' '); + return TOPIC_HELP.get(key) ?? TOPIC_HELP.get(topic); +} diff --git a/apps/cli/oaf.mjs b/apps/cli/oaf.mjs index 10c7744..18902b3 100755 --- a/apps/cli/oaf.mjs +++ b/apps/cli/oaf.mjs @@ -7,6 +7,7 @@ import { tmpdir } from 'node:os'; import path from 'node:path'; import process from 'node:process'; import { fileURLToPath } from 'node:url'; +import { printHelp } from './help.mjs'; import { buildCompressedProfileContextReport, compileContext, estimateTokens } from '../../packages/context-compiler/src/index.mjs'; import { createBenchmarkDataset, runBenchmarkTruthFloor } from '../../packages/evaluation-lab/src/index.mjs'; import { @@ -198,7 +199,7 @@ function mergeDefaultArgs(defaults, overrides, valueOptions, aliases = new Map() } if (!isHelpCommand(command) && args.some(isHelpCommand)) { - help(command, args.find((value) => !isHelpCommand(value))); + printHelp(command, args.find((value) => !isHelpCommand(value))); } else if (command === 'demo' && args[0] === 'memory-loop') { await demoMemoryLoopCommand(args.slice(1)); } else if (command === 'setup') { @@ -247,13 +248,13 @@ if (!isHelpCommand(command) && args.some(isHelpCommand)) { } else if (command === 'connect' || command === 'disconnect') { await connectionCommand(command, args); } else if (isHelpCommand(command)) { - help(args[0], args[1]); + printHelp(args[0], args[1]); } else if (['version', '--version', '-v'].includes(command)) { const pkg = JSON.parse(await readFile(new URL('../../package.json', import.meta.url), 'utf8')); console.log(pkg.version); } else { console.error(`Unknown command: ${command}\n`); - help(); + printHelp(); process.exitCode = 2; } @@ -10721,401 +10722,3 @@ function runNode(nodeArgs, { cwd = PACKAGE_ROOT, env = process.env } = {}) { function isHelpCommand(value) { return ['help', '--help', '-h'].includes(value); } - -function helpCommandName() { - if (process.env.npm_lifecycle_event === 'recall') return 'recall'; - return path.basename(process.argv[1] ?? '') === 'recall' ? 'recall' : 'oaf'; -} - -function renderHelpText(text) { - const command = helpCommandName(); - if (command === 'oaf') return text; - return text - .replace( - /\boaf (?=(status|setup|verify|doctor|connect|disconnect|task|demo|serve|check|eval|manifest|map|semantic|handoff|token-saver|context|loop|skill|measure|benchmark|bench|memory|mcp|harness|hook|version)\b)/g, - `${command} ` - ); -} - -function help(topic, subtopic) { - const topicHelp = helpTopic(topic, subtopic); - if (topicHelp) { - console.log(renderHelpText(topicHelp)); - return; - } - - console.log(renderHelpText(`Memory Recall CLI - -Usage: - oaf status - oaf setup - oaf verify - oaf doctor - oaf connect codex --dry-run --format json - oaf disconnect codex --dry-run --format json - oaf task - oaf demo [objective] - oaf demo memory-loop --root . --format json - oaf serve - oaf check - oaf eval - oaf manifest - oaf map --root . --sqlite .local/memory.sqlite --format summary - oaf semantic plan --harness codex --root . --dry-run - oaf semantic task --harness codex --root . - oaf semantic import --input semantic-result.json --root . --sqlite .local/memory.sqlite - oaf semantic run --provider gemini --allow-network --root . --sqlite .local/memory.sqlite - oaf handoff - oaf handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed-from-git --format summary - oaf token-saver - oaf token-saver --all-shards - oaf token-saver --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed-from-git --format summary - oaf context --request request.json --records records.json - oaf context profile --records memory-export.json --objective "Ship safely" --step "select compact memory" --token-budget 4096 --format json - oaf context scan --from codex --root . --dry-run - oaf context preview --from codex --root . --objective "Ship safely" --step "select context" --include-file notes/handoff.md --dry-run - oaf context pack --from codex --root . --objective "Ship safely" --step "handoff" --target codex --include-file notes/handoff.md --changed src/auth.ts --changed-from-git --dry-run --format markdown - oaf context pack --from codex --root . --objective "Ship safely" --step "handoff" --target codex --write --out context-packs/CONTEXT_PACK.md --use-out context-packs/CONTEXT_PACK.use.json --format json - oaf context pack --from codex --root . --objective "Ship safely" --step "handoff" --target codex --write --pin --out context-packs/CONTEXT_PACK.md --format json - oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --memory-config oaf.memory.json --format json - oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format summary - oaf context receive --read-only --root . --target codex --format json - oaf context receive --read-only --root . --target codex --format summary - oaf context retrieve workspace://AGENTS.md --read-only --root . --format json - oaf context retrieve workspace://AGENTS.md --read-only --root . --format summary - oaf context registry status --read-only --format json - oaf context graph preview --root . --query "approve token reset" --trace runAuthWorkflow --changed src/auth.ts --changed-from-git --dry-run --format summary - oaf graph stats --root . --format summary - oaf graph search --root . --query "route registration hooks" --format summary - oaf graph trace --root . --symbol runAuthWorkflow --direction outbound --format summary - oaf graph impact --root . --changed src/auth.ts --format summary - oaf loop plan --read-only --root . --objective "Ship safely" --stop-condition "focused tests pass" --validation "node --test tests/web-shell.test.mjs" --format json - oaf loop observe --root . --plan loop-plan.json --execute-commands --format json - oaf loop verify --root . --plan loop-plan.json --worktree ../isolated-worktree --sqlite .local/memory.sqlite --execute-commands --format json - oaf loop run --root . --plan loop-plan.json --worktree ../isolated-worktree --sqlite .local/memory.sqlite --execute-commands --format json - oaf loop schedule --read-only --root . --plan loop-plan.json --kind triage --cadence manual --format json - oaf skill catalog --read-only --root . --format json - oaf skill load-plan --read-only --root . --id skill:oaf-memory --format json - oaf skill load-plan --read-only --root . --id skill:oaf-memory --format summary - oaf measure savings --read-only --root . --objective "Ship safely" --step "measure savings" --format json - oaf measure savings --read-only --root . --objective "Ship safely" --step "measure savings" --format summary - oaf measure context-pack --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed src/auth.ts --format json - oaf measure context-pack --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed src/auth.ts --format summary - oaf benchmark truth-floor --suite benchmark-truth-floor --dataset evals/benchmark-truth-floor/cases.v1.json --format json - oaf bench sufficiency --read-only --root . --format json - oaf bench temporal --read-only --root . --format json - oaf bench session --read-only --root . --format json - oaf bench realqa --read-only --root . --format json - oaf bench locomo --read-only --root . --dataset evals/locomo/smoke.v1.json --format json - oaf memory profile --records memory-export.json --root . --dry-run --format json - oaf memory remember --root . --sqlite .local/memory.sqlite --subject auth --predicate token_expiry --object "15 minutes" --supersedes-subject auth --supersedes-predicate token_expiry --source workspace://DECISIONS.md --format json - oaf memory remember --batch facts.json --root . --sqlite .local/memory.sqlite --format json - oaf memory ingest --root . --sqlite .local/memory.sqlite --format json - oaf memory review --root . --sqlite .local/memory.sqlite --format summary - oaf memory approve mpq_status --root . --sqlite .local/memory.sqlite --format json - oaf memory approve --all-from workspace://PROJECT_STATUS.json --root . --sqlite .local/memory.sqlite --format json - oaf memory approve --all --root . --sqlite .local/memory.sqlite --format json - oaf memory reject mpq_status --root . --sqlite .local/memory.sqlite --format json - oaf memory review approve --root . --sqlite .local/memory.sqlite --proposal mpq_status --format json - oaf memory refine --read-only --root . --sqlite .local/memory.sqlite --target-active-facts 200 --format json - oaf memory refine --read-only --root . --sqlite .local/memory.sqlite --target-active-facts 200 --min-confidence 0.5 --format summary - oaf memory proposals --records memory-export.json --root . --dry-run --format json - oaf memory proposals --from memoryPaths --config oaf.memory.json --root . --dry-run --format json - oaf memory sgrep "context manifest" --records memory-export.json --workspace ws_local --dry-run --format json - oaf memory fact add --sqlite .local/memory.sqlite --workspace ws_local --scope workspace --subject project:memory-recall --predicate release_status --object release-candidate --text "Memory Recall release status is release-candidate." --source workspace://memory/status.md --proposal mpq_status --episode-id mep_status --episode-source workspace://memory/status.md --episode-summary "Reviewed status note." --format json - oaf memory fact get --sqlite .local/memory.sqlite --workspace ws_local --scope workspace --subject project:memory-recall --predicate release_status --at 2026-06-26T00:00:00.000Z --format json - oaf memory fact history --sqlite .local/memory.sqlite --workspace ws_local --scope workspace --subject project:memory-recall --predicate release_status --format json - oaf memory search "release" --sqlite .local/memory.sqlite --workspace ws_local --scope workspace --format json - oaf memory path --root . --sqlite .local/memory.sqlite --workspace ws_local --scope workspace --from project:memory-recall --to temporal-memory --max-hops 6 --format json - oaf memory explain --root . --sqlite .local/memory.sqlite --workspace ws_local --scope workspace --entity auth --depth 1 --format json - oaf mcp inspect --read-only --root . --format json - oaf mcp resources --read-only --workspace ws_local --format json - oaf mcp resources --read-only --uri oaf://workspace/ws_local/skills/catalog --format json - oaf mcp resources --read-only --uri oaf://workspace/ws_local/tools/catalog --format summary - oaf mcp resources --read-only --memory-refine --uri oaf://workspace/ws_local/memory/refine --format summary - oaf mcp resources --read-only --context-pack --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --changed-from-git --uri oaf://workspace/ws_local/context-pack/current --format json - oaf mcp resources --read-only --context-pack-use context-packs/CONTEXT_PACK.use.json --uri oaf://workspace/ws_local/context-pack/use-plan/current --format json - oaf mcp resources --read-only --context-pack-registry --uri oaf://workspace/ws_local/context-pack/registry/current --format json - oaf mcp smoke context-pack --read-only --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --changed-from-git --format json - oaf mcp resources --read-only --stdio - oaf mcp server --read-only --root . --stdio - oaf mcp stats --read-only --root . --format json - oaf mcp install --client claude-code --dry-run --format json - oaf harness setup status --client codex --dry-run --format json - oaf harness setup plan --client cursor --server oaf --dry-run --format json - oaf harness setup uninstall --client cursor --server oaf --dry-run --format json - oaf hook install --agent codex --dry-run --format json - oaf hook uninstall --agent codex --dry-run --format json - oaf hook context --read-only --format text - oaf version - -Start with oaf status; if it says Next task: none, run the First safe handoff command it prints. -Run oaf task only when npm run status names a next task. -oaf setup creates only local state in the current repository; it does not scan source files. Use oaf map for the first explicit read-only scan and oaf harness setup plan/status for dry-run wiring previews. -The default bootstrap is local-only and enables no external writes.`)); -} - -function helpTopic(topic, subtopic) { - const key = [topic, subtopic].filter(Boolean).join(' '); - const topics = new Map([ - ['setup', `Memory Recall CLI: setup - -Usage: - oaf setup - -Creates only local Recall state in the current repository. It does not scan -source files, run Recall Map, configure MCP clients, install harness servers, -activate memory, or enable external writes. - -Run the explicit first read-only map next: - oaf map --root . --sqlite .local/memory.sqlite --format summary - -Use harness setup for client wiring previews: - oaf harness setup status --client codex --dry-run --format json - oaf harness setup plan --client codex --server oaf --dry-run --format json`], - ['map', `Memory Recall CLI: map - -Usage: - oaf map --root . --sqlite .local/memory.sqlite --format summary - oaf map --root . --changed src/auth.ts --query "token reset" --format json - oaf map --root . --changed-from-git --format markdown - -Options: - --root Target repository; defaults to the current directory. - --sqlite Local SQLite memory store; defaults to .local/memory.sqlite. - --changed Add a reviewed changed workspace path; repeatable. - --changed-from-git Detect changed paths with local git only. - --query Search the bounded JS/TS source graph. - --format Emit the full safe report or a compact rendering. - -Builds a bounded local repository map from the implemented JS/TS static graph -and the governed local SQLite memory store. It does not write files, call -models, use network access, enable external adapters, or expose raw source -bodies.`], - ['semantic', `Memory Recall CLI: semantic - -Usage: - oaf semantic plan --harness codex --root . --dry-run - oaf semantic task --harness codex --root . - oaf semantic import --input semantic-result.json --root . --sqlite .local/memory.sqlite - oaf semantic run --provider gemini --allow-network --root . --sqlite .local/memory.sqlite - oaf semantic run --provider openai-compatible --endpoint https://api.example.test/v1/chat/completions --model model-id --api-key-env MODEL_API_KEY --allow-network --root . - -Plan emits a body-free JSON report and task emits only the bounded raw harness -task. Import reads one workspace-relative JSON result. Run performs exactly one -explicitly consented model request. Import and run normalize untrusted results -into pending SQLite proposals only; neither command creates active memory.`], - ['connect', `Memory Recall CLI: connect - -Usage: - oaf connect codex --dry-run --format json - oaf connect codex --yes --format json - oaf disconnect codex --dry-run --format json - -Previews or applies local harness client configuration through the governed -connection wrapper. It is dry-run by default. --yes writes only the local -harness client config for the selected agent; it does not enable external -writes, grant authority, activate memory, or call models.`], - ['disconnect', `Memory Recall CLI: disconnect - -Usage: - oaf disconnect codex --dry-run --format json - oaf disconnect codex --yes --format json - -Previews or applies removal of local OAF harness client configuration through -the governed connection wrapper. It is dry-run by default. --yes removes only -matching local harness config entries; it does not touch project state, memory, -models, or external services.`], - ['harness setup', `Memory Recall CLI: harness setup - -Usage: - oaf harness setup status --client codex --dry-run --format json - oaf harness setup plan --client cursor --server oaf --dry-run --format json - oaf harness setup uninstall --client cursor --server oaf --dry-run --format json - -Builds dry-run reports for local harness client wiring. This command is preview -only: it requires --dry-run, does not mutate home config, does not write local -files, does not grant authority, and does not enable external writes.`], - ['context', `Memory Recall CLI: context - -Usage: - oaf handoff - oaf context scan --from codex --root . --dry-run - oaf context preview --from codex --root . --objective "Ship safely" --step "select context" --include-file notes/handoff.md --dry-run - oaf context pack --from codex --root . --objective "Ship safely" --step "handoff" --target codex --include-file notes/handoff.md --changed src/auth.ts --dry-run --format json - oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format json - oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format summary - oaf context receive --read-only --root . --target codex --format json - oaf context receive --read-only --root . --target codex --format summary - oaf context retrieve workspace://AGENTS.md --read-only --root . --format summary - oaf context graph preview --root . --query "approve token reset" --trace runAuthWorkflow --changed src/auth.ts --dry-run --format summary - oaf context registry status --read-only --format json - -Context commands select local handoff context, preview harness inputs, and read -pinned context-pack state. Graph preview is dry-run only. Read-only commands do -not write files, call models, use network access, or expose raw source bodies. -Retrieve summary verifies locator/hash metadata without printing file content.`], - ['graph', `Memory Recall CLI: graph - -Usage: - oaf graph stats --root . --format summary - oaf graph search --root . --query "route registration hooks" --format summary - oaf graph trace --root . --symbol runAuthWorkflow --direction outbound --format summary - oaf graph impact --root . --changed src/auth.ts --format summary - oaf graph impact --root . --changed-from-git --format json - -Graph commands build a bounded local JS/TS source graph and return locator-only -stats, search, trace, or changed-file impact reports. They are read-only by default: -no files are written, no model calls are made, no network calls are made, and -raw source bodies are not included.`], - ['context handoff', `Memory Recall CLI: context handoff - -Usage: - oaf handoff - oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format json - oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format summary - -Options: - --from Source harness families to inspect. - --target Receiver harness. - --include-file Add reviewed workspace-relative files. - --changed Add reviewed changed files. - --changed-from-git Detect changed files with local git. - --memory-config Preflight selected memory source paths. - --format json|summary Emit the validated report or compact operator summary. - -Builds a read-only local agent handoff with context-pack proof, MCP readback, -harness setup dry-run status, and zero-tool MCP proof. It requires --read-only -and does not write files, import harness history, call models, use network -access, or expose raw source bodies.`], - ['handoff', `Memory Recall CLI: handoff - -Usage: - oaf handoff - oaf handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed-from-git --format summary - oaf context handoff --read-only --from codex --root . --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format json - -Runs the read-only context handoff flow. With no flags it defaults to a compact -Codex summary for the current repository and local git changes. It does not -write files, import harness history, call models, use network access, enable -external adapters, create active memory, or expose raw source bodies.`], - ['token-saver', `Memory Recall CLI: token-saver - -Usage: - oaf token-saver - oaf token-saver --all-shards - oaf token-saver --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed-from-git --format summary - oaf measure context-pack --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed src/auth.ts --format json - -Runs the read-only context-pack measurement flow. With no flags it measures the -current repository and local git changes. It does not write files, call models, -use network access, enable external adapters, include raw source bodies, or -claim provider billing-token savings.`], - ['context receive', `Memory Recall CLI: context receive - -Usage: - oaf context receive --read-only --root . --target codex --format json - oaf context receive --read-only --root . --target codex --format summary - -Reads the pinned local context-pack registry, current pointer, and use plan -without rebuilding or writing files. JSON returns the versioned receiver packet; -summary prints state, recipient proof, packet parts, required reads, and report -fingerprint. It rejects task text, write flags, MCP stdio mode, raw Markdown -bodies, source bodies, credentials, provider URLs, and absolute local paths.`], - ['context registry', `Memory Recall CLI: context registry - -Usage: - oaf context registry status --read-only --format json - -Reads the pinned local context-pack registry and verifies the current pointer, -artifact hashes, and source hashes. It requires --read-only and does not rebuild -packs, write artifacts, call models, use network access, or expose raw source -bodies.`], - ['skill', `Memory Recall CLI: skill - -Usage: - oaf skill catalog --read-only --root . --format json - oaf skill catalog --read-only --root . --format summary - oaf skill load-plan --read-only --root . --id skill:oaf-memory --format json - oaf skill load-plan --read-only --root . --id skill:oaf-memory --format summary - -Skill commands inspect local OAF skill manifests. They do not grant tool -authority or load raw skill text into the report.`], - ['skill catalog', `Memory Recall CLI: skill catalog - -Usage: - oaf skill catalog --read-only --root . --format json - oaf skill catalog --read-only --root . --format summary - -Reports side-effect classes, tool IDs, manifest fingerprints, and -catalog/report fingerprints for workspace skills. It requires --read-only and -does not include raw skill text, expose absolute filesystem paths, grant tool -authority, start MCP stdio, call models, use network access, or write local -files.`], - ['skill load-plan', `Memory Recall CLI: skill load-plan - -Usage: - oaf skill load-plan --read-only --root . --id skill:oaf-memory --format json - oaf skill load-plan --read-only --root . --id skill:oaf-memory --format summary - -Returns the ordered local reads for one skill: manifest, SKILL.md, and declared -references. It requires --read-only and does not include raw skill text, grant -tool authority, start MCP stdio, call models, use network access, or write local -files.`], - ['measure', `Memory Recall CLI: measure - -Usage: - oaf measure savings --read-only --root . --objective "Ship safely" --step "measure savings" --format json - oaf measure context-pack --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed src/auth.ts --format json - -Measure commands emit local evidence about context delivery. They do not claim -provider billing savings, call models, use network access, or perform external -writes.`], - ['measure context-pack', `Memory Recall CLI: measure context-pack - -Usage: - oaf measure context-pack --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed src/auth.ts --format json - oaf measure context-pack --read-only --root . --from codex --objective "Ship safely" --step "impact brief" --target codex --changed-from-git --format summary - -Measures the same read-only context-pack path used for handoff: selected and -delivered token estimates, changed-file coverage, MCP readback, timings, and -safeguards. It requires --read-only and does not include raw source bodies, -call models, use network access, or write local files.`], - ['mcp', `Memory Recall CLI: mcp - -Usage: - oaf mcp inspect --read-only --root . --format json - oaf mcp inspect --read-only --root . --format summary - oaf mcp resources --read-only --workspace ws_local --format json - oaf mcp resources --read-only --uri oaf://workspace/ws_local/skills/catalog --format json - oaf mcp resources --read-only --uri oaf://workspace/ws_local/tools/catalog --format summary - oaf mcp resources --read-only --memory-refine --uri oaf://workspace/ws_local/memory/refine --format summary - oaf mcp resources --read-only --context-pack --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format json - oaf mcp server --read-only --root . --stdio - oaf mcp stats --read-only --root . --format json - oaf mcp smoke context-pack --read-only --objective "Ship safely" --step "handoff" --target codex --changed src/auth.ts --format json - oaf mcp install --client claude-code --dry-run --format json - -MCP commands inspect or expose local read-only resources, run the stdio bridge, -preview install plans, or report delivery stats. Resource summaries require ---uri and do not dump full resource bodies. Resource/server paths require ---read-only; install remains dry-run unless explicitly confirmed by the install -flow.`], - ['memory refine', `Memory Recall CLI: memory refine - -Usage: - oaf memory refine --read-only --root . --sqlite .local/memory.sqlite --format json - oaf memory refine --read-only --root . --sqlite .local/memory.sqlite --target-active-facts 200 --format json - oaf memory refine --read-only --root . --sqlite .local/memory.sqlite --target-active-facts 200 --min-confidence 0.5 --format summary - -Scans governed local memory for duplicate, conflicting, stale, and lineage -residue candidates without applying changes. It also reports ACTIVE facts below ---min-confidence, which defaults to 0.5. --target-active-facts adds a read-only -budget preflight from existing candidates only. Summary output prints counts, -budget status, safeguards, and fingerprint only. It requires ---read-only and does not create active memory, write proposals, delete facts, -call models, use network access, or expose raw private bodies. Missing or stale -SQLite memory schemas return state: "unavailable" with zero candidates.`] - ]); - return topics.get(key) ?? topics.get(topic); -} diff --git a/docs/release/1.0-PROVENANCE.json b/docs/release/1.0-PROVENANCE.json index ebf4e9e..8bfdaf4 100644 --- a/docs/release/1.0-PROVENANCE.json +++ b/docs/release/1.0-PROVENANCE.json @@ -23,7 +23,7 @@ "sourceHashes": { "package.json": "sha256:7571776a443d6c4e5d91a824c8056b23c20d6378b8b194a316bd206a4b208359", "package-lock.json": "sha256:66bac759b6c28f95c29eca52c0b42e9bb24237a4a926fb67a42093f9ee425ed7", - "PROJECT_STATUS.json": "sha256:2da0461472309a658fac2798db0faba3e0895ce84e499d41022fe44b39b29318", + "PROJECT_STATUS.json": "sha256:d69f9d5cd81b825dd4421b13a48e47090ed422a84fa10746a3f965291ba2d9f2", "planning/backlog.json": "sha256:a404e5704ba3bf3be635a655d2d73d84eff7eba3ce43ab511b83967cceab6a5f", "adapters/catalog.json": "sha256:11c22a150f847a560be3e64c8280c7757368d813b5f70304938ab7915694c283", "docs/usage/support-matrix.md": "sha256:dd4108828b742e8d06112e6abdfa4119f90a8b034b417b9e7e41f6924dcf26a6", diff --git a/docs/release/1.0-READINESS-REPORT.md b/docs/release/1.0-READINESS-REPORT.md index a66e64a..c715b0f 100644 --- a/docs/release/1.0-READINESS-REPORT.md +++ b/docs/release/1.0-READINESS-REPORT.md @@ -24,7 +24,7 @@ Publication state: npm-published. This evidence is prepared for a maintainer mer | External writes | false | | Model mode | deterministic | | Quality snapshot date | 2026-07-15 | -| Recorded tests | 659 | +| Recorded tests | 660 | | Recorded protocol fixtures | 182 | | Recorded evaluation assertions | 144 | | Quality snapshot note | Counts are a dated snapshot; command results and HANDOFF_VERIFICATION.json are authoritative. | diff --git a/docs/release/1.0-REPRODUCIBILITY.md b/docs/release/1.0-REPRODUCIBILITY.md index ae0e615..38a856f 100644 --- a/docs/release/1.0-REPRODUCIBILITY.md +++ b/docs/release/1.0-REPRODUCIBILITY.md @@ -24,7 +24,7 @@ Counts are a dated snapshot; command results and HANDOFF_VERIFICATION.json are a | Gate | Expected Count | | --- | --- | -| Tests | 659 | +| Tests | 660 | | Protocol fixtures | 182 | | Evaluation assertions | 144 | diff --git a/scripts/consumer-browser-smoke.mjs b/scripts/consumer-browser-smoke.mjs index fcccfe3..cb72fad 100644 --- a/scripts/consumer-browser-smoke.mjs +++ b/scripts/consumer-browser-smoke.mjs @@ -270,6 +270,15 @@ try { await page.locator('#memory-intake-form button[value="preview"]').click(); await waitForText(page, '1 proposal'); await waitForText(page, '0 active memory created'); + page.once('dialog', (dialog) => dialog.accept()); + await page.locator('#memory-intake-form button[value="queue"]').click(); + await waitForText(page, 'Memory proposals queued for approval.'); + const approveProposal = page.locator('[data-action="approve-memory-proposal"]').first(); + await approveProposal.waitFor(); + page.once('dialog', (dialog) => dialog.accept()); + await approveProposal.click(); + await waitForText(page, 'Memory proposal approved.'); + await waitForText(page, 'consumer_browser_smoke'); await page.goto(`${base}/memory-graph`, { waitUntil: 'domcontentloaded' }); await waitForText(page, 'Governed knowledge graph'); diff --git a/tests/usage-docs.test.mjs b/tests/usage-docs.test.mjs index cb40c98..e70371f 100644 --- a/tests/usage-docs.test.mjs +++ b/tests/usage-docs.test.mjs @@ -6,6 +6,18 @@ function read(path) { return readFileSync(path, 'utf8'); } +test('README and status separate the source candidate from the published package', () => { + const readme = read('README.md'); + const status = JSON.parse(read('PROJECT_STATUS.json')); + const release = status.capabilities.find((capability) => capability.id === 'release.readiness'); + const web = status.capabilities.find((capability) => capability.id === 'bootstrap.web'); + + assert.match(readme, /current source checkout is the 1\.1\.0 release candidate\. npm still serves\s+1\.0\.5, which does not include Recall Map/); + assert.match(readme, /npm run recall -- setup\nnpm run recall -- map --root \. --sqlite \.local\/memory\.sqlite --format summary\nnpm run recall -- handoff/); + assert.match(release.limitations.join('\n'), /1\.0\.5 is published; the 1\.1\.0 source release candidate on main is not yet published/); + assert.match(web.limitations.join('\n'), /confirm-gated proposal approval through the authenticated loopback API/); +}); + test('semantic setup docs and status describe only the governed implemented path', () => { assert.equal(existsSync('docs/usage/semantic-setup.md'), true); const semantic = read('docs/usage/semantic-setup.md'); @@ -96,7 +108,9 @@ test('public usage docs avoid stale task and missing context-file examples while assert.match(contract, /Implemented: local JS\/TS static graph, reviewed SQLite memory, read-only MCP\./); assert.match(contract, /Experimental: Rust acceleration paths require a local build before explicit invocation\./); assert.match(contract, /Unsupported: automatic transcript capture, write-capable MCP, hosted sync, and non-JS\/TS source graph analysis\./); - assert.match(readme, /recall setup\nrecall map --root \. --sqlite \.local\/memory\.sqlite --format summary\nrecall handoff/); + assert.match(readme, /npm run recall -- setup\nnpm run recall -- map --root \. --sqlite \.local\/memory\.sqlite --format summary\nnpm run recall -- handoff/); + assert.match(readme, /current source checkout is the 1\.1\.0 release candidate\. npm still serves\s+1\.0\.5, which does not include Recall Map/); + assert.match(readme, /Source release candidate: \*\*1\.1\.0\*\*\. Published npm version: \*\*1\.0\.5\*\*\./); assert.match(readme, /`recall setup` creates only local state\. `recall map` is the explicit first\s+read-only repository scan; it does not run silently during setup\./); assert.match(normalHandoff, /recall setup\nrecall map --root \. --sqlite \.local\/memory\.sqlite --format summary\nrecall handoff/); assert.match(normalHandoff, /`recall setup` creates only local Recall state in the current repository; it\s+does not scan source files\. `recall map` is the explicit first read-only scan\./);