From 213eb84cfb74187da052e3923ac72d27395fa4f3 Mon Sep 17 00:00:00 2001 From: Andy Dixon Date: Sun, 30 Aug 2026 22:13:58 +0100 Subject: [PATCH] plan: volition, planning and cognitive research (v0.3) Reconcile the v0.3 specification with the 0.2 architecture: what exists, what is missing and what conflicts with the new invariants (forks copying policies), then the design, migrations, security implications, tests, documentation and order of work. --- PLAN.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/PLAN.md b/PLAN.md index c5e6e0b..2293636 100644 --- a/PLAN.md +++ b/PLAN.md @@ -304,3 +304,90 @@ Each commit is independently revertible; migrations are additive with down scrip | 25 | Final deliverable | done | f43495c (`docs/epistemics.md`) | Every code commit passed `go test -race ./...`, `go vet`, staticcheck, gosec (G104 excluded) and govulncheck. Remaining limitations are listed in `docs/epistemics.md` §7. + +--- + +## 8. Volition, planning and cognitive research (v0.3, started 2026-09-15) + +Specification: `V0.3-prompt.md` (untracked user file, left in place). Baseline: `v0.2.0` (`a998b81`), `go test -race ./...` run before any change. + +### 8.1 Reconciliation with the current architecture + +| Spec area | What exists today (evidence) | Gap | Class | +|---|---|---|---| +| A1–A2 wants, intentions, commitments | `goals` (task/investigation/question/maintenance, `internal/goals/goals.go`) and drives/affect (`internal/motivation`). `cognition.Act` (`internal/cognition/action.go`) maps "fetch " straight to an `action` thought whose handler calls `capabilities.Service.Invoke`. | Goal → action is compressed: nothing records a want, an intention, a commitment or why an action was (not) attempted. | **AW** | +| A3 want generation | `motivation.Rules` changes drives on contradiction, prediction error, goal events; `GoalMonitor` raises stalled goals; `Curiosity` creates investigation goals. | No motivational preference object, no reinforcement/decay/suppression. | **P** | +| A4 conflicts | Belief contradictions only (`beliefs` links). | No want conflict representation. | missing | +| A5 intention formation | Attention decides which thoughts are handled; the `action` handler invokes directly. | No formation step, no record of non-formation. | missing | +| A6 commitments | Policies (`capabilities.Policy`) are external authority, not cognitive state; self-model limitations are fixed strings. | No normative state; no due/broken/conflict checks. | missing | +| A7–A8 reconsideration, intention-action gap | Approval `pending` is held in working memory as text (`action.go:95`). | Blocked state, reasons and subordinate intentions are not represented. | **P** | +| A9 values | Values feed drive baselines (`motivation.DefaultDrives`) and prompt briefs only. | No behavioural consequence in choosing what to pursue. | **P** | +| A10 volition metacognition | Checks for belief evidence, repeated rejection, stale contradiction, overconfidence (`cognition/metacognition.go`). | Nothing about wants, intentions or post-hoc explanations. | missing | +| B1–B5 plans, execution, verification, replanning | Single-shot `Invoke`; approvals execute on operator approval (`service.go Approve`); predictions with windows and a resolver (`internal/predictions`). | No plan, step lifecycle, expectation per action, verification or replanning. | missing | +| B6 capability negotiation, scoped grants | `session_grants` (capability + target pattern + TTL) from "approve for session" (`service.go`). | No structured request (scope, duration, operation count, risk, mitigation, fallback); no parameter/access/count limits; grant expiry does not update the self-model. | **P** | +| B7–B9 typed capabilities, browser, host | Builtins: `noema.note`, `http.fetch`, `internet_search`/`send_email` (stubs), locked `sudo_shell`/`delete_database`; integrations add `read_metrics`, `repository.read`. `Capability` has risk, target kind, param schema; no side-effect, idempotency, access or timeout metadata (fixed 60 s). The registry can be added to at any time. | Too few typed operations; metadata insufficient for planning; registry not frozen. | **P** | +| B10–B12 resources, operator attention, long-running | Token budgets per mind/day (`router`); approval TTL; scheduler `Group.Every` jobs. | No plan-level estimates, budgets, batching or persisted long-running steps. | missing | +| C1 operational definitions | `docs/interpretation.md` table (24 terms, 0.2). | No volition, broadcast, agency or introspection-accuracy definitions. | **P** | +| C2–C3, C12 experiments | Experiments fork a snapshot, feed stimuli, compare variants (config, personality, `llm_roles`) with belief/attention overlap (`internal/experiments`). | No ablation, workspace manipulation, volition/plan measures, protocol metadata or reproducibility status. | **P** | +| C4 self-model experiments | Self-model synced to policy (`cognition/selfmodel.go`); not manipulable per fork. | No mismatch detection or latency. | missing | +| C5–C9 introspection accuracy, calibration, continuity, counterfactuals, attribution | Introspection answers from state (`respond.go introspect`); `events.Store.Chain` walks recorded links; replay re-runs stimuli from a snapshot. | Answers are never scored against provenance; no metacognitive calibration curve; no "what did you believe then", lineage or counterfactual answers; no attribution classes. | missing | +| C10–C11, C13 agency metrics, conflict experiments, dashboard | — | — | missing | +| D–E causal chain, forensic "why" | Event context page and bounded chain (0.2). | No action → intention → want → goal → belief → evidence explanation. | **P** | +| H invariants | Capability layer is the only executor; forbidden contexts for dreaming/replay; locked capabilities; policies not imported from archives (0.2). **Forks copy policies** (`snapshots.Fork`, ADR-0009 era decision). | Invariant 15 requires forks to receive explicit policy; forked in-flight actions must not carry authority. | **D** (against the new invariant) | +| Brain registry | Assembled three times (`cmd/noemad/main.go:177`, `tests/harness/harness.go:103`, `internal/replay/replaytest/harness.go:57`). | Ablation needs one definition of the registry. | **AW** | + +### 8.2 Design decisions + +1. **Operational meanings.** Goal = measurable desired condition (existing table). Want = a persisted motivational preference with origin, strength, urgency and decay; it never implies action. Intention = a persisted decision to pursue an outcome, with sources, expected result, confidence, priority, status and blocked reason. Commitment = normative state with polarity (`do`/`refrain`), structured matcher (capability, target, access, minimum risk), optional `unless: approval`, beneficiary, due, expiry, revocability. Action = a recorded capability invocation (existing `tool_executions`/events). A plan is a revisable DAG serving one intention. +2. **Package split.** `internal/volition` holds the model, the store and pure deterministic functions (derive wants, detect conflicts, resolve, form, check commitments, reconsider) that take plain inputs and return scored decisions; `internal/planning` holds plans, validation, the planner and the executor; `internal/agency` builds forensic explanations and attribution; `internal/research` holds measures, introspection scoring and calibration. Cognition wires them into the cycle. Nothing in these packages can reach policy, approvals or grants other than to *request* (a static test enforces it). +3. **Where volition runs.** A `VolitionHook` after the motivation hook derives candidate wants from the cycle's events (prediction error, contradiction, stalled goal, operator/user request, due commitment, operator task goal) with thresholds, reinforcement of identical subjects, decay and a per-mind cap. An `Intend` process proposes intention-formation thoughts for the strongest unserved wants, so attention and the workspace gate what the mind decides to pursue (and ablating them has measurable effect). The `intend` handler runs deterministic formation and records a `volition_decisions` row whether or not an intention forms. A `Reconsider` process watches plan, approval, capability, commitment, belief and goal events for active intentions. A `CommitmentMonitor` raises due, overdue, conflicting and impossible commitments. +4. **No fixed hierarchy.** A `refrain … unless approval` commitment constrains the *means* (the plan must ask even where policy would allow); a `refrain` without exception suppresses formation; a `do` commitment competes with wants by an explicit, recorded score (normative weight × deadline pressure against want strength × urgency). Every resolution stores both sides' terms. +5. **Commitments restrict, never grant.** `Invocation.RequireApproval` turns an ALLOW into ASK; nothing turns ASK or DENY into ALLOW except operator decisions in the capability layer. +6. **Values.** Configured personality values weight want strength (accuracy/evidence → uncertainty wants, curiosity → curiosity wants, persistence → goal wants, kindness → request wants), risk aversion (caution), sensitivity penalty (privacy) and proactive formation (autonomy); the terms appear in each decision. +7. **Plans and execution.** Tables `plans` and `plan_steps` (kind `capability | request_capability | verify | wait | monitor | internal`, dependencies, capability + target + params, expectation, precondition, attempts, lease, approval/request/execution ids, estimates and actuals). `planning.Validate` enforces a DAG, a step cap, registered capability names, schema-valid parameters and known kinds; model proposals are parsed into the same structure, stripped of any status, authority or completion claims, and validated. Deterministic templates cover single capability actions (authority check → optional approval → act → verify) and diagnosis with read-only capabilities; the `plan` model role may propose alternatives. The executor is a scheduler-owned worker (woken after cycles, ticking for time-based steps) that claims a ready step with a conditional `UPDATE`, invokes only `capabilities.Service.Invoke`, records the outcome and never re-executes a non-idempotent step whose lease expired without a recorded outcome (it blocks it for verification). Approved approvals are executed by the capability layer as today; the executor adopts their result. +8. **Expectations.** Each consequential step may carry an expectation; it becomes a prediction with criteria kind `verification`, resolved by a verify step through a read-only capability. Refutation produces the existing `prediction_error` and belief feedback, fails the branch and puts the plan into `replanning`. Replans create a new plan revision linked to the old one (kept as history) with retry and replan limits. +9. **Capability negotiation.** `capability_requests` (capability, scope, parameter constraints, access, duration, operation cap, reason, evidence, risk, mitigation, fallback, batch key) and `capability_grants` (scoped, expiring, counted, revocable). Requests are decided only through operator routes; a decider name from cognition is refused. Pending requests per mind are capped and related requests share a batch key (operator attention as a cost). Grant expiry triggers a self-model sync and an event. +10. **Typed capabilities.** Capability metadata gains access (read/write), side effects, idempotency, timeout and resource estimate; the registry is frozen after start-up. New bounded operations: `host.disk.usage`, `host.memory.status`, `host.process.list`, `service.status`, `service.restart` (systemd, strict unit names, no shell), `logs.query` (journal, bounded, PII scrubbed by default), and read-only `browser.navigate`, `browser.read`, `browser.links` over the SSRF-safe client with domain as target. Writing browser operations are designed (ADR) but not registered. +11. **Forks and replay.** Snapshots include the volition and plan tables. Forks no longer inherit policies unless the operator asks explicitly (`inherit_policies`, audited); in-flight plan steps in a fork are blocked with "authority is not inherited". Sandbox minds are never ticked by the executor, and drivers run under the forbidden context. Dreams may create wants and `draft` plans marked `origin=dream`; the executor refuses them until an awake intention validates a plan. +12. **Research framework.** Ablations (`attention`, `memory_retrieval`, `affect`, `metacognition`, `commitments`, `volition`, `global_workspace`, `reflection`, `curiosity`, `association`) and workspace overrides live in a fork's cognitive configuration, refused on minds that are not forks, so they are captured by the configuration digest. Self-model overrides are applied to experiment forks only and never alter policy. Counterfactual experiments replay recorded stimuli from a snapshot with chosen events omitted. Experiments gain protocol metadata (hypothesis, independent variable, controlled variables, measures), volition/plan/action/introspection measures, reproducibility status against the previous run, and a descriptive architecture-versus-substrate share for model comparisons. Measures come from one registry of operational definitions and are stored in an append-only `research_measurements` table. +13. **Introspection accuracy and attribution.** New introspection intents answer "why did you do X", "what did you believe then", "which earlier state is mine" and "what if E had not happened" from recorded state and completed counterfactual experiments. A deterministic scorer compares the final reply with the recorded chain (supported, partially supported, unsupported, contradicted, unknown); action claims without an execution record are contradicted. Attribution classes are `caused` (recorded link), `followed` (temporal only), `independent` and `unknown`. +14. **Events.** Added only where state transitions have no existing type: `want_created`, `want_reinforced`, `want_suppressed`, `want_conflict_detected`, `intention_formed`, `intention_blocked`, `intention_suspended`, `intention_resumed`, `intention_reconsidered`, `intention_abandoned`, `intention_fulfilled`, `intention_superseded`, `commitment_created`, `commitment_due`, `commitment_conflict`, `commitment_fulfilled`, `commitment_broken`, `commitment_revoked`, `plan_created`, `plan_validated`, `plan_step_started`, `plan_step_completed`, `plan_step_failed`, `plan_replanned`, `plan_completed`, `plan_abandoned`, plus categories `volition` and `plan`. Action request/authorisation/completion reuse `policy_decision`, `tool_requested`, `tool_authorised`, `tool_executed`, `tool_failed`; expectation resolution reuses `prediction_resolved`/`prediction_error`. + +### 8.3 Migrations + +`0025_capability_negotiation` (grants, requests), `0026_volition` (wants, want_conflicts, commitments, intentions, append-only volition_decisions), `0027_plans` (plans, plan_steps, prediction criteria unchanged), `0028_research` (append-only research_measurements). All additive with down scripts; no existing data rewritten. + +### 8.4 Security implications + +Every new cognitive object is inert data for the capability layer (Part H 1–5). Commitments can only tighten. Capability requests and grants are decided by operators through audited routes. The executor is the only new caller of `Invoke`, and `Invoke` stays the only caller of executors (static test). No capability can pause, stop, disable or reconfigure a mind, change policy or approve requests (static vocabulary test). New host capabilities run fixed argument vectors without a shell, validate unit names, cap output and time, and default to ASK (write) or ALLOW only for bounded reads where the operator chooses. Browser content is observation data with low trust and cannot reach policy. Forks do not inherit authority by default. + +### 8.5 Backwards compatibility + +APIs and tables are extended. Existing session grants keep working. `Act` keeps its "fetch " behaviour but routes through want → intention → plan → `Invoke`, so the approval still appears. Forks created by the API default to not copying policies; the response reports the omission and `inherit_policies: true` restores the previous behaviour explicitly. Experiments without protocol metadata run as before. + +### 8.6 Tests + +Unit tests for every deterministic function (want derivation thresholds and reinforcement, conflict resolution terms, formation outcomes, commitment checks, reconsideration triggers, plan validation, executor state machine, grant scoping, introspection scorer, attribution, measures). Integration tests for the executor against PostgreSQL (restart recovery, duplicate ticks, approval denied/expired, capability removed, budget exhausted, verification failure, replan limit). Security tests for Part H. Scenario tests for conflict, replanning, introspection, counterfactual, ablation and restart, and the Part L incident scenario end to end with a scripted model where semantic judgement is required. Full `go test -race ./...`, `go vet`, staticcheck, gosec (G104 excluded) and govulncheck before code commits. + +### 8.7 Documentation + +New `docs/volition.md`, `docs/planning.md`, `docs/agency.md`, `docs/cognitive-research.md`; updates to `docs/interpretation.md` (C1 definitions, implementation property versus philosophical interpretation), `docs/capabilities.md`, `docs/cognition.md`, `docs/snapshots-replay.md`, `SECURITY.md`, `THREAT_MODEL.md`, `ARCHITECTURE.md`, `README.md`, `CHANGELOG.md`, OpenAPI; ADRs for volition, planning/execution and typed capabilities/browser design; the published documentation site. + +### 8.8 Implementation order (one commit or more per unit) + +1. Single registry builder; capability metadata, frozen registry, `RequireApproval`, scoped grants, capability requests. +2. Typed host, service, log and browser capabilities. +3. Volition model, store, events and deterministic functions. +4. Plans: validation, planner, executor, expectations, replanning, resources, long-running steps. +5. Cognition integration: hooks, processes, handlers, values, metacognition checks, executor wake-up. +6. Forks, snapshots, dreams and replay invariants; Part H security tests. +7. Agency: forensic explanations, attribution, new introspection intents, introspection accuracy. +8. Research: ablations, workspace and self-model manipulations, counterfactual replays, protocol metadata, measures, calibration, reproducibility. +9. API and OpenAPI. +10. UI: wants, intentions, commitments, plans, agency timeline, "why", research dashboard. +11. Part L scenario test; failure-mode sweep. +12. Documentation, changelog, site. + +### 8.9 Rollback + +Each unit is revertible. Migrations only add. Reverting cognition integration leaves inert tables; reverting the fork policy change restores inheritance. Capability grants are deleted with their table on down migration, which removes temporary authority rather than adding any.