From 21774926462f1cdbb09a2ce3c53da15ccf171c3d Mon Sep 17 00:00:00 2001 From: Shay Date: Sat, 16 May 2026 14:51:42 -0700 Subject: [PATCH] docs(adr): resolve Agency + Tool-use scope decisions (ADR-0017, ADR-0018) Pins the two open scope decisions that the capability roadmap (ADR-0016) tagged "Before Phase 3". Both are resolved with explicit ADRs and PROGRESS.md is updated to reflect. ADR-0017 - Agency: responsive-with-axiology - Turn boundary stays responsive (no autonomous initiative, no background agent loop, no inter-turn processes). - IdentityManifold value axes become load-bearing for articulator candidate selection (within a single turn). Goal-directedness lives inside the turn, not across turns. - Replay determinism is the load-bearing constraint that rules out pure agentic loops. - Rejects pure-responsive (would relegate identity to read-only) and pure-agentic (would break trace_hash replay contract). ADR-0018 - Tool use: typed deterministic operators - Operators are pure functions over CORE's typed state. No external IO at this stage (no shells, network, external models). - Operator registry is curated, small, ADR-gated; no plug-in surface, no dynamic loading. - Operators participate in trace_hash so replay stays bit-stable. - Initial operator set lands in Phase 3 v2: transitive_walk over proposition graph + path_recall over vault. Closes Gap 1 + Gap 2 from the inference-closure / multi-step-reasoning / compositionality / cross-domain-transfer v1 findings. - Rules out: generic plugin protocols, LLM-as-judge, approximate retrieval, anything that breaks the exact-CGA / replay contracts in CLAUDE.md. Future extensions recorded but explicitly deferred: calculator (Phase 4+), document retrieval over content-addressed packs, metaphor / narrative / writing-style operators (downstream of cross-domain-transfer literal case working). This unblocks Phase 3 v2 engineering. Next: the transitive_walk + path_recall bundle as a single bounded PR per ADR-0018, plus the trace_hash extension to fold operator invocation records. --- docs/PROGRESS.md | 4 +- docs/decisions/ADR-0017-agency-scope.md | 119 +++++++++++++++++ docs/decisions/ADR-0018-tool-use-scope.md | 151 ++++++++++++++++++++++ 3 files changed, 272 insertions(+), 2 deletions(-) create mode 100644 docs/decisions/ADR-0017-agency-scope.md create mode 100644 docs/decisions/ADR-0018-tool-use-scope.md diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md index b86d7de3..d396f8d2 100644 --- a/docs/PROGRESS.md +++ b/docs/PROGRESS.md @@ -406,7 +406,7 @@ engineering above. | Decision | Status | Deadline | |----------|--------|----------| -| Agency (responsive vs. goal-directed) | Open | Before Phase 3 | -| Tool use (typed deterministic operators) | Open | Before Phase 3 | +| Agency (responsive vs. goal-directed) | **Resolved 2026-05-16 — ADR-0017** (responsive-with-axiology) | Before Phase 3 ✓ | +| Tool use (typed deterministic operators) | **Resolved 2026-05-16 — ADR-0018** (typed deterministic operators, no external IO) | Before Phase 3 ✓ | | Code generation (first-class target) | Open | Before Phase 5 | | Embodiment (sensorium gates) | Open | Phase 5 | diff --git a/docs/decisions/ADR-0017-agency-scope.md b/docs/decisions/ADR-0017-agency-scope.md new file mode 100644 index 00000000..0922165c --- /dev/null +++ b/docs/decisions/ADR-0017-agency-scope.md @@ -0,0 +1,119 @@ +# ADR-0017 — Agency Scope: Responsive-with-Axiology + +**Status:** Accepted +**Date:** 2026-05-16 +**Authors:** Joshua Shay +**Supersedes:** Open Scope Decisions row "Agency (responsive vs. goal-directed)" +in `docs/PROGRESS.md`. + +## Context + +The capability roadmap (ADR-0016) flagged *agency* as an open scope +decision required before Phase 3 engineering begins. Two extreme +positions are available: + +- **Pure responsive.** The system processes one input per turn and + produces one output. No internal aims, no autonomous initiative. + This is what `CognitiveTurnPipeline.run(text)` is today. +- **Pure agentic.** The system maintains internal goals, plans + trajectories that pursue those goals across many turns, and may + initiate actions outside of user-triggered input. Each goal-step + can in principle invoke the system without external prompting. + +A choice between these endpoints shapes how Phase 3 reasoning-depth +work is structured. The transitive-walk and path-recall operators +the inference-closure lane requires can be implemented either way, +but their semantics differ: the agentic reading makes them part of +an internal planner that runs across turns; the responsive reading +makes them per-turn deterministic functions invoked by the +articulator. + +## Decision + +CORE is **responsive-with-axiology**: + +1. **Responsive turn boundary preserved.** Every cognitive turn is + triggered by an external input: a user utterance, a CLI invocation, + or an explicit replay command. The system never initiates a turn + autonomously. No background agent loop runs between turns. + +2. **Axiology is first-class within the turn.** The + `IdentityManifold` and its `ValueAxis` set are not decorative + identity-decoration; they are the value gradient against which + the articulator chooses among candidate articulation surfaces. + When the proposition-graph planner produces multiple valid + completions, the choice is the one that scores highest against + the manifold's value axes. This is goal-directedness *within* a + single responsive turn, not across turns. + +3. **No autonomous initiative.** The system has no `loop()` or + `pursue(goal)` entry point. Anything that looks like long-horizon + pursuit is a sequence of responsive turns chained by the calling + layer, not an internal process. + +4. **Replay determinism is the load-bearing constraint.** The + responsive-with-axiology shape is preserved partly because pure + agentic loops break deterministic replay: the trace_hash contract + in `core/cognition/trace.py` assumes a turn is a deterministic + function of (input, prior-state). Adding non-input-triggered + internal actions would put state changes between turns that + replay cannot reconstruct. + +## Consequences + +- **Phase 3 v2 engineering shape.** The transitive-walk and path- + recall operators (Gap 1 and Gap 2 in + `evals/inference_closure/gaps.md`) are **per-turn deterministic + functions**, not background processes. They are invoked + synchronously by the articulator during a single turn. No turn- + spanning planner is required to close the Phase 3 inference-depth + lanes. + +- **IdentityManifold axes become load-bearing.** Today the axes are + partially decorative (the empirical investigation in commit + `86ef117` showed `identity_score.alignment = 1.0` universally + because no candidate-selection step actually consults them). + Under this ADR, the next refinement of articulator candidate + selection should consult the axes. This is also the + load-bearing path to making fix #3 of the adversarial-identity + defense work geometrically. + +- **No goal-stack data structure.** CORE will not gain a + `Goal`, `Plan`, or `Pursuit` typed object as part of Phase 3. + Anything that looks like a multi-step goal is the user explicitly + asking for multiple responsive turns. + +- **Self-explanation remains responsive.** The forthcoming + `core/cognition/explain.py` module (Gap 3 in + `evals/introspection/gaps.md`) is invoked on a turn-id; it does + not introspect autonomously. + +- **Persona / character work is axiology-side, not agency-side.** + `persona/motor.py` shapes articulation output within the + responsive turn. It does not run between turns. + +## Rejected alternatives + +- **Pure responsive (no axiology).** Rejected because the + `IdentityManifold` already exists as an architectural commitment + (ADR-0010) and the adversarial-identity defense work explicitly + depends on axes being able to *shape* behaviour, not just be + measured. Pure responsive would relegate identity to read-only + evidence, which conflicts with ADR-0010's "identity is + inalienable" claim. + +- **Pure agentic.** Rejected because it breaks the deterministic + replay contract. CORE's value proposition over frontier models is + partly that any turn can be replayed bit-for-bit; an autonomous + inter-turn process makes that contract unenforceable. Also + rejected on philosophical grounds: agency as autonomous pursuit + is not what CORE claims to be. CORE is a deterministic cognitive + engine, not an autonomous agent. + +## Verification + +- Phase 3 v2 work on Gaps 1+2 is scoped as per-turn deterministic + operators (see ADR-0018). +- No new turn-spanning processes are introduced in Phase 3. +- Replay determinism contracts in `tests/test_determinism_proofs.py` + continue to pass for all multi-turn scenarios. diff --git a/docs/decisions/ADR-0018-tool-use-scope.md b/docs/decisions/ADR-0018-tool-use-scope.md new file mode 100644 index 00000000..faa93b59 --- /dev/null +++ b/docs/decisions/ADR-0018-tool-use-scope.md @@ -0,0 +1,151 @@ +# ADR-0018 — Tool Use Scope: Typed Deterministic Operators + +**Status:** Accepted +**Date:** 2026-05-16 +**Authors:** Joshua Shay +**Supersedes:** Open Scope Decisions row "Tool use (typed deterministic +operators)" in `docs/PROGRESS.md`. +**Depends on:** ADR-0017 (Agency Scope). + +## Context + +ADR-0016 flagged *tool use* as an open scope decision required +before Phase 3. The capability roadmap (Phase 3 work items) notes +that multi-step reasoning *may* benefit from operator delegation +(`docs/capability_roadmap.md`). Phase 3 v1 evidence +(`evals/inference_closure/gaps.md` Gap 1 + Gap 2, +`evals/multi_step_reasoning/gaps.md`) confirms this: closing the +inference-depth gaps requires a `transitive_walk` operator over the +proposition graph and a `path_recall` operator over the vault. + +The question is what shape such operators take in CORE. Three +positions are available: + +- **No tools.** Reasoning depth is implemented inline in the + articulator and field-propagate machinery. No first-class + operator surface. +- **External tools.** CORE invokes external services (calculator, + search, code execution, shell) through a generic tool-use + protocol. +- **Typed deterministic operators.** CORE exposes a small, + curated set of pure-function operators over its own typed state + (proposition graph, vault, field state). No external IO. Each + operator is invoked synchronously inside a responsive turn (per + ADR-0017). + +## Decision + +CORE adopts **typed deterministic operators**: + +1. **Operators are pure functions over CORE's typed state.** Each + operator takes typed inputs (proposition-graph nodes, vault + entries, field versors, relation predicates) and returns typed + outputs. No side effects beyond the per-turn deterministic + record. + +2. **No external IO at this stage.** CORE will not invoke shells, + network endpoints, file IO outside the existing pack/vault + contracts, or other models. External tool integration is + deferred to a later phase and would require its own ADR. + +3. **Operator registry is curated and small.** Adding an operator + is a deliberate design act with an ADR-level decision. No + plug-in surface; no dynamic operator loading; no caller-supplied + operators. The deterministic-replay contract requires the + operator set to be a fixed, versioned part of the build. + +4. **Operators participate in trace_hash.** When an operator is + invoked during a turn, its name, inputs, and outputs are folded + into `trace_hash` so replay is bit-for-bit reproducible. This + is the mechanical guarantee that makes operators safe to add. + +5. **Operators are invoked by the articulator inside one turn.** + Per ADR-0017, no operator runs autonomously between turns. The + articulator decides whether to invoke an operator based on the + intent classification and proposition-graph shape produced for + the current turn. + +## Initial operator set (Phase 3 v2) + +Two operators land together as the bounded Phase 3 v2 engineering +work that closes inference-closure Gap 1 + Gap 2: + +- **`transitive_walk(graph, head, relation, max_hops) -> + list[Node]`** + Deterministic traversal of the proposition graph from `head` + following only edges labeled `relation`. Returns the path of + visited nodes. Bounded by `max_hops` (initial cap: 5; see + `evals/multi_step_reasoning/contract.md`). No approximate + search. Empty path is a valid result. + +- **`path_recall(vault, entity, relation_chain) -> + list[VaultEntry]`** + Returns vault entries that participate in the named relation + chain starting from `entity`. Uses the existing exact-CGA + inner product for entity matching; no approximate / HNSW / + ANN substitution permitted (per CLAUDE.md). + +Both operators are pure functions with no global state. Both +produce outputs that are themselves addressable in the proposition +graph and vault, so their results round-trip through the existing +pipeline. + +## What this rules out + +- **Generic plugin protocols (MCP-style).** CORE does not become a + host for external tools. The strict typing and replay-determinism + contracts forbid arbitrary capability surfaces. +- **LLM-as-judge / LLM-as-tool patterns.** No operator may call out + to a stochastic model. +- **Approximate retrieval / search operators.** Per CLAUDE.md + ("Vault recall is exact and deterministic. Do not add cosine + similarity, HNSW, ANN indexes, or approximate recall to the + runtime path."), search-shaped operators must remain exact. + +## Consequences + +- **Phase 3 v2 has a well-defined shape.** The two-operator bundle + above is the unit of engineering work. It is small, testable, + and replay-safe by design. +- **Operator-aware trace hashing.** `core/cognition/trace.py` will + need a small extension to fold operator invocation records into + the hash. This is one of the bounded design tasks inside the + Phase 3 v2 work. +- **Articulator gains an operator-call site.** `generate/realizer.py` + and/or `generate/graph_planner.py` learn to decide *whether* to + invoke an operator based on intent + graph shape. This decision + itself is deterministic — no learned policy. +- **No operator-registry hot path.** Operator lookup is at the + import-time level, not the per-turn level. The operator set is + effectively part of the build. + +## Future extensions (recorded so they're not forgotten) + +When (and if) external IO becomes scoped: + +- **Calculator** (pure-function over typed numerics) is the + cleanest first external operator candidate. Still typed, + still deterministic, no network. Probably Phase 4 or later. +- **Document retrieval** over curated packs (not the open web) + could become typed if the corpus is content-addressed and the + result is bit-stable. +- **Search / code execution / shell** are out of scope for the + foreseeable future. They break replay determinism and the + trust-boundary discipline in CLAUDE.md. + +Metaphor, narrative, and writing-style work (raised in 2026-05-16 +session, recorded in `evals/compositionality/gaps.md` and +`evals/cross_domain_transfer/gaps.md`) live under this ADR's +operator umbrella if they ever land: a metaphor operator is a +typed deterministic function over the proposition graph plus a +selectivity filter, not an external capability. + +## Verification + +- The two Phase 3 v2 operators land with unit tests showing + replay-bit-stability. +- `trace_hash` extension passes determinism tests in + `tests/test_determinism_proofs.py`. +- All inference-closure / multi-step-reasoning / compositionality / + cross-domain-transfer lanes are re-scored after the operator + bundle lands.