From 00045a532b9d06b5a462859084fc8b26c7f17bea Mon Sep 17 00:00:00 2001 From: seathatflowsinourveins <234074349+seathatflowsinourveins@users.noreply.github.com> Date: Sun, 20 Sep 2026 14:26:34 -0400 Subject: [PATCH 01/15] Add scoped FOUNDATION capability catalog and validator --- catalogs/foundation/README.md | 96 ++ catalogs/foundation/decisions.json | 2178 ++++++++++++++++++++++++++++ catalogs/foundation/manifest.json | 244 ++++ scripts/validate_foundation.py | 257 ++++ tests/test_foundation_catalog.py | 200 +++ 5 files changed, 2975 insertions(+) create mode 100644 catalogs/foundation/README.md create mode 100644 catalogs/foundation/decisions.json create mode 100644 catalogs/foundation/manifest.json create mode 100644 scripts/validate_foundation.py create mode 100644 tests/test_foundation_catalog.py diff --git a/catalogs/foundation/README.md b/catalogs/foundation/README.md new file mode 100644 index 000000000..e0b63b635 --- /dev/null +++ b/catalogs/foundation/README.md @@ -0,0 +1,96 @@ +# FOUNDATION capability catalog + +FOUNDATION selects the general native workflow: clients, skills, owned workers, +source retrieval, memory, research, quality, applications, observation and recovery. +Start with the layer needed for the task in [manifest.json](manifest.json), then +read its scoped capability decision in [decisions.json](decisions.json). A default +is a selected way to do a task, not permission to install or activate every tool. + +The catalog references 60 selected components through 39 capability decisions, +plus one separate Tavily integration candidate. It cites 63 relevant registered +receipts from the current 88-receipt inventory. These are coverage counts, not a +score of complete installation, execution or lifecycle acceptance. + +| Layer | Purpose | +| --- | --- | +| Native clients | Signed-in native coding/research tasks and actual process activation | +| Instructions and skills | Short project rules and task-specific procedures | +| Workers | Bounded delegation, owned paths and independent acceptance | +| Isolation | Worktree ownership and selected enforced OS restrictions | +| Code navigation | Exact symbols, structural patterns and scoped source retrieval | +| Document retrieval | Named lexical corpora and supported document ingestion | +| Semantic RAG | Project-scoped conceptual code retrieval and local embeddings | +| Durable memory | Approved cross-client decisions, continuity and scoped restore | +| Web research | Selected browser, literature and current-source operations | +| Token efficiency | Adequate context representations and honest usage accounting | +| Quality and evaluation | Behavioral oracles, negative cases and independent review | +| CI and supply chain | Publication checks, security controls and dependency identity | +| Scheduling and supervision | Owned process deadlines and checkpointed job continuation | +| Hosting and services | Typed local applications, databases and selected MCP services | +| Recovery and portability | Exact restore inputs, session continuity and lifecycle limits | +| Observation and inference | Bounded telemetry, usage and optional inference trials | + +Each layer records its purpose, selected approach, activation condition, lifecycle +scope and next actionable gap. Decisions join actual `component_ids` and +`evidence_ids`; they retain an explicit `evidence_scope`, limitations and activation +rule. `accepted_within_scope` describes the named capability only. Partial, +source-review and pending decisions remain distinguishable from acceptance. + +Pins remain in [the stack manifest](../../manifests/stack.json). Original receipt +claims, evidence classes, paths and limitations remain in +[the evidence manifest](../../manifests/evidence.json). Lifecycle `stage_refs` point +to the exact status in [the component matrix](../../blueprints/token-native-focus/saturation-audit.json); +they do not duplicate its commands, stage scope or receipt content. Read those +canonical details before reusing acceptance. Unlisted stages and the explicit +`lifecycle.unknown` field do not become successful by implication. + +The [broad decision index](../us-equities/decision-index.json) remains the shared +research inventory at its existing path. Discovery lists, candidates and older +[foundation/memory](../us-equities/foundation-memory.json) or +[agent/operations](../us-equities/agents-operations.json) source reviews remain +available. Their directory placement and reviewed source pins do not supersede +the currently selected component pin or qualify an entire repository. + +The manifest explicitly leaves LEAN, Alpaca, skfolio, EdgarTools and the currently +financial-only DuckDB/pandas claims in the [US-equities domain](../us-equities/README.md). +Some domain-located fixtures demonstrate reusable operations such as process-tree +termination, dependency inventory or state restore. A FOUNDATION decision cites +only that operation; it does not import strategy, market-data, broker or trading +acceptance. The Tavily entry references its +[existing source/integration receipt](../../docs/ecosystem/tavily-receipt.json) +and leaves current intended-host native CLI integration pending reconciliation. +It does not erase earlier dated observations or create an adopted component. + +The three current priorities are: + +1. Keep general capabilities and financial-domain decisions separate, with + explicit claim scope. This catalog addresses that structure; maintain the + references when evidence changes rather than migrating the broad inventory. +2. Qualify cancellation, abrupt crash and resume of an owned writing worker. + Existing local termination, individual session resume and checkpointed jobs + remain useful narrower results. +3. Qualify independent off-host restore with separately available key recovery, + and scheduled-service acceptance after reboot. Same-host restore and ordinary + stop/start do not close these gaps. + +Use [the convergence guide](../../docs/convergence-architecture.md) for the work +sequence and [the lifecycle guide](../../adoption/lifecycle.md) for selected native +operations. Keep failed attempts, unknown usage and new-host limits intact. +The newer vLLM startup failure, failed gateway inference/compression attempts, +unverified live HUD and TOON expansion remain counterexamples, not successes. + +Validate references without installing tools, calling providers or replaying +native acceptance: + +```sh +python3 scripts/validate_foundation.py --root . --json +python3 -m unittest tests.test_foundation_catalog +``` + +The validator checks the 16 layers, unique identities, component/evidence joins, +source paths, explicit scope/limitations, canonical lifecycle statuses, candidate +separation and scoped supersession. It rejects copied pin/receipt fields. A later +decision may supersede only an earlier decision for the same capability and +component scope, retaining the old record with a reason and scope. Structural +validation cannot certify the truth or adequacy of a prose claim; review the cited +receipt and its limitations before changing an adoption decision. diff --git a/catalogs/foundation/decisions.json b/catalogs/foundation/decisions.json new file mode 100644 index 000000000..47072c41b --- /dev/null +++ b/catalogs/foundation/decisions.json @@ -0,0 +1,2178 @@ +{ + "schema_version": 1, + "checked_at": "2026-09-20", + "scope": "Capability-specific general FOUNDATION selection; original pins, full receipt claims and per-component lifecycle stages remain canonical. Shared research and financial examples are not blanket adoption.", + "decisions": [ + { + "id": "native-source-tasks", + "capability": "Use native client tools to retrieve exact project evidence", + "capability_key": "native-source-tasks", + "checked_at": "2026-09-20", + "layer_ids": [ + "native-clients" + ], + "selection": "default", + "review_status": "accepted_within_scope", + "activation": "Use the native client and selected project tools for an actual coding or research task.", + "component_ids": [ + "codex", + "claude-code" + ], + "candidate": null, + "evidence_ids": [ + "foundation-native-20260920", + "native-token-focus-clients-20260920", + "native-token-stack-final-20260920" + ], + "evidence_scope": "Both signed-in native clients completed the bounded source-retrieval tasks; the final receipt also retains scoped continuation and observation results.", + "limitations": [ + "Earlier refused MCP calls, Claude format failures and source-host account limits remain recorded.", + "Successful retrieval does not qualify every installed tool, all prompts, another PC or complete causal token savings." + ], + "source_paths": [ + "docs/foundation-stack.md", + "blueprints/convergence-practice/README.md" + ], + "next_gap": "Verify changed native process/tool activation on the intended host; retain failed attempts.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Both signed-in native clients completed the bounded source-retrieval tasks; the final receipt also retains scoped continuation and observation results.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Verify changed native process/tool activation on the intended host; retain failed attempts.", + "stage_refs": [ + { + "component_id": "codex", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "claude-code", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "native-process-defaults", + "capability": "Resolve persistent native command and MCP environments", + "capability_key": "native-process-defaults", + "checked_at": "2026-09-20", + "layer_ids": [ + "native-clients", + "instructions-skills" + ], + "selection": "default", + "review_status": "accepted_within_scope", + "activation": "Reuse accepted persistent settings and inspect a fresh native process when environment inputs change.", + "component_ids": [ + "codex", + "claude-code", + "context-mode", + "rtk", + "qmd", + "ai-memory" + ], + "candidate": null, + "evidence_ids": [ + "codex-session-environment-20260920", + "codex-desktop-live-20260920", + "native-session-defaults-20260920" + ], + "evidence_scope": "Fresh native processes resolved selected commands/MCP servers and Claude startup hooks; restarted Desktop source retrieval has its own dated receipt.", + "limitations": [ + "Configuration presence does not prove an already-running task hot-reloaded it.", + "The Linux/WSL and Desktop process/configuration boundaries remain distinct." + ], + "source_paths": [ + "docs/convergence-architecture.md" + ], + "next_gap": "Collect the specific new-host or changed-session activation evidence; do not copy account stores.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Fresh native processes resolved selected commands/MCP servers and Claude startup hooks; restarted Desktop source retrieval has its own dated receipt.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Collect the specific new-host or changed-session activation evidence; do not copy account stores.", + "stage_refs": [ + { + "component_id": "codex", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "claude-code", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "context-mode", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "rtk", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "qmd", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "ai-memory", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "on-demand-guidance", + "capability": "Load selected community procedures only for the current operation", + "capability_key": "on-demand-guidance", + "checked_at": "2026-09-20", + "layer_ids": [ + "instructions-skills" + ], + "selection": "optional", + "review_status": "source_review", + "activation": "Load the named skill only when its procedure helps the authorized task.", + "component_ids": [ + "affaan-m/ECC", + "davila7/claude-code-templates", + "shanraisshan/claude-code-best-practice" + ], + "candidate": null, + "evidence_ids": [ + "component-history", + "token-practice-coverage-20260920" + ], + "evidence_scope": "Selected guidance/source records are retained; they have no executable installation or process lifecycle.", + "limitations": [ + "Source selection is not execution acceptance and does not activate a complete skills catalog." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Review a newly selected skill against current project rules before activation.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Selected guidance/source records are retained; they have no executable installation or process lifecycle.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Review a newly selected skill against current project rules before activation.", + "stage_refs": [ + { + "component_id": "affaan-m/ECC", + "stage": "use", + "status": "not_applicable" + }, + { + "component_id": "davila7/claude-code-templates", + "stage": "use", + "status": "not_applicable" + }, + { + "component_id": "shanraisshan/claude-code-best-practice", + "stage": "use", + "status": "not_applicable" + } + ] + }, + "supersedes": [] + }, + { + "id": "portable-skill-reference", + "capability": "Validate and render a selected portable skill", + "capability_key": "portable-skill-reference", + "checked_at": "2026-09-20", + "layer_ids": [ + "instructions-skills", + "quality-evaluation" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Run the reference validator for a portable-format compatibility question.", + "component_ids": [ + "skills-ref" + ], + "candidate": null, + "evidence_ids": [ + "upstream-native-tools-20260920" + ], + "evidence_scope": "The native reference validator accepted and rendered one selected skill.", + "limitations": [ + "The reference format does not define every Codex or Claude extension." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Check client discovery/extension behavior separately on the target client.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. The native reference validator accepted and rendered one selected skill.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Check client discovery/extension behavior separately on the target client.", + "stage_refs": [ + { + "component_id": "skills-ref", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "owned-native-child", + "capability": "Implement a bounded repair through an owned native child", + "capability_key": "owned-native-child", + "checked_at": "2026-09-20", + "layer_ids": [ + "workers" + ], + "selection": "default", + "review_status": "accepted_within_scope", + "activation": "Dispatch independent bounded work with base commit, owned paths and acceptance; the coordinator integrates.", + "component_ids": [ + "claude-code" + ], + "candidate": null, + "evidence_ids": [ + "native-claude-child-patch-20260920" + ], + "evidence_scope": "One foreground native Opus child repaired the owned file; twelve frozen tests and independent exhaustive checks passed.", + "limitations": [ + "One successful child task does not establish arbitrary delegation quality, crash recovery or total workflow efficiency." + ], + "source_paths": [ + "blueprints/convergence-practice/native-worker/README.md" + ], + "next_gap": "Exercise abrupt worker failure and effect-aware same-task resume.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. One foreground native Opus child repaired the owned file; twelve frozen tests and independent exhaustive checks passed.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Exercise abrupt worker failure and effect-aware same-task resume.", + "stage_refs": [ + { + "component_id": "claude-code", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "companion-backend", + "capability": "Use the scoped native companion backend when explicitly selected", + "capability_key": "companion-backend", + "checked_at": "2026-09-20", + "layer_ids": [ + "workers" + ], + "selection": "optional", + "review_status": "partial_acceptance", + "activation": "Use the selected companion only for a concrete cross-client task with native readiness checked.", + "component_ids": [ + "codex-for-claude", + "codex" + ], + "candidate": null, + "evidence_ids": [ + "token-practice-gap-followup-20260920" + ], + "evidence_scope": "One read-only native bridge backend task passed.", + "limitations": [ + "The backend result is narrower than complete plugin integration; native account allowance and interactive activation remain separate." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Qualify the intended outer plugin invocation before calling full integration accepted.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. One read-only native bridge backend task passed.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Qualify the intended outer plugin invocation before calling full integration accepted.", + "stage_refs": [ + { + "component_id": "codex-for-claude", + "stage": "use", + "status": "partial_acceptance" + }, + { + "component_id": "codex", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "dependency-task-queue", + "capability": "Persist selected project claims and task dependencies", + "capability_key": "dependency-task-queue", + "checked_at": "2026-09-20", + "layer_ids": [ + "workers", + "scheduling-supervision" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Use one explicitly scoped queue when dependencies improve coordination.", + "component_ids": [ + "beads" + ], + "candidate": null, + "evidence_ids": [ + "upstream-native-tools-20260920" + ], + "evidence_scope": "Native Beads persisted task claims and dependency transitions in the selected fixture.", + "limitations": [ + "A queue is not worker cancellation, distributed lease correctness or restored task-effect acceptance." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Test the selected queue restart/recovery boundary before unattended reliance.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Native Beads persisted task claims and dependency transitions in the selected fixture.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Test the selected queue restart/recovery boundary before unattended reliance.", + "stage_refs": [ + { + "component_id": "beads", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "beads", + "stage": "persistence", + "status": "accepted_within_scope" + }, + { + "component_id": "beads", + "stage": "recovery", + "status": "not_established" + } + ] + }, + "supersedes": [] + }, + { + "id": "owned-worktrees", + "capability": "Create and retire bounded native Git worktrees", + "capability_key": "owned-worktrees", + "checked_at": "2026-09-20", + "layer_ids": [ + "workers", + "isolation" + ], + "selection": "default", + "review_status": "accepted_within_scope", + "activation": "Give each writer an owned branch/worktree and exact base; retain dirty work until reconciled.", + "component_ids": [ + "worktrunk" + ], + "candidate": null, + "evidence_ids": [ + "worktrunk-list", + "token-native-retained-functional-20260920", + "velanext-native-quality-tools-20260920" + ], + "evidence_scope": "Native listing and disposable create/list/remove passed; dirty removal was refused without loss.", + "limitations": [ + "Worktrees isolate edits, not permissions, accounts, global settings or shared services." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Prove any required crash cleanup without deleting unrelated or dirty state.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Native listing and disposable create/list/remove passed; dirty removal was refused without loss.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Prove any required crash cleanup without deleting unrelated or dirty state.", + "stage_refs": [ + { + "component_id": "worktrunk", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "scoped-os-isolation", + "capability": "Enforce the selected filesystem and HTTP network boundaries", + "capability_key": "scoped-os-isolation", + "checked_at": "2026-09-20", + "layer_ids": [ + "isolation" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Apply native restrictions only to the owned command and policy required by the task.", + "component_ids": [ + "sandbox-runtime" + ], + "candidate": null, + "evidence_ids": [ + "runtime-tools", + "native-sandbox-network-20260920" + ], + "evidence_scope": "Permitted/protected filesystem checks and loopback allow/deny HTTP fixtures passed.", + "limitations": [ + "This is not a general escape audit or TLS/SOCKS/network-stack qualification." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Qualify a new protocol/platform boundary if the task actually needs it.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Permitted/protected filesystem checks and loopback allow/deny HTTP fixtures passed.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Qualify a new protocol/platform boundary if the task actually needs it.", + "stage_refs": [ + { + "component_id": "sandbox-runtime", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "language-symbols", + "capability": "Retrieve exact symbols and references in configured languages", + "capability_key": "language-symbols", + "checked_at": "2026-09-20", + "layer_ids": [ + "code-navigation" + ], + "selection": "default", + "review_status": "accepted_within_scope", + "activation": "Use symbols/references for known identifiers and inspect original code before editing.", + "component_ids": [ + "serena" + ], + "candidate": null, + "evidence_ids": [ + "native-context-memory", + "foundation-native-20260920" + ], + "evidence_scope": "Serena native symbol operations passed; the foundation wave adds eight fresh Python/CJS checks after language coverage repair.", + "limitations": [ + "A configured Bash server or one passing extension cannot establish every language server." + ], + "source_paths": [ + "docs/foundation-stack.md" + ], + "next_gap": "Run the relevant extension/language operation for a newly adopted project.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Serena native symbol operations passed; the foundation wave adds eight fresh Python/CJS checks after language coverage repair.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Run the relevant extension/language operation for a newly adopted project.", + "stage_refs": [ + { + "component_id": "serena", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "structural-code-lane", + "capability": "Search syntax and inspect a selected static call graph", + "capability_key": "structural-code-lane", + "checked_at": "2026-09-20", + "layer_ids": [ + "code-navigation" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Choose exact structural search or the graph lane when it answers the actual code question.", + "component_ids": [ + "ast-grep", + "codebase-memory-mcp" + ], + "candidate": null, + "evidence_ids": [ + "portable-cli-artifacts", + "desktop-cli-workflows", + "native-cli-gaps" + ], + "evidence_scope": "Native structural-source fixtures and selected static graph search/trace passed.", + "limitations": [ + "The earlier Codex attempt in native-cli-gaps was quota-blocked; later Desktop acceptance does not rewrite that attempt.", + "Static graph coverage is language/project-specific and does not establish runtime call behavior." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Check target-language and changed-source coverage rather than assuming a universal graph.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Native structural-source fixtures and selected static graph search/trace passed.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Check target-language and changed-source coverage rather than assuming a universal graph.", + "stage_refs": [ + { + "component_id": "ast-grep", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "codebase-memory-mcp", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "scoped-symbol-index", + "capability": "Retrieve exact implementation from a scoped symbol index", + "capability_key": "scoped-symbol-index", + "checked_at": "2026-09-20", + "layer_ids": [ + "code-navigation", + "token-efficiency" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Use indexed discovery when it replaces broad reads; use the cheaper known-source read when adequate.", + "component_ids": [ + "jcodemunch-mcp" + ], + "candidate": null, + "evidence_ids": [ + "native-jcodemunch-20260920", + "native-token-focus-clients-20260920", + "native-token-clean-prefix-20260920" + ], + "evidence_scope": "Exact function retrieval and bounded native client calls passed; isolated install/restart/uninstall has its own receipt.", + "limitations": [ + "The complete search/source sequence was smaller than a whole file and larger than a known focused read.", + "Native estimated tokens avoided are not exact causal provider savings." + ], + "source_paths": [ + "docs/foundation-stack.md", + "adoption/lifecycle.md" + ], + "next_gap": "Verify symbol updates/deletions or recovery only after a relevant index/input change.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Exact function retrieval and bounded native client calls passed; isolated install/restart/uninstall has its own receipt.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Verify symbol updates/deletions or recovery only after a relevant index/input change.", + "stage_refs": [ + { + "component_id": "jcodemunch-mcp", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "jcodemunch-mcp", + "stage": "install", + "status": "accepted_within_scope" + }, + { + "component_id": "jcodemunch-mcp", + "stage": "restart", + "status": "accepted_within_scope" + }, + { + "component_id": "jcodemunch-mcp", + "stage": "cleanup", + "status": "accepted_within_scope" + }, + { + "component_id": "jcodemunch-mcp", + "stage": "recovery", + "status": "not_established" + } + ] + }, + "supersedes": [] + }, + { + "id": "scoped-document-bm25", + "capability": "Search and read a named local Markdown corpus", + "capability_key": "scoped-document-bm25", + "checked_at": "2026-09-20", + "layer_ids": [ + "document-retrieval" + ], + "selection": "default", + "review_status": "accepted_within_scope", + "activation": "Name the index/collection, refresh changed files, search then get the selected source.", + "component_ids": [ + "qmd" + ], + "candidate": null, + "evidence_ids": [ + "qmd-bm25-retrieval-20260919", + "desktop-cli-workflows", + "foundation-native-20260920" + ], + "evidence_scope": "Native scoped QMD search/get passed; the fixed twelve-query benchmark returned the intended source in eight top-three results.", + "limitations": [ + "All four benchmark misses remain; exact source retrieval on a fixture does not establish arbitrary corpus recall.", + "The selected BM25 lane needs no downloaded embedding model." + ], + "source_paths": [ + "blueprints/us-equities/retrieval-evaluation/README.md", + "docs/foundation-stack.md" + ], + "next_gap": "Evaluate positive and absent queries for a new corpus.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Native scoped QMD search/get passed; the fixed twelve-query benchmark returned the intended source in eight top-three results.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Evaluate positive and absent queries for a new corpus.", + "stage_refs": [ + { + "component_id": "qmd", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "source-document-conversion", + "capability": "Convert supported local documents into bounded source evidence", + "capability_key": "source-document-conversion", + "checked_at": "2026-09-20", + "layer_ids": [ + "document-retrieval" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Select the supported input format and retain document/page/hash boundaries.", + "component_ids": [ + "markitdown", + "poppler" + ], + "candidate": null, + "evidence_ids": [ + "portable-cli-artifacts", + "mac-native-document-ingestion-20260920", + "wsl-document-ingestion-20260920" + ], + "evidence_scope": "Selected HTML conversion passed; native Poppler preserved three designed PDF pages, twenty-four cells and twelve positive/absent queries on Mac and WSL.", + "limitations": [ + "Base MarkItDown HTML acceptance does not imply optional PDF/Office extras.", + "The designed born-digital PDF fixture does not qualify OCR, arbitrary layouts or semantic retrieval." + ], + "source_paths": [ + "blueprints/convergence-practice/document-ingestion/README.md", + "blueprints/convergence-practice/wsl-document-ingestion/README.md" + ], + "next_gap": "Freeze a representative layout/OCR protocol before extending the claim.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Selected HTML conversion passed; native Poppler preserved three designed PDF pages, twenty-four cells and twelve positive/absent queries on Mac and WSL.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Freeze a representative layout/OCR protocol before extending the claim.", + "stage_refs": [ + { + "component_id": "markitdown", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "poppler", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "curated-developer-docs", + "capability": "Retrieve selected curated developer documentation", + "capability_key": "curated-developer-docs", + "checked_at": "2026-09-20", + "layer_ids": [ + "document-retrieval" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Use for a named documentation gap and inspect the returned primary source.", + "component_ids": [ + "context-hub" + ], + "candidate": null, + "evidence_ids": [ + "token-native-retained-functional-20260920" + ], + "evidence_scope": "Retained native Context Hub search/retrieval supports its selected developer-document operation.", + "limitations": [ + "This is not a claim that all external documentation is current or indexed." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Recheck the relevant source revision when its API or requirement changes.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Retained native Context Hub search/retrieval supports its selected developer-document operation.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Recheck the relevant source revision when its API or requirement changes.", + "stage_refs": [ + { + "component_id": "context-hub", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "project-semantic-index", + "capability": "Maintain conceptual code retrieval for one project", + "capability_key": "project-semantic-index", + "checked_at": "2026-09-20", + "layer_ids": [ + "semantic-rag", + "code-navigation" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Adopt one explicit project index when conceptual search helps; keep exact identifiers in focused source tools.", + "component_ids": [ + "socraticode", + "qdrant" + ], + "candidate": null, + "evidence_ids": [ + "native-rag", + "desktop-direct-rag", + "foundation-native-20260920" + ], + "evidence_scope": "Correct project code and automatic add/update/delete persisted in the selected local vector store; direct Desktop retrieval is separately recorded.", + "limitations": [ + "Another project/index and full-service restart/recovery need their own scope." + ], + "source_paths": [ + "docs/foundation-stack.md" + ], + "next_gap": "Verify changed-project freshness before relying on retrieved code.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Correct project code and automatic add/update/delete persisted in the selected local vector store; direct Desktop retrieval is separately recorded.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Verify changed-project freshness before relying on retrieved code.", + "stage_refs": [ + { + "component_id": "socraticode", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "socraticode", + "stage": "persistence", + "status": "accepted_within_scope" + }, + { + "component_id": "socraticode", + "stage": "recovery", + "status": "not_established" + }, + { + "component_id": "qdrant", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "qdrant", + "stage": "persistence", + "status": "accepted_within_scope" + }, + { + "component_id": "qdrant", + "stage": "recovery", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "local-embedding-runtime", + "capability": "Serve accepted local embeddings with pinned model inputs", + "capability_key": "local-embedding-runtime", + "checked_at": "2026-09-20", + "layer_ids": [ + "semantic-rag", + "observation-inference" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Retain the compatible runtime/model revision and native GPU evidence.", + "component_ids": [ + "vllm", + "huggingface-hub-native" + ], + "candidate": null, + "evidence_ids": [ + "native-rag", + "vllm-compatibility", + "foundation-native-20260920" + ], + "evidence_scope": "Native local embedding/model retrieval supports the accepted runtime; a later runtime installed but failed GPU startup and the accepted environment was restored.", + "limitations": [ + "The newer WSL startup failure remains failed; release availability is not runtime acceptance.", + "Model downloads and embedding acceptance do not qualify local text-generation quality." + ], + "source_paths": [ + "docs/foundation-stack.md" + ], + "next_gap": "Test a changed GPU/runtime only for an actual compatibility need.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Native local embedding/model retrieval supports the accepted runtime; a later runtime installed but failed GPU startup and the accepted environment was restored.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Test a changed GPU/runtime only for an actual compatibility need.", + "stage_refs": [ + { + "component_id": "vllm", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "huggingface-hub-native", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "scoped-memory-lifecycle", + "capability": "Persist and retrieve approved cross-client project memory", + "capability_key": "scoped-memory-lifecycle", + "checked_at": "2026-09-20", + "layer_ids": [ + "durable-memory", + "recovery-portability" + ], + "selection": "default", + "review_status": "accepted_within_scope", + "activation": "Use one explicitly scoped memory of record; durable writes require explicit intent.", + "component_ids": [ + "ai-memory" + ], + "candidate": null, + "evidence_ids": [ + "native-memory", + "native-memory-lifecycle-20260919", + "native-ai-memory-maintenance-20260920", + "mac-memory-patch-20260920", + "wsl-memory-maintenance-20260920" + ], + "evidence_scope": "Scoped native retrieval, lifecycle negatives, migration, restart, upstream backup and empty-target restore have distinct accepted receipts.", + "limitations": [ + "Lifecycle capture is bounded sanitized observations, not complete transcripts.", + "Synthetic maintenance and production activation differ; TTL observations are not immediate access revocation." + ], + "source_paths": [ + "adoption/lifecycle.md", + "blueprints/convergence-practice/wsl-memory-maintenance/README.md" + ], + "next_gap": "Establish independent-host/key recovery and the target production activation separately.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Scoped native retrieval, lifecycle negatives, migration, restart, upstream backup and empty-target restore have distinct accepted receipts.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Establish independent-host/key recovery and the target production activation separately.", + "stage_refs": [ + { + "component_id": "ai-memory", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "ai-memory", + "stage": "install", + "status": "accepted_within_scope" + }, + { + "component_id": "ai-memory", + "stage": "persistence", + "status": "accepted_within_scope" + }, + { + "component_id": "ai-memory", + "stage": "restart", + "status": "accepted_within_scope" + }, + { + "component_id": "ai-memory", + "stage": "cleanup", + "status": "accepted_within_scope" + }, + { + "component_id": "ai-memory", + "stage": "recovery", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "bounded-browser-operations", + "capability": "Inspect and interact with selected browser pages", + "capability_key": "bounded-browser-operations", + "checked_at": "2026-09-20", + "layer_ids": [ + "web-research" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Use the selected browser lane for the requested page and retain bounded results.", + "component_ids": [ + "agent-browser", + "playwright-cli" + ], + "candidate": null, + "evidence_ids": [ + "desktop-cli-workflows", + "token-practice-gap-followup-20260920" + ], + "evidence_scope": "Selected local browser snapshot/ref interactions and the pinned Linux browser fixture passed.", + "limitations": [ + "Local fixture acceptance does not authorize unrelated websites, accounts or messages.", + "Browser-session recovery and arbitrary website compatibility remain unestablished." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Check a changed website/browser operation only when the task depends on it.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Selected local browser snapshot/ref interactions and the pinned Linux browser fixture passed.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Check a changed website/browser operation only when the task depends on it.", + "stage_refs": [ + { + "component_id": "agent-browser", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "playwright-cli", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "public-literature-retrieval", + "capability": "Discover and retrieve selected public research papers", + "capability_key": "public-literature-retrieval", + "checked_at": "2026-09-20", + "layer_ids": [ + "web-research" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Use for a bounded literature question and verify the selected paper/source.", + "component_ids": [ + "openresearch" + ], + "candidate": null, + "evidence_ids": [ + "artifact-reductions", + "token-practice-gap-followup-20260920" + ], + "evidence_scope": "Retained public-paper retrieval and selected extracted artifacts support the narrow research operation.", + "limitations": [ + "Discovery and extracted text do not establish paper conclusions or exhaustive literature coverage." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Evaluate missing/ambiguous source handling for the next research corpus.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Retained public-paper retrieval and selected extracted artifacts support the narrow research operation.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Evaluate missing/ambiguous source handling for the next research corpus.", + "stage_refs": [ + { + "component_id": "openresearch", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "selected-context-processing", + "capability": "Process large tool output while preserving useful source facts", + "capability_key": "selected-context-processing", + "checked_at": "2026-09-20", + "layer_ids": [ + "token-efficiency" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Use an explicit filter/execution lane when cheaper than a short direct read, retaining raw errors and recovery.", + "component_ids": [ + "context-mode", + "rtk" + ], + "candidate": null, + "evidence_ids": [ + "native-context-memory", + "token-practice-artifacts-20260920", + "token-practice-native-pairs-20260920", + "native-token-focus-clients-20260920", + "foundation-native-20260920" + ], + "evidence_scope": "Selected explicit native calls and exact artifact checks passed; paired trials retain both a Codex reduction and a Claude increase.", + "limitations": [ + "Cache conditions were uncontrolled and enclosing workflow usage was incomplete.", + "The foundation gateway RTK/lite previews failed required semantic checks; general CLI acceptance does not repair those failures." + ], + "source_paths": [ + "docs/token-practice.md", + "docs/foundation-stack.md" + ], + "next_gap": "Measure only a concrete changed workload, with correctness and complete attempt accounting.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Selected explicit native calls and exact artifact checks passed; paired trials retain both a Codex reduction and a Claude increase.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Measure only a concrete changed workload, with correctness and complete attempt accounting.", + "stage_refs": [ + { + "component_id": "context-mode", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "rtk", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "guarded-recoverable-compression", + "capability": "Compress selected artifacts with exact-source recovery", + "capability_key": "guarded-recoverable-compression", + "checked_at": "2026-09-20", + "layer_ids": [ + "token-efficiency" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Use upstream direct MCP or the guarded adapter for a matching selected artifact.", + "component_ids": [ + "headroom" + ], + "candidate": null, + "evidence_ids": [ + "native-headroom-mcp-20260920", + "native-token-clean-prefix-20260920", + "token-practice-confirmation-20260920" + ], + "evidence_scope": "Owned synthetic MCP compression/retrieval and isolated install/restart/uninstall passed; retained guard comparisons preserve counterexamples.", + "limitations": [ + "Automatic interception of all agent traffic is not configured.", + "Capped native counters and exact artifact comparisons do not establish lifetime causal provider savings." + ], + "source_paths": [ + "docs/token-practice.md", + "adoption/lifecycle.md" + ], + "next_gap": "Reject a candidate representation that loses required facts or costs more than the adequate baseline.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Owned synthetic MCP compression/retrieval and isolated install/restart/uninstall passed; retained guard comparisons preserve counterexamples.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Reject a candidate representation that loses required facts or costs more than the adequate baseline.", + "stage_refs": [ + { + "component_id": "headroom", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "headroom", + "stage": "install", + "status": "accepted_within_scope" + }, + { + "component_id": "headroom", + "stage": "restart", + "status": "accepted_within_scope" + }, + { + "component_id": "headroom", + "stage": "cleanup", + "status": "accepted_within_scope" + }, + { + "component_id": "headroom", + "stage": "recovery", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "selected-file-representations", + "capability": "Pack selected files or encode structured data only when useful", + "capability_key": "selected-file-representations", + "checked_at": "2026-09-20", + "layer_ids": [ + "token-efficiency", + "code-navigation" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Use explicit file selection and keep the smallest adequate decoded representation.", + "component_ids": [ + "repomix", + "toon" + ], + "candidate": null, + "evidence_ids": [ + "portable-cli-artifacts", + "token-practice-artifacts-20260920", + "token-practice-catalog-toon-20260920" + ], + "evidence_scope": "Selected-file packing and TOON roundtrip passed; exact full-catalog tokens increased under TOON and compact JSON was retained.", + "limitations": [ + "Structural compression omits implementation details; originals remain required for edits and correctness.", + "A smaller heuristic estimate is not an exact token reduction." + ], + "source_paths": [ + "docs/token-practice.md" + ], + "next_gap": "Recount a changed artifact only when representation choice matters.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Selected-file packing and TOON roundtrip passed; exact full-catalog tokens increased under TOON and compact JSON was retained.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Recount a changed artifact only when representation choice matters.", + "stage_refs": [ + { + "component_id": "repomix", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "toon", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "native-usage-reading", + "capability": "Read native provider usage without mixing counter scopes", + "capability_key": "native-usage-reading", + "checked_at": "2026-09-20", + "layer_ids": [ + "token-efficiency", + "observation-inference" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Read the selected native ledger and retain its aggregation scope.", + "component_ids": [ + "ccusage" + ], + "candidate": null, + "evidence_ids": [ + "token-practice-gap-followup-20260920", + "current-session-observation-20260920" + ], + "evidence_scope": "Offline native usage parsing and scoped current-session observations have retained outputs.", + "limitations": [ + "Provider consumption, estimated savings, billing and cache subsets are distinct.", + "Repeated cumulative snapshots cannot be summed as additional usage." + ], + "source_paths": [ + "docs/token-practice.md" + ], + "next_gap": "Resolve missing attempt/child coverage before any whole-workflow efficiency claim.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Offline native usage parsing and scoped current-session observations have retained outputs.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Resolve missing attempt/child coverage before any whole-workflow efficiency claim.", + "stage_refs": [ + { + "component_id": "ccusage", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "deterministic-quality-tools", + "capability": "Evaluate fixtures and review shell/source changes", + "capability_key": "deterministic-quality-tools", + "checked_at": "2026-09-20", + "layer_ids": [ + "quality-evaluation" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Use the smallest meaningful project acceptance plus independent review for substantive changes.", + "component_ids": [ + "promptfoo", + "difftastic", + "shellcheck", + "playwright-test" + ], + "candidate": null, + "evidence_ids": [ + "token-native-retained-functional-20260920", + "portable-cli-artifacts", + "wsl-application-20260920" + ], + "evidence_scope": "Deterministic promptfoo, native shell/structural comparison and the locked browser application flow have scoped acceptance.", + "limitations": [ + "Fixture success does not prove universal model quality or production application correctness." + ], + "source_paths": [ + "blueprints/convergence-practice/wsl-application/README.md" + ], + "next_gap": "Add the missing behavioral negative case exposed by the next task.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Deterministic promptfoo, native shell/structural comparison and the locked browser application flow have scoped acceptance.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Add the missing behavioral negative case exposed by the next task.", + "stage_refs": [ + { + "component_id": "promptfoo", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "difftastic", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "shellcheck", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "playwright-test", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "offline-security-inventory", + "capability": "Check workflow/secret controls and selected dependency identity", + "capability_key": "offline-security-inventory", + "checked_at": "2026-09-20", + "layer_ids": [ + "ci-supply-chain", + "quality-evaluation" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Run selected offline checks on changed published files and an explicitly scoped dependency source.", + "component_ids": [ + "gitleaks", + "zizmor", + "syft" + ], + "candidate": null, + "evidence_ids": [ + "velanext-native-quality-tools-20260920", + "native-ci-security-20260920", + "native-linux-zizmor-20260920", + "syft-sdk-inventory-20260919" + ], + "evidence_scope": "Native gitleaks and zizmor accepted clean controls and rejected inert unsafe fixtures; Syft matched thirty-six selected SDK distributions.", + "limitations": [ + "Secret scanning is not proof of no secret anywhere; regular offline workflow analysis is scoped.", + "The financial SDK fixture supports dependency enumeration only, not financial behavior or vulnerability assurance." + ], + "source_paths": [ + "blueprints/convergence-practice/ci-security/README.md", + "blueprints/us-equities/supply-chain/README.md" + ], + "next_gap": "Qualify new distributions or security boundaries independently.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Native gitleaks and zizmor accepted clean controls and rejected inert unsafe fixtures; Syft matched thirty-six selected SDK distributions.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Qualify new distributions or security boundaries independently.", + "stage_refs": [ + { + "component_id": "gitleaks", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "zizmor", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "syft", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "clean-token-tool-ci", + "capability": "Reproduce native context-tool commands in a clean CI environment", + "capability_key": "clean-token-tool-ci", + "checked_at": "2026-09-20", + "layer_ids": [ + "ci-supply-chain", + "token-efficiency" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Run the existing job when its pinned inputs or acceptance code change.", + "component_ids": [ + "rtk", + "qmd", + "repomix", + "toon" + ], + "candidate": null, + "evidence_ids": [ + "native-token-ci-local-20260920", + "native-token-ci-github-20260920" + ], + "evidence_scope": "Local and GitHub clean installation passed forty-one command expectations and fourteen fidelity/recovery checks; retained artifact/source hashes matched.", + "limitations": [ + "CI acceptance covers these four tool fixtures, not live providers, GPU execution or a full new-PC stack." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Extend a specific missing native-tool CI behavior only with its own useful fixture.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Local and GitHub clean installation passed forty-one command expectations and fourteen fidelity/recovery checks; retained artifact/source hashes matched.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Extend a specific missing native-tool CI behavior only with its own useful fixture.", + "stage_refs": [ + { + "component_id": "rtk", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "qmd", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "repomix", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "toon", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "owned-process-deadlines", + "capability": "Terminate an owned local process tree at its deadline", + "capability_key": "owned-process-deadlines", + "checked_at": "2026-09-20", + "layer_ids": [ + "scheduling-supervision", + "workers" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Use a transient owned unit for a task that needs process-tree supervision.", + "component_ids": [ + "systemd" + ], + "candidate": null, + "evidence_ids": [ + "native-worker-supervision-20260919" + ], + "evidence_scope": "The Linux user manager terminated a TERM-ignoring parent and descendants, retained timeout failure, and accepted a separate fresh run.", + "limitations": [ + "Local process termination does not prove remote provider cancellation, spending caps or exactly-once effects." + ], + "source_paths": [ + "blueprints/us-equities/worker-supervision/README.md" + ], + "next_gap": "Test worker cancellation and reconcile external effects before any relaunch.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. The Linux user manager terminated a TERM-ignoring parent and descendants, retained timeout failure, and accepted a separate fresh run.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Test worker cancellation and reconcile external effects before any relaunch.", + "stage_refs": [ + { + "component_id": "systemd", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "checkpointed-workflow-resume", + "capability": "Retry unfinished workflow steps while preserving a checkpoint", + "capability_key": "checkpointed-workflow-resume", + "checked_at": "2026-09-20", + "layer_ids": [ + "scheduling-supervision", + "recovery-portability" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Run an owned workflow with explicit checkpoints and bounded retry conditions.", + "component_ids": [ + "dagu" + ], + "candidate": null, + "evidence_ids": [ + "native-dagu-job-recovery-20260920", + "wsl-transport-recovery-20260920" + ], + "evidence_scope": "Native cancellation/retry retained one checkpoint on Mac and WSL; separate SSH-client termination left the same job running to completion.", + "limitations": [ + "Controlled transport interruption is not a real network outage or host reboot.", + "This does not establish remote model cancellation or distributed exactly-once effects." + ], + "source_paths": [ + "blueprints/convergence-practice/job-recovery/README.md", + "blueprints/convergence-practice/wsl-transport-recovery/README.md" + ], + "next_gap": "Qualify scheduled-service restart/reboot and unfinished worker effect reconciliation.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Native cancellation/retry retained one checkpoint on Mac and WSL; separate SSH-client termination left the same job running to completion.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Qualify scheduled-service restart/reboot and unfinished worker effect reconciliation.", + "stage_refs": [ + { + "component_id": "dagu", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "dagu", + "stage": "persistence", + "status": "accepted_within_scope" + }, + { + "component_id": "dagu", + "stage": "restart", + "status": "accepted_within_scope" + }, + { + "component_id": "dagu", + "stage": "recovery", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "local-typed-application", + "capability": "Build a typed local UI/API with persistent database state", + "capability_key": "local-typed-application", + "checked_at": "2026-09-20", + "layer_ids": [ + "hosting-services", + "quality-evaluation" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Use the selected locked project and owned native database/application processes.", + "component_ids": [ + "nextjs", + "react", + "fastapi", + "postgresql" + ], + "candidate": null, + "evidence_ids": [ + "native-application-delivery-20260920", + "mac-native-application-migration-20260920", + "wsl-application-20260920" + ], + "evidence_scope": "Locked UI/API, twelve API checks, browser create/update, migration reversal and exact rows/history after restart passed on named Mac/WSL fixtures.", + "limitations": [ + "No production authentication, cloud hosting or independent-host database restore is accepted.", + "The failed newer TypeScript generator attempt remains separate from the retained supported runtime." + ], + "source_paths": [ + "blueprints/convergence-practice/application-delivery/README.md", + "blueprints/convergence-practice/wsl-application/README.md" + ], + "next_gap": "Qualify independent restore and the requested deployment-specific access/runtime conditions.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Locked UI/API, twelve API checks, browser create/update, migration reversal and exact rows/history after restart passed on named Mac/WSL fixtures.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Qualify independent restore and the requested deployment-specific access/runtime conditions.", + "stage_refs": [ + { + "component_id": "nextjs", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "nextjs", + "stage": "install", + "status": "accepted_within_scope" + }, + { + "component_id": "nextjs", + "stage": "persistence", + "status": "accepted_within_scope" + }, + { + "component_id": "nextjs", + "stage": "restart", + "status": "accepted_within_scope" + }, + { + "component_id": "nextjs", + "stage": "recovery", + "status": "not_established" + }, + { + "component_id": "react", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "react", + "stage": "install", + "status": "accepted_within_scope" + }, + { + "component_id": "react", + "stage": "persistence", + "status": "accepted_within_scope" + }, + { + "component_id": "react", + "stage": "restart", + "status": "accepted_within_scope" + }, + { + "component_id": "react", + "stage": "recovery", + "status": "not_established" + }, + { + "component_id": "fastapi", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "fastapi", + "stage": "install", + "status": "accepted_within_scope" + }, + { + "component_id": "fastapi", + "stage": "persistence", + "status": "accepted_within_scope" + }, + { + "component_id": "fastapi", + "stage": "restart", + "status": "accepted_within_scope" + }, + { + "component_id": "fastapi", + "stage": "recovery", + "status": "not_established" + }, + { + "component_id": "postgresql", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "postgresql", + "stage": "install", + "status": "accepted_within_scope" + }, + { + "component_id": "postgresql", + "stage": "persistence", + "status": "accepted_within_scope" + }, + { + "component_id": "postgresql", + "stage": "restart", + "status": "accepted_within_scope" + }, + { + "component_id": "postgresql", + "stage": "recovery", + "status": "not_established" + } + ] + }, + "supersedes": [] + }, + { + "id": "mac-container-volume", + "capability": "Retain a database row in an owned native Mac container volume", + "capability_key": "mac-container-volume", + "checked_at": "2026-09-20", + "layer_ids": [ + "hosting-services", + "isolation" + ], + "selection": "optional", + "review_status": "accepted_within_scope", + "activation": "Use only the matching Mac container/volume recipe; WSL has a separate direct database recipe.", + "component_ids": [ + "apple-container" + ], + "candidate": null, + "evidence_ids": [ + "mac-native-container-storage-20260920" + ], + "evidence_scope": "Pinned PostgreSQL image on Apple container retained its row after native stop/start; owned fixtures were removed.", + "limitations": [ + "Mac Documents bind mount stalled; accepted ext4 named-volume behavior does not erase that failure.", + "Mac-only fixture; no crash/reboot or production durability claim." + ], + "source_paths": [ + "blueprints/convergence-practice/container-storage/README.md" + ], + "next_gap": "Qualify crash/reboot persistence only when that deployment needs it.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Pinned PostgreSQL image on Apple container retained its row after native stop/start; owned fixtures were removed.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Qualify crash/reboot persistence only when that deployment needs it.", + "stage_refs": [ + { + "component_id": "apple-container", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "apple-container", + "stage": "persistence", + "status": "accepted_within_scope" + }, + { + "component_id": "apple-container", + "stage": "restart", + "status": "accepted_within_scope" + }, + { + "component_id": "apple-container", + "stage": "cleanup", + "status": "accepted_within_scope" + }, + { + "component_id": "apple-container", + "stage": "recovery", + "status": "not_established" + } + ] + }, + "supersedes": [] + }, + { + "id": "native-mcp-adapters", + "capability": "Bridge or inspect selected MCP operations through upstream tools", + "capability_key": "native-mcp-adapters", + "checked_at": "2026-09-20", + "layer_ids": [ + "hosting-services", + "code-navigation" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Use the configured project bridge or Inspector for a concrete operation/protocol check.", + "component_ids": [ + "mcporter", + "mcp-inspector" + ], + "candidate": null, + "evidence_ids": [ + "desktop-restart-acceptance", + "token-native-retained-functional-20260920" + ], + "evidence_scope": "Retained native bridge recovery and Inspector stdio arithmetic support their selected operations.", + "limitations": [ + "A shared daemon is not an owned disposable service; removing one registration is not an uninstall or all-client cleanup." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Qualify changed process roots and scoped registration recovery without disturbing unrelated consumers.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Retained native bridge recovery and Inspector stdio arithmetic support their selected operations.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Qualify changed process roots and scoped registration recovery without disturbing unrelated consumers.", + "stage_refs": [ + { + "component_id": "mcporter", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "mcp-inspector", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "same-host-restore", + "capability": "Restore selected native state into an isolated empty target", + "capability_key": "same-host-restore", + "checked_at": "2026-09-20", + "layer_ids": [ + "recovery-portability", + "durable-memory", + "semantic-rag" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Retain the exact snapshot and separately available private key source; restore into an empty owned target.", + "component_ids": [ + "restic", + "ai-memory", + "qdrant" + ], + "candidate": null, + "evidence_ids": [ + "restic-local-public-reference-20260919", + "ai-memory-native-state-recovery-20260919", + "qdrant-native-state-recovery-20260919", + "native-wsl-restic-synthetic-20260920" + ], + "evidence_scope": "Selected public bytes, native memory/FTS state and Qdrant snapshot/query results survived same-host backup/restore; synthetic wrong-key/corrupt-copy refusals were retained.", + "limitations": [ + "Independent physical host, lost-key recovery and the whole stack after disaster remain unestablished.", + "Financial-blueprint location supplies reusable state-recovery evidence only." + ], + "source_paths": [ + "adoption/lifecycle.md", + "blueprints/convergence-practice/wsl-restore/README.md" + ], + "next_gap": "Run independent off-host recovery with a separately accessible key and real post-restore application queries.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Selected public bytes, native memory/FTS state and Qdrant snapshot/query results survived same-host backup/restore; synthetic wrong-key/corrupt-copy refusals were retained.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Run independent off-host recovery with a separately accessible key and real post-restore application queries.", + "stage_refs": [ + { + "component_id": "restic", + "stage": "recovery", + "status": "accepted_within_scope" + }, + { + "component_id": "ai-memory", + "stage": "recovery", + "status": "accepted_within_scope" + }, + { + "component_id": "qdrant", + "stage": "recovery", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "native-session-resume", + "capability": "Resume the same native session after an owned interruption", + "capability_key": "native-session-resume", + "checked_at": "2026-09-20", + "layer_ids": [ + "recovery-portability", + "native-clients", + "workers" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Reconcile native session identity and saved effects before resubmitting unfinished work.", + "component_ids": [ + "codex", + "claude-code" + ], + "candidate": null, + "evidence_ids": [ + "native-codex-session-recovery-20260920", + "native-claude-session-recovery-20260920", + "native-token-stack-final-20260920" + ], + "evidence_scope": "Codex on Mac and Claude on WSL resumed the same session to finish an unchanged single checkpoint; later bounded source tasks also retained continuations.", + "limitations": [ + "Individual session continuation does not establish arbitrary worker crash, provider cancellation or whole-host recovery.", + "Resumed cumulative usage must not be added again to earlier included totals." + ], + "source_paths": [ + "blueprints/convergence-practice/native-recovery/README.md", + "blueprints/convergence-practice/native-recovery/claude/README.md" + ], + "next_gap": "Qualify abrupt writing-worker failure with task-specific single-effect acceptance.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Codex on Mac and Claude on WSL resumed the same session to finish an unchanged single checkpoint; later bounded source tasks also retained continuations.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Qualify abrupt writing-worker failure with task-specific single-effect acceptance.", + "stage_refs": [ + { + "component_id": "codex", + "stage": "recovery", + "status": "accepted_within_scope" + }, + { + "component_id": "claude-code", + "stage": "recovery", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "loopback-usage-observation", + "capability": "Observe bounded native outcomes and reconcile usage categories", + "capability_key": "loopback-usage-observation", + "checked_at": "2026-09-20", + "layer_ids": [ + "observation-inference" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Keep local observation access separate from workflow operator authentication and inference accounts.", + "component_ids": [ + "opentelemetry-collector-contrib", + "prometheus", + "loki", + "grafana", + "alertmanager", + "ntfy" + ], + "candidate": null, + "evidence_ids": [ + "native-observability", + "native-observability-followup", + "native-token-stack-final-20260920", + "current-session-observation-20260920" + ], + "evidence_scope": "Native tasks, loopback queries/dashboard and local firing/resolved notifications passed; later writer-scoped results reconcile selected native usage.", + "limitations": [ + "Liveness, checkpoint age, source attribution and consumed tokens are different observations.", + "Extra startup events and unlabelled historical invocations retain attribution limits; no exact causal lifetime savings are inferred." + ], + "source_paths": [ + "observability/README.md", + "adoption/lifecycle.md" + ], + "next_gap": "Qualify scheduled-service/reboot persistence and missing task attribution only in the needed scope.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Native tasks, loopback queries/dashboard and local firing/resolved notifications passed; later writer-scoped results reconcile selected native usage.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Qualify scheduled-service/reboot persistence and missing task attribution only in the needed scope.", + "stage_refs": [ + { + "component_id": "opentelemetry-collector-contrib", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "prometheus", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "loki", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "grafana", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "alertmanager", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "ntfy", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "bounded-history-and-traces", + "capability": "Inspect selected native session history and local traces", + "capability_key": "bounded-history-and-traces", + "checked_at": "2026-09-20", + "layer_ids": [ + "observation-inference" + ], + "selection": "conditional", + "review_status": "accepted_within_scope", + "activation": "Use a selected archive or loopback receiver when a concrete diagnostic needs it.", + "component_ids": [ + "agentsview", + "otel-tui" + ], + "candidate": null, + "evidence_ids": [ + "token-practice-gap-followup-20260920", + "upstream-native-tools-20260920", + "current-session-observation-20260920" + ], + "evidence_scope": "One scoped session archive query and a synthetic loopback terminal trace were accepted; current observations retain their separate bounds.", + "limitations": [ + "Archive retrieval requires explicit scope/refresh and is not every native transcript or durable memory.", + "Synthetic trace acceptance is not production tracing completeness." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Test changed archive/session scope and missing attribution before drawing broader conclusions.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. One scoped session archive query and a synthetic loopback terminal trace were accepted; current observations retain their separate bounds.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Test changed archive/session scope and missing attribution before drawing broader conclusions.", + "stage_refs": [ + { + "component_id": "agentsview", + "stage": "use", + "status": "accepted_within_scope" + }, + { + "component_id": "otel-tui", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "interactive-hud-boundary", + "capability": "Retain synthetic HUD rendering separately from live activation", + "capability_key": "interactive-hud-boundary", + "checked_at": "2026-09-20", + "layer_ids": [ + "observation-inference" + ], + "selection": "optional", + "review_status": "partial_acceptance", + "activation": "Keep the configured optional statusline scoped and use native usage for authoritative accounting.", + "component_ids": [ + "claude-hud" + ], + "candidate": null, + "evidence_ids": [ + "token-practice-gap-followup-20260920", + "native-claude-hud-interactive-20260920" + ], + "evidence_scope": "Synthetic renderer passed; the real terminal launch reached onboarding before the conversation HUD appeared.", + "limitations": [ + "Live interactive HUD rendering remains unverified despite existing authentication; a synthetic rendering pass does not replace it." + ], + "source_paths": [ + "docs/convergence-architecture.md", + "adoption/lifecycle.md" + ], + "next_gap": "Observe the real statusline only after the native onboarding condition is resolved.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Synthetic renderer passed; the real terminal launch reached onboarding before the conversation HUD appeared.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Observe the real statusline only after the native onboarding condition is resolved.", + "stage_refs": [ + { + "component_id": "claude-hud", + "stage": "use", + "status": "partial_acceptance" + } + ] + }, + "supersedes": [] + }, + { + "id": "local-generation-trial", + "capability": "Trial local text generation against a frozen repair oracle", + "capability_key": "local-generation-trial", + "checked_at": "2026-09-20", + "layer_ids": [ + "observation-inference" + ], + "selection": "trial", + "review_status": "accepted_within_scope", + "activation": "Use an isolated local trial only when a concrete inference gap warrants it; native workers remain default.", + "component_ids": [ + "llama-cpp" + ], + "candidate": null, + "evidence_ids": [ + "native-gpu-patch-20260920" + ], + "evidence_scope": "One pinned partial-offload local CUDA repair passed independent source review and twelve original tests on WSL RTX4090.", + "limitations": [ + "Single-task trial, not general frontier parity, host portability or causal token savings.", + "Memory reserve, model/hash provenance and missing exact layer telemetry remain in the receipt." + ], + "source_paths": [ + "blueprints/convergence-practice/gpu-inference/README.md" + ], + "next_gap": "Freeze a representative next workload and resource acceptance before expanding use.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. One pinned partial-offload local CUDA repair passed independent source review and twelve original tests on WSL RTX4090.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Freeze a representative next workload and resource acceptance before expanding use.", + "stage_refs": [ + { + "component_id": "llama-cpp", + "stage": "use", + "status": "accepted_within_scope" + } + ] + }, + "supersedes": [] + }, + { + "id": "optional-gateway-lifecycle", + "capability": "Keep optional gateway lifecycle separate from inference acceptance", + "capability_key": "optional-gateway-lifecycle", + "checked_at": "2026-09-20", + "layer_ids": [ + "observation-inference", + "hosting-services" + ], + "selection": "trial", + "review_status": "partial_acceptance", + "activation": "Retain native account/model routes; use the optional gateway only for an explicit qualified routing need.", + "component_ids": [ + "omniroute" + ], + "candidate": null, + "evidence_ids": [ + "foundation-native-20260920" + ], + "evidence_scope": "Clean native Linux installation, service restart, persistence, plaintext restore and stop passed; inference and compression are separately scoped attempts.", + "limitations": [ + "Native Codex model400, direct quota429 and malformed Claude launch/plaintext429 remain unsuccessful gateway tasks.", + "RTK/lite semantic previews failed; exact dedup retained its matching-scope result; cache/compression counters are not provider savings." + ], + "source_paths": [ + "docs/foundation-stack.md" + ], + "next_gap": "Retry an exact-model task only after model mapping/provider capacity changes; do not repeat unchanged refusals.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "Only the listed canonical stages and their original host/operation scopes apply. Clean native Linux installation, service restart, persistence, plaintext restore and stop passed; inference and compression are separately scoped attempts.", + "unknown": "Unlisted or unestablished stages are not implied by this capability decision. Retry an exact-model task only after model mapping/provider capacity changes; do not repeat unchanged refusals.", + "stage_refs": [ + { + "component_id": "omniroute", + "stage": "use", + "status": "partial_acceptance" + }, + { + "component_id": "omniroute", + "stage": "install", + "status": "accepted_within_scope" + }, + { + "component_id": "omniroute", + "stage": "restart", + "status": "accepted_within_scope" + }, + { + "component_id": "omniroute", + "stage": "recovery", + "status": "partial_acceptance" + } + ] + }, + "supersedes": [] + }, + { + "id": "tavily-native-integration-pending", + "capability": "Bind Tavily source review to the intended native CLI and skill activation receipt", + "capability_key": "tavily-native-integration", + "checked_at": "2026-09-20", + "layer_ids": [ + "web-research", + "instructions-skills" + ], + "selection": "candidate", + "review_status": "source_review", + "activation": "Select the needed Tavily operation after native CLI and eight-skill discovery acceptance is explicitly reconciled for the intended host.", + "component_ids": [], + "candidate": { + "id": "tavily", + "repository": "https://github.com/tavily-ai/skills" + }, + "evidence_ids": [], + "evidence_scope": "The existing source/integration receipt is referenced without creating a selected component or a new host success claim. The current native CLI integration receipt is pending coordinator reconciliation.", + "limitations": [ + "Earlier source-host CLI/search/discovery observations retain their original scope; this pending entry neither repeats nor erases them.", + "The eight skills are on-demand operations, not a requirement to run every web tool or activate every provider." + ], + "source_paths": [ + "docs/ecosystem/tavily-receipt.json" + ], + "next_gap": "Attach the intended-host native CLI acceptance and fresh Codex/Claude skill discovery evidence, then make an explicit component/adoption decision.", + "lifecycle": { + "source_path": "blueprints/token-native-focus/saturation-audit.json", + "scope": "No selected component lifecycle is asserted by this source-review entry.", + "unknown": "Native CLI integration and applicable lifecycle stages remain pending for the current intended-host adoption.", + "stage_refs": [] + }, + "supersedes": [] + } + ] +} diff --git a/catalogs/foundation/manifest.json b/catalogs/foundation/manifest.json new file mode 100644 index 000000000..4c5a1e827 --- /dev/null +++ b/catalogs/foundation/manifest.json @@ -0,0 +1,244 @@ +{ + "schema_version": 1, + "catalog_id": "foundation", + "checked_at": "2026-09-20", + "scope": "General native engineering, research, documentation, applications, workers, observation and recovery. FOUNDATION is a capability selection over canonical evidence, separate from the US-equities domain catalog.", + "limitations": [ + "Historical receipts qualify their named host, input and operation only; this catalog does not run or certify a new host.", + "Component pins and original evidence claims remain canonical; discoveries, source review, deployment and successful execution are distinct.", + "The broad repository union remains shared research inventory at catalogs/us-equities/decision-index.json; it is not an installation or adoption list." + ], + "canonical_sources": { + "components": "manifests/stack.json", + "evidence": "manifests/evidence.json", + "lifecycle": "blueprints/token-native-focus/saturation-audit.json", + "shared_research_inventory": "catalogs/us-equities/decision-index.json" + }, + "decisions_file": "catalogs/foundation/decisions.json", + "layers": [ + { + "id": "native-clients", + "title": "Native clients", + "purpose": "Run ordinary coding, research and review through locally signed-in native clients.", + "selection": "Codex and Claude keep native accounts, model selection, caching and compaction.", + "activation": "Use the intended native client and inspect its loaded project tools; new process defaults require a fresh session.", + "lifecycle_scope": "Dated native source retrieval, process environment and scoped session continuation passed; host-wide restart recovery is separate.", + "next_gap": "Bind fresh-session activation and resumed effects to the next target host without repeating accepted model trials." + }, + { + "id": "instructions-skills", + "title": "Instructions and skills", + "purpose": "Keep project rules short and load detailed task procedures on demand.", + "selection": "Canonical project instructions plus selected upstream skills; reference validation is optional.", + "activation": "Load only the skill needed for the requested operation; repository discovery never activates every skill.", + "lifecycle_scope": "Selected skill format and renderer checks exist; source guidance has no executable lifecycle.", + "next_gap": "Check the target client actually discovers a newly selected skill before claiming integration." + }, + { + "id": "workers", + "title": "Workers and task ownership", + "purpose": "Delegate bounded independent work with an actual base, owned paths and independent acceptance.", + "selection": "Native workers first; Beads only when a dependency-aware queue helps.", + "activation": "One coordinator integrates; each writing worker uses its own worktree and concise task contract.", + "lifecycle_scope": "One native child repair and scoped companion backend passed; cancellation/crash/resume remains broader than a successful child task.", + "next_gap": "Exercise cancellation, abrupt failure and resume of an owned writing worker with external-effect reconciliation." + }, + { + "id": "isolation", + "title": "Isolation", + "purpose": "Bound filesystem, network, checkout and shared-resource ownership.", + "selection": "Git worktrees for edits; optional native sandbox for a task requiring enforced restrictions.", + "activation": "Assign ownership before writes and use supported OS permissions for enforcement; prose is not a sandbox.", + "lifecycle_scope": "Disposable worktree operations and filesystem/HTTP allow-deny fixtures passed; worktrees do not isolate accounts or services.", + "next_gap": "Qualify only the required platform/network boundary; broader sandbox escape and crash isolation are unknown." + }, + { + "id": "code-navigation", + "title": "Code navigation", + "purpose": "Find exact implementations, symbols, references and structural relationships.", + "selection": "Known source or exact search first; Serena, ast-grep, static graph or scoped jCodeMunch when useful.", + "activation": "Choose one fitting retrieval lane and read original implementation before edits or correctness decisions.", + "lifecycle_scope": "Recorded exact source/symbol checks passed; language coverage and index freshness stay project-specific.", + "next_gap": "Test the actual target language and a changed/deleted symbol after moving to a new project." + }, + { + "id": "document-retrieval", + "title": "Documents and ingestion", + "purpose": "Retrieve bounded, source-attributed documentation and supported document text.", + "selection": "Scoped QMD BM25, selected Context Hub documentation, MarkItDown HTML and Poppler PDF fixtures.", + "activation": "Name the collection/corpus, refresh changed files, search then read the selected source.", + "lifecycle_scope": "Lexical retrieval and designed PDF/text fixtures passed with retained misses; arbitrary OCR/layout is unknown.", + "next_gap": "Freeze a representative new corpus and negative queries before claiming wider retrieval quality." + }, + { + "id": "semantic-rag", + "title": "Semantic code retrieval", + "purpose": "Retrieve conceptual code using the selected project index and local embeddings.", + "selection": "SocratiCode with Qdrant and the accepted local vLLM embedding runtime.", + "activation": "Activate only the selected project and models; do not index unrelated folders or change the accepted runtime for release novelty.", + "lifecycle_scope": "Native source retrieval and add/change/delete persistence passed; a newer GPU runtime startup failed and remains failed.", + "next_gap": "Retain the accepted environment and collect changed-runtime/GPU acceptance only when a concrete need warrants it." + }, + { + "id": "durable-memory", + "title": "Durable memory", + "purpose": "Preserve scoped decisions, approved durable knowledge and recoverable handoffs across clients.", + "selection": "One ai-memory store as cross-harness memory of record.", + "activation": "Retrieve relevant history when needed; durable writes require explicit intent and recalled text never authorizes actions.", + "lifecycle_scope": "Synthetic migration, scope, restart, backup and empty-target restore passed; capture is bounded, not a full transcript.", + "next_gap": "Establish independent-host/key recovery and the target host production activation separately." + }, + { + "id": "web-research", + "title": "Web research", + "purpose": "Find current primary sources and inspect selected web content.", + "selection": "Native browser and bounded literature retrieval; Tavily retained as a separate integration candidate in this view.", + "activation": "Use an existing authenticated route on demand; load only the research operation needed.", + "lifecycle_scope": "Local browser and selected paper retrieval have dated acceptance; the pending Tavily native CLI integration receipt must be bound explicitly.", + "next_gap": "Complete the intended-host Tavily CLI and eight-skill activation receipt without inferring acceptance from source review." + }, + { + "id": "token-efficiency", + "title": "Context and usage efficiency", + "purpose": "Reduce task context only while preserving required facts, source recovery and answer quality.", + "selection": "Known focused reads, RTK, Context Mode, scoped jCodeMunch, guarded Headroom and selected representations.", + "activation": "Choose the cheapest sufficient lane for each artifact; preserve raw failure output and native caching.", + "lifecycle_scope": "Exact artifact comparisons and mixed native trial results are retained; heuristic counters and consumed usage are separate.", + "next_gap": "Measure complete matched attempts only for a decision-changing optimization; do not infer causal lifetime savings." + }, + { + "id": "quality-evaluation", + "title": "Quality and evaluation", + "purpose": "Use deterministic oracles and independent review to accept the actual requested behavior.", + "selection": "Project tests, browser acceptance, promptfoo fixtures, shell review and structural diffs as applicable.", + "activation": "Freeze useful acceptance and negative cases before a substantive change; reuse matching passing evidence.", + "lifecycle_scope": "Selected deterministic fixtures and browser flows passed; no universal model-quality or production guarantee follows.", + "next_gap": "Add a representative failure oracle when the next task exposes an untested behavior." + }, + { + "id": "ci-supply-chain", + "title": "CI and supply chain", + "purpose": "Check published artifacts, workflow permissions, secret controls and scoped dependency identity.", + "selection": "Native publication checks, zizmor, gitleaks and scoped Syft inventory.", + "activation": "Run the relevant offline checks and current CI for changed inputs; keep private state out of artifacts.", + "lifecycle_scope": "Workflow/secret negative fixtures and clean native token-tool CI passed; inventory is not a vulnerability or provenance verdict.", + "next_gap": "Qualify changed distribution inputs and applicable hosted jobs; no broad vulnerability assurance is accepted." + }, + { + "id": "scheduling-supervision", + "title": "Scheduling and supervision", + "purpose": "Schedule owned work, bound process lifetime and resume unfinished steps deliberately.", + "selection": "Dagu for selected workflows and Linux user-manager supervision for owned process trees.", + "activation": "Use explicit task/service ownership, bounded retries and independent state/effect checks.", + "lifecycle_scope": "Local descendant termination and Dagu cancel/retry/SSH continuation passed; full service reboot and provider cancellation remain unknown.", + "next_gap": "Test an owned scheduled service across reboot and reconcile pending native worker effects before resubmission." + }, + { + "id": "hosting-services", + "title": "Application and service hosting", + "purpose": "Build, run and inspect recoverable local application and MCP services.", + "selection": "Locked Next/React/FastAPI/PostgreSQL fixture; platform-specific container and MCP tools only as needed.", + "activation": "Select the target host recipe, explicit service owner and isolated prefix; external hosting is a separate action.", + "lifecycle_scope": "Typed API/browser flows, migration reversal and rows after restart passed on named hosts; production auth and cloud deployment are unqualified.", + "next_gap": "Qualify independent database restore and production-specific access requirements before broader hosting claims." + }, + { + "id": "recovery-portability", + "title": "Recovery and portability", + "purpose": "Retain pinned inputs and prove usable restore, continuity and cleanup at the intended boundary.", + "selection": "Owned lifecycle recipes, Restic, native application backups and native session resume.", + "activation": "Use exact snapshots and empty restore targets; keep keys/account sign-ins private and separate from the checkout.", + "lifecycle_scope": "Same-host restores and individual session/job continuations passed; a whole-stack independent-host disaster recovery has not.", + "next_gap": "Run independent off-host restore with separately available key recovery and affected service acceptance." + }, + { + "id": "observation-inference", + "title": "Observation and optional inference", + "purpose": "Observe bounded native outcomes and usage; trial local inference or routing only against a concrete gap.", + "selection": "Loopback native telemetry and scoped history; local model and gateway remain optional trials.", + "activation": "Preserve writer/task attribution, account boundaries and native default routes; dashboards do not grant operator authority.", + "lifecycle_scope": "Recorded telemetry reconciles scoped usage; HUD live rendering and exact-model gateway inference remain incomplete.", + "next_gap": "Resolve only the selected unknown attribution, interactive rendering or provider compatibility condition before retrying." + } + ], + "domain_boundary": [ + { + "component_id": "lean", + "catalog": "catalogs/us-equities/README.md", + "scope": "Historical execution engine and market-data assumptions belong to TRADING." + }, + { + "component_id": "alpaca-py", + "catalog": "catalogs/us-equities/README.md", + "scope": "Broker/data SDK contract and observation acceptance belong to TRADING; no order authority is conveyed." + }, + { + "component_id": "skfolio", + "catalog": "catalogs/us-equities/README.md", + "scope": "Only chronological financial splitter/control evidence is accepted; portfolio optimization is not a general foundation capability." + }, + { + "component_id": "edgartools", + "catalog": "catalogs/us-equities/README.md", + "scope": "SEC acquisition and filing provenance belong to the financial data domain." + }, + { + "component_id": "duckdb", + "catalog": "catalogs/us-equities/README.md", + "scope": "Current accepted use is financial/synthetic temporal materialization; a general SQL product claim requires its own workload acceptance." + }, + { + "component_id": "pandas", + "catalog": "catalogs/us-equities/README.md", + "scope": "Current accepted use is exact timestamp parsing and chronological financial controls, not blanket dataframe acceptance." + } + ], + "top_gaps": [ + { + "id": "catalog-capability-separation", + "priority": 1, + "status": "addressed_in_catalog", + "scope": "General foundation capabilities now have an explicit home and scoped claims; the broad research union keeps its existing path.", + "next_action": "Maintain these capability joins when a decision changes; do not migrate or adopt every discovery by directory placement.", + "source_paths": [ + "catalogs/foundation/manifest.json", + "catalogs/foundation/decisions.json", + "catalogs/us-equities/decision-index.json" + ] + }, + { + "id": "worker-cancellation-crash-resume", + "priority": 2, + "status": "partial", + "scope": "Native child repair, local process-tree termination and individual session/job resume are accepted only for their fixtures; combined worker crash and external-effect recovery remains open.", + "next_action": "Freeze one owned writing-worker fixture and test cancellation, abrupt crash and same-task resume with single-effect assertions.", + "source_paths": [ + "blueprints/convergence-practice/native-worker/README.md", + "blueprints/convergence-practice/native-recovery/README.md", + "blueprints/us-equities/worker-supervision/README.md" + ] + }, + { + "id": "offhost-keys-and-service-reboot", + "priority": 3, + "status": "open", + "scope": "Same-host backup/restore and service stop/start do not establish independent off-host key recovery or scheduled-service continuity after reboot.", + "next_action": "Exercise a separately accessible key and exact snapshot on an independent host, then qualify the selected owned scheduled service after reboot.", + "source_paths": [ + "adoption/lifecycle.md", + "blueprints/convergence-practice/wsl-restore/README.md", + "blueprints/convergence-practice/wsl-transport-recovery/README.md" + ] + } + ], + "open_gates": [ + { + "id": "worker-cancellation-crash-resume", + "gap_id": "worker-cancellation-crash-resume" + }, + { + "id": "offhost-keys-and-service-reboot", + "gap_id": "offhost-keys-and-service-reboot" + } + ] +} diff --git a/scripts/validate_foundation.py b/scripts/validate_foundation.py new file mode 100644 index 000000000..317ac305c --- /dev/null +++ b/scripts/validate_foundation.py @@ -0,0 +1,257 @@ +#!/usr/bin/env python3 +"""Validate FOUNDATION capability references offline, without replaying receipts. + +Pins, original claims and lifecycle stage evidence stay in their canonical files. +This checks consistency of the selection, never the truth of a prose assertion. +""" + +from __future__ import annotations + +import argparse +import json +from pathlib import Path + +try: + from scripts.validate_catalogs import ( + InvalidCatalog, Validator, dated, enum, https, object_value, require, + sequence, strings, text, + ) +except ModuleNotFoundError: + from validate_catalogs import ( + InvalidCatalog, Validator, dated, enum, https, object_value, require, + sequence, strings, text, + ) + + +ROOT = Path(__file__).resolve().parents[1] +MANIFEST = "catalogs/foundation/manifest.json" +DECISIONS = "catalogs/foundation/decisions.json" +SOURCES = { + "components": "manifests/stack.json", + "evidence": "manifests/evidence.json", + "lifecycle": "blueprints/token-native-focus/saturation-audit.json", + "shared_research_inventory": "catalogs/us-equities/decision-index.json", +} +LAYERS = { + "native-clients", "instructions-skills", "workers", "isolation", "code-navigation", + "document-retrieval", "semantic-rag", "durable-memory", "web-research", + "token-efficiency", "quality-evaluation", "ci-supply-chain", "scheduling-supervision", + "hosting-services", "recovery-portability", "observation-inference", +} +STAGES = {"install", "use", "persistence", "restart", "cleanup", "recovery"} +STATUSES = { + "accepted_within_scope", "observed_installed", "partial_acceptance", + "documented_not_replayed", "not_established", "not_applicable", +} +EXECUTION = {"native_model_e2e", "native_cli_e2e", "artifact_measurement"} + + +def fields(value, expected, label): + object_value(value, label) + require(not value.keys() - expected, label, f"unknown fields: {sorted(value.keys() - expected)}") + require(not expected - value.keys(), label, f"missing fields: {sorted(expected - value.keys())}") + + +def indexed(rows, key, label): + result = {} + for row in sequence(rows, label): + object_value(row, label) + identifier = text(row.get(key), f"{label}.{key}") + require(identifier not in result, label, f"duplicate ID {identifier}") + result[identifier] = row + return result + + +def source_paths(values, validator, label): + for path in strings(values, label): + validator.path(path, label) + + +def validate_foundation(root: Path) -> dict: + validator = Validator(root) + manifest = validator.load(MANIFEST) + fields(manifest, {"schema_version", "catalog_id", "checked_at", "scope", "limitations", + "canonical_sources", "decisions_file", "layers", "domain_boundary", "top_gaps", "open_gates"}, MANIFEST) + validator.header(manifest, MANIFEST) + require(manifest["catalog_id"] == "foundation", MANIFEST, "catalog_id must be foundation") + text(manifest["scope"], "manifest.scope") + strings(manifest["limitations"], "manifest.limitations") + require(manifest["canonical_sources"] == SOURCES, "canonical_sources", "use canonical sources without copying pins or receipts") + require(manifest["decisions_file"] == DECISIONS, "decisions_file", "use the FOUNDATION decisions file") + for path in SOURCES.values(): + validator.path(path, "canonical_sources") + components = indexed(validator.load(SOURCES["components"]).get("components"), "id", "components") + receipts = indexed(validator.load(SOURCES["evidence"]).get("receipts"), "id", "receipts") + lifecycle = indexed(validator.load(SOURCES["lifecycle"]).get("components"), "component_id", "lifecycle") + + layers = indexed(manifest["layers"], "id", "layers") + require(set(layers) == LAYERS, "layers", "must contain exactly the 16 required layers") + for identifier, layer in layers.items(): + fields(layer, {"id", "title", "purpose", "selection", "activation", "lifecycle_scope", "next_gap"}, identifier) + for key, value in layer.items(): + text(value, f"{identifier}.{key}") + + domain = {} + for row in sequence(manifest["domain_boundary"], "domain_boundary", nonempty=False): + fields(row, {"component_id", "catalog", "scope"}, "domain_boundary") + identifier = text(row["component_id"], "domain_boundary.component_id") + require(identifier in components, "domain_boundary", f"unknown component {identifier}") + require(identifier not in domain, "domain_boundary", "duplicate component") + validator.path(row["catalog"], "domain_boundary.catalog") + text(row["scope"], "domain_boundary.scope") + domain[identifier] = row + + gaps = indexed(manifest["top_gaps"], "id", "top_gaps") + priorities = [] + for gap in gaps.values(): + fields(gap, {"id", "priority", "status", "scope", "next_action", "source_paths"}, "top_gaps") + require(type(gap["priority"]) is int, "top_gaps.priority", "expected integer priority") + priorities.append(gap["priority"]) + enum(gap["status"], {"open", "partial", "addressed_in_catalog"}, "top_gaps.status") + text(gap["scope"], "top_gaps.scope") + text(gap["next_action"], "top_gaps.next_action") + source_paths(gap["source_paths"], validator, "top_gaps.source_paths") + require(sorted(priorities) == [1, 2, 3], "top_gaps", "exactly three ranked gaps required") + gate_ids, gap_ids = set(), set() + for gate in sequence(manifest["open_gates"], "open_gates", nonempty=False): + fields(gate, {"id", "gap_id"}, "open_gates") + gate_id = text(gate["id"], "open_gates.id") + gap_id = text(gate["gap_id"], "open_gates.gap_id") + require(gate_id not in gate_ids and gap_id not in gap_ids, "open_gates", "duplicate gate or gap") + require(gap_id in gaps, "open_gates", "unknown gap") + gate_ids.add(gate_id) + gap_ids.add(gap_id) + require(gap_ids == {identifier for identifier, gap in gaps.items() if gap["status"] != "addressed_in_catalog"}, + "open_gates", "must reference exactly the unfinished gaps") + + document = validator.load(DECISIONS) + fields(document, {"schema_version", "checked_at", "scope", "decisions"}, DECISIONS) + validator.header(document, DECISIONS, manifest["checked_at"]) + text(document["scope"], "decisions.scope") + decisions = indexed(document["decisions"], "id", "decisions") + used_layers, used_components, used_receipts, candidates = set(), set(), set(), set() + for identifier, row in decisions.items(): + fields(row, {"id", "capability", "capability_key", "checked_at", "layer_ids", "selection", "review_status", + "activation", "component_ids", "candidate", "evidence_ids", "evidence_scope", "limitations", + "source_paths", "next_gap", "lifecycle", "supersedes"}, identifier) + for key in ("capability", "capability_key", "activation", "evidence_scope", "next_gap"): + text(row[key], f"{identifier}.{key}") + checked = dated(row["checked_at"], f"{identifier}.checked_at") + require(checked <= dated(manifest["checked_at"], "manifest.checked_at"), identifier, "decision date exceeds manifest") + layer_ids = strings(row["layer_ids"], f"{identifier}.layer_ids") + require(set(layer_ids) <= LAYERS, identifier, "unknown layer") + used_layers.update(layer_ids) + enum(row["selection"], {"default", "conditional", "optional", "trial", "candidate"}, f"{identifier}.selection") + enum(row["review_status"], {"accepted_within_scope", "partial_acceptance", "source_review", "discovery", "not_established"}, + f"{identifier}.review_status") + component_ids = strings(row["component_ids"], f"{identifier}.component_ids", nonempty=False) + require(set(component_ids) <= components.keys(), identifier, "unknown component") + require(not set(component_ids) & domain.keys(), identifier, "component belongs to domain boundary") + evidence_ids = strings(row["evidence_ids"], f"{identifier}.evidence_ids", nonempty=False) + require(set(evidence_ids) <= receipts.keys(), identifier, "unknown evidence") + strings(row["limitations"], f"{identifier}.limitations") + source_paths(row["source_paths"], validator, f"{identifier}.source_paths") + + candidate = row["candidate"] + if row["selection"] == "candidate": + fields(candidate, {"id", "repository"}, f"{identifier}.candidate") + candidate_id = text(candidate["id"], f"{identifier}.candidate.id") + require(candidate_id not in candidates and candidate_id not in components, identifier, "candidate identity duplicates adopted component or candidate") + https(candidate["repository"], f"{identifier}.candidate.repository") + require(not component_ids and not evidence_ids and row["review_status"] in {"discovery", "source_review", "not_established"}, + identifier, "candidate cannot assert adopted components or native acceptance") + candidates.add(candidate_id) + else: + require(candidate is None and bool(component_ids), identifier, "selected capability needs component IDs, not a candidate") + require(bool(evidence_ids), identifier, "selected capability needs evidence references") + + bound_components = set() + for evidence_id in evidence_ids: + receipt = receipts[evidence_id] + validator.path(receipt.get("path"), f"{identifier}.evidence.{evidence_id}") + receipt_components = set(strings(receipt.get("component_ids"), f"{evidence_id}.component_ids")) + overlap = set(component_ids) & receipt_components + require(bool(overlap), identifier, f"unrelated evidence {evidence_id}") + bound_components.update(overlap) + text(receipt.get("claim"), f"{evidence_id}.claim") + strings(receipt.get("limitations"), f"{evidence_id}.limitations") + require(set(component_ids) <= bound_components, identifier, "component without related evidence") + if row["review_status"] == "accepted_within_scope": + require(any(receipts[evidence_id].get("kind") in EXECUTION for evidence_id in evidence_ids), + identifier, "native acceptance requires execution evidence, not inventory alone") + + stages = row["lifecycle"] + fields(stages, {"source_path", "scope", "unknown", "stage_refs"}, f"{identifier}.lifecycle") + require(stages["source_path"] == SOURCES["lifecycle"], identifier, "use canonical lifecycle source") + text(stages["scope"], f"{identifier}.lifecycle.scope") + text(stages["unknown"], f"{identifier}.lifecycle.unknown") + seen_stages = set() + for stage in sequence(stages["stage_refs"], f"{identifier}.stage_refs", nonempty=bool(component_ids)): + fields(stage, {"component_id", "stage", "status"}, f"{identifier}.stage_refs") + require(stage["component_id"] in component_ids and stage["component_id"] in lifecycle, + identifier, "invalid lifecycle component") + enum(stage["stage"], STAGES, f"{identifier}.lifecycle stage") + enum(stage["status"], STATUSES, f"{identifier}.lifecycle status") + key = (stage["component_id"], stage["stage"]) + require(key not in seen_stages, identifier, "duplicate lifecycle stage") + seen_stages.add(key) + canonical = object_value(lifecycle[stage["component_id"]].get("lifecycle_stages"), "canonical lifecycle") + native_stage = object_value(canonical.get(stage["stage"]), "canonical lifecycle stage") + require(stage["status"] == native_stage.get("status"), identifier, "lifecycle status differs from canonical scoped evidence") + text(native_stage.get("scope"), "canonical lifecycle scope") + for path in strings(native_stage.get("evidence_refs"), "canonical lifecycle evidence", nonempty=False): + validator.path(path, "canonical lifecycle evidence") + require(set(component_ids) <= {key[0] for key in seen_stages}, identifier, "component missing lifecycle reference") + if row["review_status"] == "accepted_within_scope": + accepted_components = {stage["component_id"] for stage in stages["stage_refs"] + if stage["status"] == "accepted_within_scope"} + require(set(component_ids) <= accepted_components, identifier, + "capability acceptance requires a canonical accepted stage for each component") + if candidate is not None: + require(not seen_stages, identifier, "candidate lifecycle must remain pending") + used_components.update(component_ids) + used_receipts.update(evidence_ids) + + require(used_layers == LAYERS, "decisions", "every required layer needs a capability or explicit pending decision") + for identifier, row in decisions.items(): + targets = set() + for supersession in sequence(row["supersedes"], f"{identifier}.supersedes", nonempty=False): + fields(supersession, {"decision_id", "scope", "reason"}, f"{identifier}.supersedes") + target = text(supersession["decision_id"], f"{identifier}.supersedes.decision_id") + require(target in decisions, identifier, "unknown superseded decision") + require(target != identifier and target not in targets, identifier, "self or duplicate supersession") + targets.add(target) + text(supersession["scope"], f"{identifier}.supersedes.scope") + text(supersession["reason"], f"{identifier}.supersedes.reason") + previous = decisions[target] + require(previous["capability_key"] == row["capability_key"] + and set(previous["component_ids"]) == set(row["component_ids"]) + and previous["candidate"] == row["candidate"], identifier, "supersession must retain the same capability and component scope") + require(dated(previous["checked_at"], "superseded date") < dated(row["checked_at"], "decision date"), + identifier, "superseded decision must be earlier; cycles forbidden") + + return {"layers": len(layers), "decisions": len(decisions), "foundation_components": len(used_components), + "domain_components": len(domain), "evidence_receipts": len(used_receipts), "candidates": len(candidates)} + + +def main(argv=None): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--root", type=Path, default=ROOT) + parser.add_argument("--json", action="store_true", dest="as_json") + args = parser.parse_args(argv) + try: + counts = validate_foundation(args.root) + report = {"ok": True, "counts": counts, "errors": []} + except (InvalidCatalog, OSError, UnicodeError, ValueError) as error: + report = {"ok": False, "counts": {}, "errors": [str(error)]} + if args.as_json: + print(json.dumps(report, indent=2)) + elif report["ok"]: + print("FOUNDATION catalog valid: " + ", ".join(f"{key}={value}" for key, value in counts.items())) + else: + print("FOUNDATION catalog invalid: " + "; ".join(report["errors"])) + return 0 if report["ok"] else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_foundation_catalog.py b/tests/test_foundation_catalog.py new file mode 100644 index 000000000..b0a86b748 --- /dev/null +++ b/tests/test_foundation_catalog.py @@ -0,0 +1,200 @@ +"""Reject unsupported adoption claims using small, independent public fixtures.""" + +import copy +import json +from pathlib import Path +import subprocess +import sys +import tempfile +import unittest + + +ROOT = Path(__file__).resolve().parents[1] +SCRIPT = ROOT / "scripts/validate_foundation.py" +LAYERS = "native-clients instructions-skills workers isolation code-navigation document-retrieval semantic-rag durable-memory web-research token-efficiency quality-evaluation ci-supply-chain scheduling-supervision hosting-services recovery-portability observation-inference".split() +MANIFEST = "catalogs/foundation/manifest.json" +DECISIONS = "catalogs/foundation/decisions.json" +MATRIX = "blueprints/token-native-focus/saturation-audit.json" + + +class FoundationCatalogTests(unittest.TestCase): + def setUp(self): + temporary = tempfile.TemporaryDirectory() + self.addCleanup(temporary.cleanup) + self.root = Path(temporary.name) + self.manifest = { + "schema_version": 1, "catalog_id": "foundation", "checked_at": "2026-09-20", + "scope": "General engineering fixture on one historical host.", + "limitations": ["No new-host acceptance."], + "canonical_sources": {"components": "manifests/stack.json", "evidence": "manifests/evidence.json", + "lifecycle": MATRIX, "shared_research_inventory": "catalogs/us-equities/decision-index.json"}, + "decisions_file": DECISIONS, + "layers": [{"id": layer, "title": layer, "purpose": "Bounded purpose", "selection": "Selected fixture", + "activation": "Only on demand", "lifecycle_scope": "One use accepted; recovery unknown", + "next_gap": "Exercise recovery on selected host"} for layer in LAYERS], + "domain_boundary": [{"component_id": "domain", "catalog": "catalogs/us-equities/README.md", + "scope": "Specialist example only; not foundation acceptance"}], + "top_gaps": [{"id": f"gap-{i}", "priority": i, "status": "open", "scope": "One scoped gap", + "next_action": "Run a bounded acceptance", "source_paths": ["guide.md"]} for i in (1, 2, 3)], + "open_gates": [{"id": f"gap-{i}", "gap_id": f"gap-{i}"} for i in (1, 2, 3)], + } + self.decision = { + "id": "source-retrieval", "capability": "Retrieve exact source", "capability_key": "source-retrieval", + "checked_at": "2026-09-20", "layer_ids": LAYERS, + "selection": "default", "review_status": "accepted_within_scope", "activation": "Select the fixture", + "component_ids": ["tool"], "candidate": None, "evidence_ids": ["native"], + "evidence_scope": "One source function on the recorded host", "limitations": ["No arbitrary corpus acceptance"], + "source_paths": ["guide.md"], "next_gap": "Try the selected target corpus", + "lifecycle": {"source_path": MATRIX, "scope": "Native use only", "unknown": "Recovery unestablished", + "stage_refs": [{"component_id": "tool", "stage": "use", "status": "accepted_within_scope"}]}, + "supersedes": [], + } + self.decisions = {"schema_version": 1, "checked_at": "2026-09-20", "scope": "Capability-specific fixture", + "decisions": [self.decision]} + self.write("manifests/stack.json", {"components": [{"id": "tool", "version": "1"}, {"id": "domain", "version": "1"}]}) + self.write("manifests/evidence.json", {"receipts": [{"id": "native", "kind": "native_cli_e2e", "path": "receipt.json", + "component_ids": ["tool"], "claim": "One useful operation", "limitations": ["One host"]}]}) + self.write(MATRIX, {"components": [{"component_id": "tool", "lifecycle_stages": { + "use": {"status": "accepted_within_scope", "scope": "Native use only", "evidence_refs": ["receipt.json"]}, + "recovery": {"status": "not_established", "scope": "Not tested", "evidence_refs": []}}}]}) + for path in ("guide.md", "receipt.json", "catalogs/us-equities/decision-index.json", "catalogs/us-equities/README.md"): + self.write(path, {}) + + def write(self, path, value): + target = self.root / path + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text(json.dumps(value), encoding="utf-8") + + def run_check(self): + self.write(MANIFEST, self.manifest) + self.write(DECISIONS, self.decisions) + result = subprocess.run([sys.executable, str(SCRIPT), "--root", str(self.root), "--json"], + text=True, capture_output=True, check=False) + return result, json.loads(result.stdout) if result.stdout.strip().startswith("{") else {} + + def assert_invalid(self, fragment): + result, report = self.run_check() + self.assertEqual(result.returncode, 1, result.stderr or result.stdout) + self.assertIn(fragment, " ".join(report.get("errors", []))) + + def test_valid_catalog_resolves_historical_claims_without_executing_them(self): + result, report = self.run_check() + self.assertEqual(result.returncode, 0, result.stderr or result.stdout) + self.assertEqual(report["counts"], {"layers": 16, "decisions": 1, "foundation_components": 1, + "domain_components": 1, "evidence_receipts": 1, "candidates": 0}) + + def test_duplicate_decision_ids_fail(self): + self.decisions["decisions"].append(copy.deepcopy(self.decision)) + self.assert_invalid("duplicate") + + def test_missing_or_unknown_layers_fail(self): + self.manifest["layers"].pop() + self.assert_invalid("16 required layers") + self.setUp() + self.decision["layer_ids"] = ["imaginary-layer"] + self.assert_invalid("unknown layer") + + def test_nonexistent_component_and_unrelated_receipt_fail(self): + self.decision["component_ids"] = ["missing"] + self.assert_invalid("unknown component") + self.setUp() + self.write("manifests/evidence.json", {"receipts": [{"id": "native", "kind": "native_cli_e2e", + "path": "receipt.json", "component_ids": ["domain"], "claim": "Different use", "limitations": ["Narrow"]}]}) + self.assert_invalid("unrelated evidence") + + def test_unknown_receipt_and_missing_evidence_file_fail(self): + self.decision["evidence_ids"] = ["missing"] + self.assert_invalid("unknown evidence") + self.setUp() + (self.root / "receipt.json").unlink() + self.assert_invalid("file missing") + + def test_missing_scope_and_empty_limitations_fail(self): + for field, value in (("evidence_scope", ""), ("limitations", []), ("activation", ""), ("next_gap", "")): + with self.subTest(field=field): + old = self.decision[field] + self.decision[field] = value + self.assert_invalid(field) + self.decision[field] = old + + def test_paths_cannot_escape_follow_symlinks_or_name_missing_files(self): + (self.root / "linked.md").symlink_to(self.root / "guide.md") + for path, message in (("../guide.md", "confined"), ("linked.md", "symlinks"), ("absent.md", "file missing")): + with self.subTest(path=path): + self.decision["source_paths"] = [path] + self.assert_invalid(message) + + def test_unknown_lifecycle_status_or_promotion_of_unknown_stage_fails(self): + stage = self.decision["lifecycle"]["stage_refs"][0] + stage["status"] = "fully-working" + self.assert_invalid("lifecycle status") + stage.update(stage="recovery", status="accepted_within_scope") + self.assert_invalid("lifecycle status differs") + + def test_native_acceptance_requires_execution_evidence_not_inventory(self): + data = json.loads((self.root / "manifests/evidence.json").read_text()) + data["receipts"][0]["kind"] = "historical_inventory" + self.write("manifests/evidence.json", data) + self.assert_invalid("execution evidence") + + def test_partial_lifecycle_cannot_be_reclassified_as_accepted_capability(self): + data = json.loads((self.root / MATRIX).read_text()) + data["components"][0]["lifecycle_stages"]["use"]["status"] = "partial_acceptance" + self.write(MATRIX, data) + self.decision["lifecycle"]["stage_refs"][0]["status"] = "partial_acceptance" + self.assert_invalid("accepted stage") + + def test_pin_and_receipt_copies_are_rejected(self): + for field, value in (("version", "2.0"), ("source_pin", "a" * 40), ("receipts", [{"claim": "Everything passed"}])): + with self.subTest(field=field): + self.decision[field] = value + self.assert_invalid("unknown fields") + del self.decision[field] + + def test_candidate_cannot_claim_adopted_components_or_native_acceptance(self): + self.decision.update(selection="candidate", review_status="source_review", component_ids=[], evidence_ids=[], + candidate={"id": "new-tool", "repository": "https://github.com/example/new-tool"}) + self.decision["lifecycle"]["stage_refs"] = [] + result, _ = self.run_check() + self.assertEqual(result.returncode, 0, result.stdout) + self.decision["review_status"] = "accepted_within_scope" + self.assert_invalid("candidate") + + def test_domain_components_cannot_be_promoted_by_catalog_placement(self): + self.manifest["domain_boundary"][0]["component_id"] = "tool" + self.assert_invalid("domain boundary") + + def test_open_gates_must_resolve_every_unfinished_gap(self): + self.manifest["open_gates"][0]["gap_id"] = "unknown" + self.assert_invalid("unknown gap") + self.manifest["open_gates"].pop(0) + self.assert_invalid("unfinished gaps") + + def test_supersession_requires_same_capability_and_earlier_date(self): + old = copy.deepcopy(self.decision) + old.update(id="older", checked_at="2026-09-19") + self.decisions["decisions"].append(old) + self.decision["supersedes"] = [{"decision_id": "older", "scope": "Same fixture", "reason": "Later scoped result"}] + result, _ = self.run_check() + self.assertEqual(result.returncode, 0, result.stdout) + old["capability_key"] = "another-capability" + self.assert_invalid("same capability") + old["capability_key"] = self.decision["capability_key"] + old["checked_at"] = "2026-09-20" + self.assert_invalid("earlier") + old["checked_at"] = "2026-09-19" + self.decision["supersedes"][0]["decision_id"] = "absent" + self.assert_invalid("unknown superseded") + + def test_duplicate_json_keys_fail_with_a_machine_readable_error(self): + (self.root / "manifests/stack.json").write_text('{"components":[],"components":[]}') + self.assert_invalid("duplicate key") + + def test_checked_in_catalog_passes(self): + result = subprocess.run([sys.executable, str(SCRIPT), "--root", str(ROOT), "--json"], + text=True, capture_output=True, check=False) + self.assertEqual(result.returncode, 0, result.stderr or result.stdout) + + +if __name__ == "__main__": + unittest.main() From 5c20c71ca3462aa3926ee45b067e5c489458e724 Mon Sep 17 00:00:00 2001 From: seathatflowsinourveins <234074349+seathatflowsinourveins@users.noreply.github.com> Date: Sun, 20 Sep 2026 14:30:09 -0400 Subject: [PATCH 02/15] Add scoped Foundation and Trading catalog views --- docs/ecosystem/template.html | 139 ++++++++++++++++++++++++++++++- scripts/build_ecosystem.py | 94 ++++++++++++++++++++- tests/test_ecosystem_manifest.py | 131 +++++++++++++++++++++++++++++ 3 files changed, 359 insertions(+), 5 deletions(-) diff --git a/docs/ecosystem/template.html b/docs/ecosystem/template.html index 0d82c2c0f..f5b27f656 100644 --- a/docs/ecosystem/template.html +++ b/docs/ecosystem/template.html @@ -18,6 +18,8 @@ #token-topic th:nth-child(1){width:15%}#token-topic th:nth-child(2){width:25%}#token-topic th:nth-child(3){width:32%}#token-topic th:nth-child(4){width:28%} #token-topic .topic-detail td{padding-top:0;padding-bottom:20px}#token-topic .topic-detail pre{max-width:100%} #token-topic-section{scroll-margin-top:160px} +.navigation{flex-wrap:wrap;column-gap:22px;row-gap:0}.navigation button:last-child{margin-left:0} +.catalog-entries,.catalog-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:18px;margin:0 0 36px}.catalog-entry,.catalog-layer,.catalog-card{min-width:0;border:1px solid var(--line);border-radius:var(--radius);padding:25px;background:var(--white);overflow-wrap:anywhere}.catalog-entry:first-child{background:#e8eddf}.catalog-entry h2{margin:12px 0;font-size:35px}.catalog-entry p,.catalog-layer p,.catalog-card p{font-size:13px;margin:12px 0;color:var(--muted)}.catalog-entry .button{margin-top:15px}.catalog-entry .catalog-count{color:var(--green);font-weight:600}.catalog-layer h3,.catalog-card h3{font-size:20px}.catalog-layer .eyebrow{color:var(--copper);margin-bottom:8px}.catalog-layer .accepted-scope{color:var(--green)}.catalog-gap{border-left:3px solid var(--copper);padding-left:12px;margin:16px 0;font-size:12px}.catalog-gap strong{display:block}.catalog-gap p{margin:5px 0}.catalog-detail{border-top:1px solid var(--line);padding:15px 0 0;margin-top:16px;min-width:0}.catalog-detail p,.catalog-detail li{font-size:12px}.catalog-detail summary,.catalog-detail a{overflow-wrap:anywhere}.catalog-capability{border-top:1px solid var(--line);padding:18px 0 4px}.catalog-capability h4{font-size:15px;margin:0 0 9px}.catalog-capability .badge{font-size:10px}.catalog-sources{display:flex;flex-direction:column;gap:8px;margin:14px 0;font-size:12px}.catalog-facts{display:grid;grid-template-columns:minmax(90px,1fr) minmax(0,2fr);gap:9px 16px;font-size:12px;margin:15px 0}.catalog-facts dt{color:var(--muted)}.catalog-facts dd{margin:0;overflow-wrap:anywhere}.catalog-layer .catalog-detail .catalog-detail{padding-left:12px}.catalog-summary{margin:0 0 22px}.catalog-summary p{font-size:13px;margin-top:10px}.catalog-controls{margin-bottom:20px}.catalog-scope{font-size:12px;color:var(--muted);margin:15px 0 25px}.catalog-empty{padding:30px;border:1px dashed var(--line);border-radius:12px;margin-bottom:30px}.catalog-grid>*{min-width:0}.catalog-card pre{max-width:100%}@media(max-width:800px){.catalog-entries,.catalog-grid{grid-template-columns:1fr}}@media(max-width:670px){.navigation{overflow:visible;column-gap:16px}.catalog-entry,.catalog-layer,.catalog-card{padding:20px}.catalog-facts{grid-template-columns:1fr}.catalog-facts dd{margin-bottom:7px}.catalog-entry h2{font-size:31px}} @@ -26,6 +28,8 @@
native stackECOSYSTEM MANIFEST
Public reference /