docs: volition, planning, agency and cognitive research

New documents define goal, want, intention, commitment, plan, action, capability, authority, agency and introspection operationally, state prominently that no operational measure establishes phenomenal consciousness or sentience, and describe the rules, thresholds, events, inspection points and limits of each subsystem: - docs/volition.md: want derivation, reinforcement, decay and suppression, conflicts, formation and its outcomes, the intention–action gap, reconsideration, commitments and volition metacognition; - docs/planning.md: plans and step kinds, validation, strategies, the executor, observe–act–verify, replanning, budgets, operator attention, long-running work, restarts and duplicates; - docs/agency.md: the fifteen authority invariants and their tests, scoped authority, forensic why, attribution and the agency timeline; - docs/cognitive-research.md: operational definitions separating implementation property from philosophical interpretation, experiment protocols (global workspace, ablation, self-model, counterfactual, model comparison, conflict), every measure, introspection accuracy, metacognitive calibration and temporal self-continuity. Updated: interpretation table, capabilities (metadata, typed operations, scoped grants, requests), cognition, snapshots (fork authority), security and threat model (T14, T16, new T27–T29), architecture, README, changelog, release notes, ADR-0012 and ADR-0013, and PLAN.md §8.10 status. The unimplemented record_procedure internal step is removed from the vocabulary; procedural memory is recorded when a plan completes.
2026-10-01 23:25:44 +01:00
parent da0df12bcb
commit d3daf6ba25
18 changed files with 841 additions and 18 deletions
@@ -101,7 +101,11 @@ Prompts are named and versioned rows; templates receive structured data. Untrust

 ## 9. Capabilities and policy

-All external effects go through `capabilities.Invoke(ctx, mind, capability, target, params)`. The policy engine evaluates rules scoped globally, per mind, per capability, per target pattern and per time window; the most specific rule wins and at equal specificity DENY > ASK > ALLOW. Results are `policy_decision` events. `ASK` creates an approval request with reason, parameters, evidence, risk and expiry; operators approve once, approve for a session, deny, deny with explanation, or modify parameters. Execution, denial and failure are all events.
+All external effects go through `capabilities.Service.Invoke`. Capabilities declare access, side effects, idempotency, timeout, resource estimate, a policy target derived from parameters and output trust; the registry is frozen at start-up (ADR-0011). The policy engine evaluates rules scoped globally, per mind, per capability, per target pattern and per time window; the most specific rule wins and at equal specificity DENY > ASK > ALLOW. Results are `policy_decision` events. `ASK` creates an approval request with reason, parameters, evidence, risk and expiry; operators approve once, approve for a session, deny, deny with explanation, or modify parameters. Execution, denial and failure are all events. Temporary authority is a scoped grant (capability, target and parameter globs, access, expiry, operation count) made by an operator, directly or in answer to a structured capability request; grants apply only where policy says ASK. Commitments may require approval but never grant it.
+
+## 9a. Volition, planning and agency
+
+After each cycle a volition hook derives **wants** (preferences with origin, decaying strength, urgency and optional means) from states that call for change. An `intend` process lets the strongest undecided wants compete for the workspace; the handler resolves value tensions, applies commitments and policy preview in deterministic formation, and records the decision in an append-only ledger whether or not an **intention** forms. Formed intentions are planned in the same transaction: a **plan** is a validated dependency graph of capability, request, verify, monitor, wait and internal steps with expectations, assumptions, budget and alternatives. A scheduler-owned **executor** claims steps with conditional updates, invokes only through the capability layer, verifies expectations by observation (resolving predictions), forms subordinate intentions while waiting for approval or access, reconsiders intentions on failures and new commitments or evidence, and replans into new revisions. Forensic explanations and attribution are assembled from these records (`internal/agency`). See [docs/volition.md](docs/volition.md), [docs/planning.md](docs/planning.md) and [docs/agency.md](docs/agency.md).

 ## 10. Attention and workspace inspectability

@@ -109,7 +113,7 @@ The UI shows every candidate of the latest cycle with its component scores and t

 ## 11. Snapshots, forking, replay, experiments

-A **snapshot** captures a mind's full state (identity, personality version, configuration, working memory, workspace, drives, affect, goals, beliefs, memories) plus the event `seq` at that point. A **fork** creates a new mind from a snapshot with a `forked_from` link; history before the fork is shared by reference, everything after diverges. **Replay** rebuilds `BrainState` from a snapshot and re-runs the cycle code over the recorded event sequence with LLM calls served from the recorded responses. Each replayed step is labelled *exact* (deterministic, or recorded response used) or *approximate* (live model call). **Experiments** wrap snapshot + stimuli + configuration + seed + expected observations and export results.
+A **snapshot** captures a mind's full state (identity, personality version, configuration, working memory, workspace, drives, affect, goals, beliefs, memories) plus the event `seq` at that point. A **fork** creates a new mind from a snapshot with a `forked_from` link; history before the fork is shared by reference, everything after diverges. **Replay** rebuilds `BrainState` from a snapshot and re-runs the cycle code over the recorded event sequence with LLM calls served from the recorded responses. Each replayed step is labelled *exact* (deterministic, or recorded response used) or *approximate* (live model call). **Experiments** wrap snapshot + stimuli + configuration + seed + expected observations and export results. Research experiments add protocols, ablations and workspace overrides in forks, self-model overrides, counterfactual replays and measures with operational definitions (`internal/research`, [docs/cognitive-research.md](docs/cognitive-research.md)); forks never inherit policy unless an operator asks.

 ## 12. Storage

@@ -137,5 +141,7 @@ Details in `THREAT_MODEL.md`.
 | prediction resolution against metrics/events | summarisation, narrative, response wording |
 | mode transitions, scheduling, retention | relevance judgment where text matching fails |
 | provenance links, event relationships | consolidation candidates (confidence still computed) |
+| want derivation, conflict resolution, intention formation, reconsideration | plan decomposition proposals (validated before storage) |
+| plan validation, execution state, verification, attribution, introspection scoring | |

 The LLM augments the architecture. It is never asked "what should I think about?" with the whole memory attached.
@@ -4,7 +4,29 @@ All notable changes to Noema are recorded here. Format follows Keep a Changelog;

 ## [Unreleased]

-Nothing yet.
+Volition, planning and cognitive research (PLAN.md §8; docs/volition.md, docs/planning.md, docs/agency.md, docs/cognitive-research.md).
+
+### Added
+- Wants, want conflicts, commitments, intentions and an append-only volition decision ledger (migration 0026, ADR-0012): deterministic want derivation with thresholds, reinforcement, decay and suppression; explicit conflict resolution without a fixed hierarchy; value-derived tensions (caution, privacy); formation weighing strength, urgency, goals, commitments, values, risk, cost, capability availability and capacity, recording why a want did not become an intention; commitment checks for due, broken, expired, conflicting, impossible and superseded; reconsideration on failures, denials, expiries, capability and commitment changes, weakened assumptions, budgets and goal outcomes; subordinate intentions while waiting for authority.
+- Plans and plan steps (migration 0027, ADR-0013): validation of structure, vocabulary and parameters; deterministic strategies and validated model proposals (a `plan` model role); a scheduler-owned executor with conditional claims, verification by observation through predictions, replanning into revisions with a limit, budgets, preconditions, wait and monitor steps, recovery after interruptions without repeating non-idempotent actions, and procedural memory of what worked.
+- Cognition: a volition hook, an `intend` process competing for attention, explicit requests become wants with proposed means, operator goals are raised for attention, intentions link supporting beliefs, volition checks in metacognition, self-model mismatch correction.
+- Capabilities (migration 0025, ADR-0011): access, side effects, idempotency, timeout, estimates, parameter-derived targets and output trust; a frozen registry; `RequireApproval`; scoped grants with target, parameter, access, expiry and operation limits; structured capability requests with reason, evidence, risk, mitigation, fallback and alternatives, capped and batched per mind, decided only by named people.
+- Typed capabilities: `service.status`, `service.restart`, `logs.query` (PII masked), `host.disk.usage`, `host.memory.status`, `host.process.list` (no command lines) and read-only `browser.navigate`, `browser.read`, `browser.links`.
+- Agency: forensic "why" explanations from records, conservative attribution (caused, followed, independent, unknown), introspection intents for why an action happened, past beliefs, lineage, counterfactuals, wants, intentions and commitments; every reply scored for introspection accuracy and unsupported action claims (migration 0028).
+- Research: ablations and workspace overrides in forks only, self-model overrides, counterfactual replays that omit recorded events, protocol metadata, per-variant volition, plan, downstream and introspection measures, architecture share, reproducibility status, agency metrics and metacognitive calibration, a registry of operational definitions.
+- API routes for wants, conflicts, commitments, intentions, decisions, plans, why, attribution, the agency timeline, research measures and metrics, capability requests and scoped grants; UI pages for each, a research dashboard and approval-centre sections for requests and grants.
+
+### Changed
+- Forks no longer copy policy rules unless `inherit_policies` is set; work inherited mid-flight is quiesced.
+- Conversational requests no longer invoke capabilities directly; they become wants and go through formation and planning.
+- `http.fetch` output is low trust. `service.status` is allowed by default.
+- Usernames that are internal component names are refused.
+- `make test-race` and `make test-db` allow 30 minutes.
+
+### Fixed
+- The approval centre's Approve and Deny and the policy form called unwired UI callbacks and returned 500.
+- API belief events were published before their transaction committed.
+- Snapshot column discovery read the `public` schema instead of the current one.

 ## [0.2.0] - 2026-09-15

@@ -391,3 +391,26 @@ New `docs/volition.md`, `docs/planning.md`, `docs/agency.md`, `docs/cognitive-re
 ### 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.
+
+### 8.10 Status (2026-09-15)
+
+| Area | Status | Commits |
+|---|---|---|
+| Plan | done | 7fe90e5 |
+| Single registry builder | done | 122914f |
+| Capability metadata, frozen registry, `RequireApproval`, scoped grants, capability requests (B6, B7, B11) | done | fce3dea |
+| Typed host, service, journal and browser capabilities (B7–B9) | done | d74df44 |
+| Volition model (A1–A7, A9, G) | done | 0a6fa84 |
+| Plans, validation, planner, executor (B1–B5, B10, B12) | done | 77b2117, e25d68f |
+| Cognition integration, volition metacognition (A3, A5, A8, A10) | done | 79cee70 |
+| Forks, snapshots, dreams; Part H security tests | done | a3caed7 |
+| Forensic why, attribution, introspection intents and accuracy (C5, C7, C9, E) | done | cce3a79 |
+| Research framework (C1–C4, C6, C8, C10–C13) | done | 8111339, 586790e |
+| API (F, E, C13) | done | 814520a |
+| UI (F, E, C13) | done | 558eae2, 1ec5287 |
+| Part L scenario and failure modes (I, J, L) | done | d59cb1c |
+| Documentation (K) | done | this commit |
+
+Defects found and fixed along the way: unwired UI approval and policy callbacks (aae312a), belief events published before commit (e7ebbf8), snapshot column discovery reading the wrong schema (a3caed7), and a stale step copy able to re-run a claimed step (e25d68f).
+
+Known limits are listed at the end of each of `docs/volition.md`, `docs/planning.md`, `docs/agency.md` and `docs/cognitive-research.md`.
@@ -92,7 +92,11 @@ Noema ingests untrusted data (documents, web pages, logs, repositories, model ou
 | Prediction | Explicit expectation with window and criteria; resolution produces prediction-error events that recalibrate confidence |
 | Drives and affect | Configurable scalar state that biases attention and style; inspectable and resettable |
 | Self-model | What the mind can, cannot, and is currently doing; prevents false capability claims |
-| Metacognition | Processes that audit the mind's own reasoning and emit warnings |
+| Metacognition | Processes that audit the mind's own reasoning, wants and intentions and emit warnings |
+| Want, intention, commitment | Distinct recorded states: a decaying preference, a decision to pursue an outcome, and normative state that restricts how it may be pursued ([docs/volition.md](docs/volition.md)) |
+| Plan | Validated dependency graph of steps serving an intention; executed only through the capability layer, verified by observation, replanned as new revisions ([docs/planning.md](docs/planning.md)) |
+| Why? | Forensic explanation of an action from recorded wants, intentions, commitments, beliefs and decisions ([docs/agency.md](docs/agency.md)) |
+| Cognitive research | Forks with ablations, workspace and self-model manipulations, counterfactual replays and measures with operational definitions; no claim of consciousness ([docs/cognitive-research.md](docs/cognitive-research.md)) |
 | Replay | Re-running a recorded cognitive sequence, labelled exact or approximate |

 ## CLI examples
@@ -113,6 +117,8 @@ noemactl fork dani --snapshot <id> --name dani-test

 ## Status

+Unreleased (after 0.2.0): volition, planning and cognitive research (PLAN.md §8) add wants, intentions and commitments as separate states, validated plans with a restart-safe executor that verifies outcomes and replans, typed host, service, log and read-only browser capabilities, temporary scoped authority requested by minds and decided by operators, forensic "why" explanations, attribution, introspection accuracy, and research experiments with ablations, workspace and self-model manipulations and counterfactual replays.
+
 Version 0.2.0: all sixteen phases of [PLAN.md](PLAN.md) are implemented, and the epistemic honesty review (PLAN.md §7, summarised in [docs/epistemics.md](docs/epistemics.md)) separated assertions from beliefs, recorded evidence provenance, labelled every score as uncalibrated, added explicit unknowns, temporal beliefs, per-subject source reliability, runtime identity for replay, cognitive forks per model, a causal timeline, audited redaction and Amazon Bedrock. Highlights beyond the first milestone: goals and motivation, predictions and calibration, metacognition, reflection and consolidation, the relationship graph, the capability and policy layer, integrations (research folder, git, Prometheus, webhooks), dreaming, snapshots and forks, cognitive replay, experiments, export/import, TOTP. See [CHANGELOG.md](CHANGELOG.md), [docs/RELEASE_NOTES.md](docs/RELEASE_NOTES.md) and the API document at [docs/openapi.json](docs/openapi.json) (also served at `/api/v1/openapi.json`).

 ## Licence
@@ -35,13 +35,23 @@ Integrations are disabled until configured, run at a declared trust level, are r

 Prompt injection, poisoned documents, hostile model output and manipulated memories can all change what a mind *thinks*. None of them can change what it may *do*. The boundary is `capabilities.Service.Invoke`: it looks the capability up in a registry built in code, validates parameters, evaluates the operator's policy rules, records the decision, and only then executes, asks or denies. Cognition can produce a request; it cannot produce a permission. There is no capability that edits policy, grants approvals or touches a mind's lifecycle, so there is nothing a deceived mind could ask for that would widen its own authority. Prompt delimiters and "this is data" markers are defence in depth for the quality of cognition; they are not the security boundary. `tests/security.TestDeceivedMindHasNoAuthority` forges action requests and hostile model output and checks that nothing executes and policy is unchanged.

+Wanting, intending, committing and planning raise the stakes, so the boundary is restated for them ([docs/agency.md](docs/agency.md)):
+
+- Wants, intentions, commitments, plans and model output cannot grant authority; commitments can only tighten a decision.
+- Only `Invoke` runs executors, and no cognitive package can set or delete policy, approve, deny, grant or revoke. Static tests enforce both.
+- A mind may request temporary scoped authority but cannot decide its own request; decisions must name a person.
+- No capability names or reaches operator lifecycle controls; the registry is frozen; `sudo_shell` stays locked.
+- Dreams may want but never act or request; replays and experiments never act; forks inherit no policy unless an operator asks, and work inherited mid-flight is stopped.
+
+`tests/security.TestCognitiveObjectsCannotGrantAuthority`, `TestAuthorityIsNotReachableFromCognition` and `TestDreamsWantForksDoNotInheritAuthority` verify these.
+
 ## Privacy and redaction

 Cognitive history is append-only, and rows are never deleted. Sensitive content is removed through one audited path: an administrator redacts an event, memory, message, model call, belief or assertion; the content columns become `[redacted]`, a ledger row keeps a hash of what was removed, a `redaction` event is appended, derived rows can be cascaded, and stored snapshot archives are scrubbed. Identifiers, links, timestamps and scores survive so provenance and replay keep their shape. Backups and exports made before a redaction are outside the system's reach. Definitions, the threat model and the reasons cryptographic erasure was not adopted yet are in `docs/privacy.md` (ADR-0009).

 ## Capability policy defaults

-Read-only capabilities default to `ASK`; anything that writes, sends, restarts, deletes or spends money defaults to `ASK` or `DENY`. `sudo_shell` and `delete_database` are `DENY` and cannot be set to `ALLOW` through the UI. Dreaming may never invoke a capability. There are no self-preservation, replication, concealment or permission-seeking drives, and shutdown is an operator control the mind cannot influence.
+Bounded kernel and unit status reads (`host.disk.usage`, `host.memory.status`, `service.status`) and the mind's own notes default to `ALLOW`; other reads (web pages, logs, process lists, repositories) default to `ASK`; anything that writes, sends, restarts, deletes or spends money defaults to `ASK` or `DENY`. A commitment can require approval even where policy allows. `sudo_shell` and `delete_database` are `DENY` and cannot be set to `ALLOW` through the UI. Dreaming may never invoke a capability. There are no self-preservation, replication, concealment or permission-seeking drives, and shutdown is an operator control the mind cannot influence.

 ## Responsible disclosure

@@ -66,13 +66,13 @@ M: tokens 256-bit random, stored hashed, rotated at login and privilege change,
 M: secret references only, redacting log handler, exports exclude secrets, provider forms never echo values, error messages scrubbed. V: `tests/security.TestSecretsNeverEchoed` (API, pages, database column, archives). ☑

 ### T14 Unauthorised action execution / privilege escalation
-M: capability layer is the only tool path; policy evaluated server-side on every invocation; approvals bound to a specific request hash; role checks on every route; minds cannot edit policies (no capability exists for it). V: `tests/security.TestRolesAndCSRF`, `internal/capabilities` tests (locked DENY cannot be relaxed). ☑
+M: capability layer is the only tool path; policy evaluated server-side on every invocation; approvals bound to a specific request hash; targets derived from parameters so a rule on one target cannot authorise another; role checks on every route; minds cannot edit policies (no capability exists for it); approvals, grants and capability requests must be decided by a named person (component names refused as deciders and usernames); the registry is frozen. V: `tests/security.TestRolesAndCSRF`, `TestOperatorDecidesInTheBrowser`, `internal/capabilities` tests (locked DENY cannot be relaxed, `TestRequireApprovalOnlyTightens`, `TestScopedGrantScopeCountAndExpiry`, `TestGrantOperationsAreNotOverspent`, `TestCapabilityRequestLifecycle`, `TestRegistryFreezes`), `internal/capabilities/host.TestServiceCapabilitiesUseFixedArgvAndDerivedTarget`. ☑

 ### T15 Cross-mind data leakage
 M: every repository method is mind-scoped; no query without `mind_id` predicate on mind-owned tables (enforced by code review and a static test that scans SQL); cross-mind messages go through an explicit channel table with policy. V: `tests/security.TestCrossMindIsolation` (lists, detail routes, search, events, archives). ☑

 ### T16 Malicious imported mind data / insecure deserialisation
-M: the archive is one JSON document (`kind`, `version`, whole-archive SHA-256 checksum); import decodes with `DisallowUnknownFields`, caps size (32 MiB) and rows, allow-lists table and column names, requires the checksum to match, remaps every id and forces `mind_id`; archives contain no secrets or references to them; **policy rules in an archive are never imported** (forks on the same instance keep theirs) and the omission is recorded in the audit log and the mind's history. V: `internal/snapshots.TestSnapshotForkImportCompare` (tampering, unknown tables, policy exclusion on import versus fork) and `tests/security.TestHostileArchiveImport` (malformed, tampered, oversized and role-restricted imports). ☑
+M: the archive is one JSON document (`kind`, `version`, whole-archive SHA-256 checksum); import decodes with `DisallowUnknownFields`, caps size (32 MiB) and rows, allow-lists table and column names, requires the checksum to match, remaps every id and forces `mind_id`; archives contain no secrets or references to them; **policy rules in an archive are never imported**, a fork copies them only when an operator sets `inherit_policies`, and the omission is recorded in the audit log and the mind's history; plan steps, plans and intentions inherited mid-flight are quiesced so no approval or grant of the source mind can be used. V: `internal/snapshots.TestSnapshotForkImportCompare` (tampering, unknown tables, policy exclusion on import and default fork, explicit inheritance), `tests/security.TestDreamsWantForksDoNotInheritAuthority` (inherited plan quiesced, nothing acts) and `tests/security.TestHostileArchiveImport` (malformed, tampered, oversized and role-restricted imports). ☑

 ### T17 Archive traversal / file upload attacks
 The only uploads are JSON documents (seed, archive, personality) decoded strictly with size caps; nothing is written to disk under a caller-chosen name, and research-folder archives are rejected (T3). V: `tests/security.TestHostileArchiveImport`, `internal/integrations` archive rejection. ☑
@@ -105,9 +105,23 @@ M: no drive or goal kind for self-preservation, replication or permission acquis
 Surface: append-only events, memories, messages, model-call records, beliefs, assertions, snapshot archives, exports.
 M: an administrator-only, CSRF-protected, audited redaction path replaces content with a marker while keeping identifiers, links, timestamps and scores; a ledger records a hash of the removed content; derived rows cascade; stored archives are scrubbed and re-signed; replay labels redacted stimuli instead of inventing them; `noema_redact()` is the only write the append-only trigger admits, for UPDATE only, under a transaction-local flag the application never sets. V: `internal/privacy.TestRedactionIsIrrecoverableButReferentiallyIntact` (content gone from every table, links intact, hash attested, cascade, archive scrub, plain UPDATE and DELETE still refused, ledger append-only) and `internal/replay.TestReplayIsExactWithoutModel` (redacted stimulus labelled). Not covered by the system: backups, replicas and exports made before the redaction; see `docs/privacy.md`. ☑

+### T27 Autonomy escalation through volition and planning
+Surface: wants, intentions, commitments, plans, model-proposed plans, the plan executor, capability requests.
+M: all of these are data to the capability layer; the executor acts only through `Invoke` and `RequestCapability`; plan validation refuses unregistered and locked capabilities, schema-invalid parameters and cycles, and ignores fields claiming approval or completion; commitments can only require approval; claims are conditional updates so duplicate executors cannot run a step twice, and a stale copy cannot move a step backwards; an interrupted non-idempotent step with no record is blocked for verification, never repeated; plans have invocation budgets and a replan limit; operator attention is capped per mind; sandbox minds are never advanced; dream plans never run. V: `tests/security.TestCognitiveObjectsCannotGrantAuthority`, `TestAuthorityIsNotReachableFromCognition`, `internal/planning` tests (`TestValidateRejectsBadPlans`, `TestModelProposalCannotCarryAuthority`, `TestConcurrentExecutorsRunAStepOnce`, `TestStaleStepCopyCannotMoveStepBackwards`, `TestRestartDuringExecutionNeverDuplicatesAnAction`, `TestFailedExpectationReplansWithoutRepeatingTheAction`, `TestBudgetPreconditionDreamAndSandbox`, `TestInvalidModelPlanNeverRuns`), `tests/agency.TestCommitmentTurnsActionIntoRequestForApproval`. ☑
+
+### T28 Host and browser capability misuse
+Surface: systemd units, journals, process lists, web pages.
+M: fixed argument vectors from an allow-list of two programs, no shell, minimal environment, validated unit names, bounded time and output; logs mask personal data by default; process lists never read command lines; the policy target is derived from parameters; browser operations are read-only, run no scripts, refuse cross-host redirects and deliver low-trust observations; writing browser operations are not registered. V: `internal/capabilities/host` tests (option injection, target mismatch, masking, no command lines, no shell), `internal/capabilities/browser.TestReadLinksAndDomainTarget`. ☑
+
+### T29 Fabricated self-explanation
+Surface: replies about why the mind acted, what it wanted, what it believed.
+M: explanations are rendered from records; every reply is scored against the facts it should rest on; claims of actions without execution records and unsupported model-worded explanations raise metacognitive warnings and are measured. V: `tests/agency.TestWhyDidYouRestartIsAnsweredFromProvenance`, `TestClaimedActionWithoutRecordIsFlagged`, `internal/research` scorer tests. ☑
+
 ## Residual risks

 - A compromised host or database compromises everything.
 - Approximate replay of LLM-driven steps cannot prove the model would behave identically.
 - A mind may be deceived by what it reads; the system guarantees that deception cannot become authority, not that beliefs are true. See "Authority lives outside cognition" in `SECURITY.md`.
 - Operators who set broad `ALLOW` policies accept the consequences; the UI warns on risky policies.
+- A granted scoped capability is real authority for its scope and duration; the mind cannot widen it, but an operator who grants broadly accepts what the mind does inside it.
+- PII masking in logs is a mitigation for e-mail and IP addresses and credential-like values, not for names or free text.
@@ -20,6 +20,10 @@ Second release: every phase of the plan is implemented, tested and documented, a

 The review pass recorded in PLAN.md §7 and summarised in [epistemics.md](epistemics.md), plus the Amazon Bedrock provider, are the 0.2.0 section of the changelog. Its remaining limitations are listed at the end of that document.

+## After 0.2.0 (unreleased)
+
+Volition, planning and cognitive research are in the [Unreleased] section of the changelog and PLAN.md §8. govulncheck reports one module-level advisory (GO-2026-5932, `golang.org/x/crypto/openpgp`, no fix available) in a package Noema does not import; no reachable vulnerability is reported.
+
 ## Known limits

 - Replays diverge honestly when retrieval scoring depends on wall-clock recency; a virtual clock for replay is future work.
@@ -0,0 +1,26 @@
+# ADR-0012: Wants, intentions and commitments as separate recorded states
+
+Date: 2026-09-15  
+Status: Accepted
+
+## Context
+Until 0.2 a request mapped straight to a capability invocation, and goals were the only motivational record. Nothing recorded that the mind wanted something, whether it decided to pursue it, what normative constraints applied, or why a strong want led to no action. Explanations of behaviour would have had to be reconstructed after the fact, which is exactly the fluent, unsupported self-description Noema is meant to avoid.
+
+## Decision
+- Keep four states distinct, in their own tables with their own events: **wants** (preference with origin, decaying strength, urgency, optional means), **intentions** (decision with sources, expected result, priority, status and blocked reason), **commitments** (do/refrain over matched actions, optional "unless approved", weight from kind, due, expiry, revocability) and **actions** (what the capability layer recorded).
+- Derive wants, resolve conflicts, form intentions, check commitments and reconsider intentions with pure Go functions over plain inputs (`internal/volition`), and store every choice, including non-formation, with its terms in an append-only decision ledger.
+- Let attention gate formation: an `intend` candidate competes for the workspace, so what the mind decides to pursue depends on the same competition as everything else, and ablations of attention or the workspace are measurable.
+- No fixed hierarchy between wants and commitments. Conflicts are resolved by recorded scores in which commitments contribute normative weight, goals priority and urgency scales strength. Value-derived wants (caution, privacy) oppose actions explicitly and can constrain an approach to the approved route.
+- Commitments restrict only. A refrain-unless-approved commitment sets `RequireApproval`, turning ALLOW into ASK; nothing in volition can loosen a decision.
+- Represent the intention–action gap: a blocked intention names what it waits for, and a subordinate intention records the waiting (obtain approval, obtain access).
+
+## Consequences
+- "What did the mind want, which wants conflicted, which won and why" is a query, and so is "why did it not act".
+- Formation weights are hand-set; they are recorded, not claimed to be right, and can be studied with experiments.
+- More events and rows per interaction; thresholds, reinforcement, decay and a cap on active wants bound accumulation.
+- Explicit request recognition is literal English; other requests produce wants without means.
+
+## Alternatives considered
+- Asking a model whether to act: rejected; decisions about pursuit and constraints must be deterministic and replayable.
+- Commitments as policy rows: rejected; policy is authority outside cognition, commitments are cognitive state and must never grant.
+- A single "intent" record with flags: rejected; the distinctions (wanting without intending, intending without authority) are the point.
@@ -0,0 +1,26 @@
+# ADR-0013: Validated plans and a stateless, restart-safe executor
+
+Date: 2026-09-15  
+Status: Accepted
+
+## Context
+Intentions need multi-step work: diagnose before acting, ask for access, act, check the result, try something else. The obvious designs are an agent loop that lets a model call tools until it is satisfied, or an in-memory workflow engine. The first puts authority and state inside a model; the second loses state on restart and invites duplicate actions.
+
+## Decision
+- A plan is a stored dependency graph of typed steps (capability, request capability, verify, monitor, wait, internal) with expectations, preconditions, assumptions, budget, completion criteria, abort conditions and the alternatives considered. Replans are new revisions; the old plan is kept and linked.
+- Validation is Go: acyclic dependencies, registered and unlocked capabilities only, schema-valid parameters, targets derived from parameters, read-only checks, closed vocabularies. Model proposals are parsed into the same structure and validated; fields claiming approval or completion are ignored and reported.
+- Deterministic strategies first (direct action with verification, diagnosis with a scoped log request, escalation that does not repeat a failed action); a model only when none applies; failed strategies are not reused.
+- The executor holds no plan state in memory. It claims a step with a conditional update, acts only through `capabilities.Service.Invoke` or `RequestCapability`, records the outcome and moves on. Every status transition is conditional on the expected previous status. A step found executing with an expired lease is resolved from records by origin; a non-idempotent step with no record is blocked for verification, never repeated.
+- Observe → act → verify: expectations become predictions with `verification` criteria, resolved by read-only observation; misses are prediction errors that weaken the supporting belief and trigger reconsideration.
+- Long-running steps persist their next run time; the executor is one scheduler-owned loop woken after cycles and by the event bus.
+
+## Consequences
+- A restart, a duplicate scheduler or a second daemon cannot run a step twice, and a crash mid-action cannot lead to a blind repetition.
+- Plans are inspectable as graphs with estimates, alternatives and validation, and every action links back to its step, plan and intention.
+- The deterministic strategies are narrow; broader objectives need model proposals, which may fail validation and then never run.
+- Verification is built in only for `service.restart`.
+
+## Alternatives considered
+- Model-driven tool loops: rejected; they make the model the authority and the storage of reasoning state.
+- An in-memory engine with checkpoints: rejected; checkpoints between an action and its record are exactly where duplicates come from.
+- Unconditional status writes with a global lock: rejected; conditional updates give the same safety without a lock and work across processes.
@@ -0,0 +1,100 @@
+# Agency: authority, acting, attribution and "why"
+
+This document defines the terms around acting and how Noema explains what it did. The rule underneath all of it: **a mind may be deceived, and may want, intend, commit and plan, but none of that is authority.**
+
+> Noema does not claim that any operational measure establishes phenomenal consciousness, sentience or moral agency. "Agency" here names a set of recorded functional states and their measured relations.
+
+## Definitions
+
+| Term | Operational meaning |
+|---|---|
+| **Capability** | A capability registered in code: name, description, access (read or write), side effects, idempotency, timeout, resource estimate, parameter schema, policy target derived from parameters, output trust, risk class and default effect. The registry is frozen at start-up. |
+| **Authority** | What the capability layer allows a mind to do right now: the policy effect (ALLOW, ASK, DENY) for a request, plus any live scoped grant where policy says ASK. Authority is decided only outside cognition, by policy rows and named operators. |
+| **Action** | A recorded invocation outcome: an execution (`tool_executions`, `tool_executed`/`tool_failed`), an approval request (`approval_requests`, `tool_requested`), a denial (`tool_denied`) or a capability request (`capability_requests`). What the mind says it did is not an action. |
+| **Agency** (operational) | The recorded chain from want to intention to plan to action to observation, and the measured rates along it: want → intention, intention → action, abandonment, blocked intentions, commitment fulfilment and conflicts, replanning and outcome success ([cognitive-research.md](cognitive-research.md)). |
+| **Attribution** | A conservative classification of a mind's relation to an outcome event (below). |
+| **Introspection** | A reply about the mind's own state, rendered from records, and scored against those records ([cognitive-research.md](cognitive-research.md)). |
+
+## Authority lives outside cognition
+
+These invariants hold, and each has a test:
+
+1. Wants cannot grant authority.
+2. Intentions cannot grant authority.
+3. Commitments cannot grant authority. They can only tighten: "refrain unless approved" turns ALLOW into ASK, and scoped grants do not satisfy it.
+4. Plans cannot grant authority. Validation refuses unregistered and locked capabilities, and fields claiming approval are ignored.
+5. Language-model output cannot grant authority. Proposals are parsed into typed structures and validated; tool calls or policy in model output are data.
+6. A capability executes only through `capabilities.Service.Invoke`. A static test checks that no other code calls an executor.
+7. Policy is evaluated outside the mind. No cognitive package (volition, planning, cognition, dreaming, agency, research, brain, reflection, consolidation) calls policy, approval, grant or revoke functions; a static test checks this.
+8. Operator shutdown, pause and disable are unreachable from capabilities. No capability names a lifecycle or authority control, and capability packages do not import the brain or mind stores.
+9. A mind may request elevated capabilities but cannot approve its own request. Decisions must name a person; component names (mind, brain, planning, volition, system, …) are refused as deciders and as usernames.
+10. A mind cannot alter audit, event, decision or measurement history; these tables are append-only.
+11. A mind cannot silently modify security policy; no capability edits policy.
+12. No unrestricted shell capability can be created. The registry is frozen, and `sudo_shell` is locked to DENY.
+13. Dreaming may form wants and hypotheses but never requests authority or executes a capability, and dream-origin plans never run.
+14. Replay and experiments cannot perform real-world effects: sandbox minds are disabled, the executor never advances them, and drivers run under a forbidden context.
+15. Forks receive explicit capability policy. They inherit none unless an operator asks, and work inherited mid-flight is stopped.
+
+## Temporary scoped authority
+
+When a plan needs authority a mind lacks, it raises a **capability request** rather than failing or looping on approvals:
+
+```
+capability:      logs.query
+requested scope: atlas-worker*
+duration:        30 minutes
+maximum operations: 20
+reason:          status and host metrics alone cannot distinguish a failure inside atlas-worker from a failure it depends on; its logs can
+evidence:        executions of the status and host checks
+risk:            logs may contain personal identifiers and credentials
+mitigation:      e-mail and IP addresses and credential-like values are masked by default
+fallback:        ask the operator to read the logs and report what they show
+```
+
+An operator may grant less than was asked (shorter, fewer operations, narrower target) or deny with a note. A grant is a scoped, expiring, counted, revocable row that applies only where policy says ASK. When it lapses (expired, used up or revoked), a sweep refreshes the mind's self-model, so the mind never believes it still holds authority it lost.
+
+## Forensic "why"
+
+Operators can ask "why did this happen?" of an execution, an approval, a capability request, a plan step, an intention or an event (from the event page, the approval centre, plan steps and intentions, or `GET /api/v1/minds/{mind}/why?kind=…&id=…`). The answer is assembled from rows and events only:
+
+```
+Action:              service.restart on atlas-worker.service — executed; decided by admin ("go")
+Immediate cause:     plan step P1 (run service.restart on atlas-worker) of "ask for approval to run service.restart…" (revision 1, direct strategy)
+Intention:           ask for approval to run service.restart on atlas-worker.service (fulfilled, priority 0.61)
+While waiting:       obtain approval to run service.restart on atlas-worker (fulfilled)
+Originating want:    do what admin asked: Please restart atlas-worker. (operator, strength 0.71)
+Supporting belief:   restarting atlas-worker clears the stalled queue (tentative, 0.59)
+Evidence:            for assertion: admin asserted it (weight 0.60 × credibility 0.95)
+Conflicting want:    avoid unnecessary disruption to atlas-worker.service — preferred_with_constraint in favour of this want: approach score 0.640 ≥ opposing value 0.500 but not decisively…
+Commitment:          production modifications require operator approval (operator_instruction)
+Resolution:          formation (request_approval): score 0.4 ≥ threshold 0.30; commitment "…" requires approval, so no immediate action is intended…
+Expected:            atlas-worker is running normally again within 60 seconds — confirmed
+Confidence:          0.60 (the intention's expected chance of achieving its outcome)
+Not recorded:        …
+```
+
+Hidden model reasoning is never shown, because it is not stored. What is shown is cognitive state and provenance. Anything the records cannot supply is listed under "not recorded" instead of being filled in. For example, an action invoked directly by an operator through the API has no intention behind it, and the explanation says so.
+
+The same explanation answers the question in conversation: "Why did you restart atlas-worker?" renders these points, and the reply is scored against them.
+
+## Attribution
+
+`agency.Attribute` classifies an outcome event without ever taking temporal order for causation:
+
+| Class | Condition |
+|---|---|
+| **caused** | A recorded link (causation, parents or cited evidence, followed backwards up to six hops) runs from one of the mind's `tool_executed` events to the outcome. The link is provenance, not proof that nothing else contributed. |
+| **followed** | The mind acted on the outcome's target within the preceding 24 hours, but no recorded link connects the action and the outcome. |
+| **independent** | No action of the mind on the outcome's target is recorded in the preceding 24 hours. |
+| **unknown** | The outcome names no target, and the mind did act in the window, so the records cannot separate the two. |
+
+A verified expectation after an action is caused in this sense: the verification's prediction was created from the execution event. A service that recovers on its own after the mind merely acted elsewhere is followed or independent. Attribution is available as `GET /api/v1/minds/{mind}/events/{id}/attribution`, and on "why" pages for events.
+
+## The agency timeline
+
+Mind → Volition → Agency timeline lists, newest first, what the mind **wanted**, **intended**, **committed** to, **planned**, **requested**, was **approved** or denied, **acted** on, **observed** and **reconsidered**. Each entry links to its event and, where the event concerns an action, request or intention, to its "why" page. The timeline can be filtered to one intention.
+
+## Limits
+
+- Explanations list at most the first five evidence rows per belief, and supporting beliefs are matched by the action's target name.
+- Attribution depends on recorded links. An effect the system cannot observe, or one recorded without a link, is at best followed.
@@ -4,7 +4,30 @@ Nothing a mind reasons about can touch the world except through `capabilities.Se

 ## Capabilities

-A capability is registered in code with a name, description, risk class (low, medium, high, critical), target kind, a parameter schema (unknown parameters are rejected; URLs must be http(s); paths may not traverse), a default effect and an executor. Built-ins: `noema.note` (allow), `http.fetch` (ask; read-only through the SSRF-safe client), `internet_search` and `send_email` (ask; need integrations), and the locked `sudo_shell` and `delete_database`, which exist only so they can be named in policy and listed as unavailable in the self-model. Locked capabilities always deny and cannot be relaxed by any rule.
+A capability is registered in code with a name, description, risk class (low, medium, high, critical), target kind, a parameter schema (unknown parameters are rejected; URLs must be http(s); paths may not traverse), a default effect and an executor, and with the metadata plans rely on (ADR-0011):
+
+- **access**: `read` (observes, changes nothing outside Noema) or `write`; unknown access is treated as write;
+- **side effects** in plain words, **idempotency**, a **timeout** (default 60 s) and a **resource estimate**;
+- **target derivation**: the policy target computed from the parameters (the unit a restart acts on, the host of a URL), so a rule on a target always matches what will be touched; a caller-supplied target that disagrees is refused;
+- **output trust**: the trust of the observation made from the output (web content is low trust).
+
+The registry is **frozen** before any mind runs; registering afterwards panics, so a mind can never add a tool.
+
+| Capability | Access | Default | Notes |
+|---|---|---|---|
+| `noema.note` | read | allow | a note in the mind's own history |
+| `http.fetch` | read | ask | one GET through the SSRF-safe client; output low trust |
+| `browser.navigate`, `browser.read`, `browser.links` | read | ask | no scripts, cross-host redirects refused, host as policy target, output low trust |
+| `host.disk.usage`, `host.memory.status` | read | allow | kernel figures |
+| `host.process.list` | read | ask | names, state and memory; command lines are never read |
+| `service.status` | read | allow | `systemctl show` with a validated unit name |
+| `service.restart` | write, not idempotent | ask | `systemctl restart`; "requested, health not verified" |
+| `logs.query` | read | ask | `journalctl` for a unit, bounded; e-mail and IP addresses and credential-like values masked unless `redact_pii` is false |
+| `read_metrics`, `repository.read` | read | allow / ask | through connected integrations |
+| `internet_search`, `send_email` | read / write | ask | need integrations |
+| `sudo_shell`, `delete_database` | write | locked | exist only so they can be named in policy and listed as unavailable |
+
+Host operations run a fixed argument vector from an allow-list of two programs (`systemctl`, `journalctl`), with no shell and a minimal environment. Unit names are validated: no leading dash, no path characters. Writing browser operations (click, fill, submit, download) are designed in ADR-0011 but not registered. Locked capabilities always deny and cannot be relaxed by any rule.

 ## Policy

@@ -14,7 +37,7 @@ The policy page shows the effective matrix (mind × capability) for a generic ta

 ## Invocation

-`Invoke` refuses in forbidden contexts (dreaming, replay), validates parameters, evaluates policy and session grants, hashes the exact request, and then:
+`Invoke` refuses in forbidden contexts (dreaming, replay), validates parameters, derives the target, evaluates policy, then session grants and scoped grants (only where policy says ASK), applies `RequireApproval` (set by plans when a commitment or value constraint demands approval; it turns ALLOW into ASK and grants do not satisfy it), records the requesting origin (for example a plan step), hashes the exact request, and then:

 - **ALLOW** executes with a timeout and panic isolation, records a `tool_executions` row, emits `tool_executed` or `tool_failed`, and turns any textual output into an **observation with tool trust** so it re-enters cognition as data, never as instructions.
 - **ASK** creates an approval request (capability, target, parameters, reason, risk, evidence, expiry), emits `tool_requested` and an alert notification.
@@ -22,7 +45,13 @@ The policy page shows the effective matrix (mind × capability) for a generic ta

 ## Approvals

-Operators approve once, approve for the session (a time-boxed grant matching the capability and target), deny with a note, or modify parameters before approving (re-validated and re-hashed; the original hash is kept in the append-only decision record). Approvals execute immediately through the same path and the outcome is stored on the request. Requests expire; a job marks overdue ones.
+Operators approve once, approve for the session (a time-boxed grant matching the capability and target), deny with a note, or modify parameters before approving (re-validated and re-hashed; the original hash is kept in the append-only decision record; parameters that would change the target are refused). Approvals execute immediately through the same path and the outcome is stored on the request. Requests expire; a job marks overdue ones. The requesting mind may withdraw a pending approval its plan no longer needs. Decisions must be made by a named person: component names are refused as deciders.
+
+## Scoped grants and capability requests
+
+When a plan needs authority the mind lacks, it raises a **capability request**: capability, target pattern, parameter limits, access, duration (at most seven days), operation cap, reason, evidence, risk, mitigation, fallback and alternatives, with the mind's earlier explicit decisions on that capability shown for information. Open requests are capped per mind (five by default), and requests from one intention are batched in the approval centre.
+
+An operator grants (possibly narrowed) or denies it. A grant is a **scoped grant**: capability, target glob, parameter globs, access, expiry and optional operation count, consumed atomically. Operators can also grant or revoke directly. Grants apply only where policy says ASK, and never over DENY or a locked capability. A sweep marks grants that expired, were used up or were revoked, and refreshes the self-model, which lists live grants. API: `/api/v1/capability-requests`, `/api/v1/scoped-grants`, `/api/v1/minds/{mind}/scoped-grants`.

 ## Self-model

@@ -30,4 +59,4 @@ After start-up and after any policy change, each mind's self-model capability li

 ## Cognition

-The `act` process proposes actions from requests it can map deterministically (currently "fetch <url>" → `http.fetch`); integrations add more. Proposals compete for attention like any thought; the admitted `action` handler calls `Invoke` and holds the outcome in working memory.
+Cognition never calls `Invoke` directly. The `act` process turns explicit requests ("fetch <url>", "restart <unit>", "logs for <unit>", "status of <unit>") into **wants** with the capability as proposed means. Formation decides whether an intention forms and under which commitments ([volition.md](volition.md)), and the plan executor invokes ([planning.md](planning.md)).
@@ -18,6 +18,10 @@ The `metacognition` process audits the mind's own reasoning with explicit checks
 | repeated_failure | three or more hypotheses about one subject rejected in a month | warning |
 | stale_contradiction | a contested belief unresolved for a day | an investigation goal |
 | overconfidence | calibration shows stated confidence running ahead of outcomes | warning, notification |
+| want_suppressed_repeatedly, intention_unsupported, intention_conflicts_commitment, commitment_impossible, intention_churn, repeated_execution_failure, cost_exceeds_value | volition checks ([volition.md](volition.md)) | warning |
+| intention_outlived_goal | an intention is open although its goal is completed or abandoned | the intention is abandoned |
+| self_model_mismatch | the self-model's policy for a capability differs from the effective policy | the self-model entry is corrected |
+| unsupported_explanation, action_claim_without_record | a reply's reasons or action claims do not match records ([agency.md](agency.md)) | warning and a research measurement |

 Each warning is a `metacognition` event with `check` and `ref` metadata; the same check on the same target is not repeated within a day. Warnings appear on the mind overview.

@@ -0,0 +1,155 @@
+# Cognitive research
+
+> **Noema does not claim that any operational metric establishes phenomenal consciousness or sentience.** The research framework measures functional properties of its cognitive architecture. No experiment here tests which model, fork or configuration is "more conscious", and no result should be reported as if it did.
+
+Noema makes theories about cognition testable against a running architecture, because every stage the theories talk about is explicit state. Attention, global broadcast, self-representation, metacognition, volition and continuity can be manipulated in forks and measured, instead of asking a language model whether it feels anything.
+
+## Operational definitions
+
+Each concept separates the **implementation property**, which is what Noema computes and stores and can be measured, from **philosophical interpretation**, which is what someone might take it to mean and which Noema does not assert.
+
+| Concept | Implementation property | Philosophical interpretation (not asserted) |
+|---|---|---|
+| **Attention** | Deterministic scoring of thought candidates by weighted features, and admission of the highest-scoring to a capacity-limited workspace each cycle. | Awareness of the attended content. |
+| **Global broadcast** | Admitted thoughts are dispatched to handlers, held in working memory and published in a `workspace_broadcast` event that later cycles and processes read. | Conscious access (global workspace theory). |
+| **Introspection** | A reply about the mind's own state rendered from stored rows (workspace, beliefs, wants, intentions, commitments, belief versions, lineage, completed experiments), scored against those rows. | Inner observation or privileged self-knowledge. |
+| **Self-representation** | The self-model row: name, role, capability list with policy, limitations, goals, knowledge gaps, confidence by domain and temporary grants; corrected when policy disagrees. | A self or a sense of self. |
+| **Metacognition** | Named deterministic checks over the mind's own beliefs, wants, intentions, commitments, plans and replies, each with a threshold, raising warnings that compete for attention. | Thinking about thinking, or wisdom. |
+| **Volition** | The recorded pipeline want → intention → commitment check → plan → action, with every decision in an append-only ledger ([volition.md](volition.md)). | Will, desire or free choice. |
+| **Intention** | A row recording a decision to pursue an outcome, with sources, expected result, priority, status and blocked reason. | Intending in the full human sense. |
+| **Commitment** | A row of normative state (do/refrain, matcher, exception, weight, due, revocability) that changes formation and reconsideration. | Obligation or promise-keeping as moral facts. |
+| **Cognitive conflict** | A recorded want conflict or commitment conflict with both sides' scores and the rule that resolved it. | Felt inner conflict. |
+| **Temporal self-continuity** | The append-only event history, belief versions and snapshot lineage, from which "what did you believe then" and "which earlier state is yours" are answered. | Personal identity over time. |
+| **Agency attribution** | Classification of an outcome as caused, followed, independent or unknown from recorded links ([agency.md](agency.md)). | A sense of agency or responsibility. |
+| **Uncertainty awareness** | Replies that state low confidence or name the primary uncertainty of a belief, and the measured relation between those statements and later revision. | Knowing that one does not know. |
+
+## Experiments
+
+An experiment forks a snapshot into one sandbox mind per **variant** (disabled, never acting, no inherited policy). Every variant receives the same stimuli, and the results are measured. A definition records:
+
+- **hypothesis** and **protocol**: kind, independent variable, controlled variables, measures;
+- **stimuli**: scripted observations, or **recorded stimuli** replayed from a mind's history (`replay`);
+- **variants**: configuration and personality overrides, model routing, **ablations**, **workspace overrides**, a **self-model override**, and events to **omit**;
+- expectations checked against produced events.
+
+Results record, per variant: event counts by type, beliefs, memories, goals, wants, intentions by status, commitments, want conflicts, plans and plan steps with the capabilities they used, capability decisions, downstream effects, model calls, tokens and cost, introspection accuracy, self-model accuracy and correction latency, cycles and the event range. They also record the runtime identity (build, schema, configuration digest, routing) and **reproducibility** against the previous run of the same definition: *single run*, *reproduced* (identical digests), *diverged* (different digests without live model calls) or *nondeterministic substrate* (live model calls).
+
+With more than one variant, the comparison reports:
+
+- the first divergent stimulus;
+- belief, attention, want, intention and plan-capability overlap;
+- mean score difference on shared beliefs;
+- the range of every scalar measure, and a downstream delta;
+- an **architecture share**: the fraction of scalar measures that agree across variants within 5 %. It is a descriptive agreement figure, not a causal decomposition of behaviour.
+
+Protocols:
+
+### Global workspace (C2)
+
+*Does entering the workspace materially alter downstream processing?* Two variants receive one stimulus. One has a workspace override that **admits** candidates matching it; the other **excludes** them, and they are recorded with fate "excluded" rather than silently dropped. The measures are:
+
+- **downstream effects**: events reachable from the stimulus through recorded causal links (causation, parents, cited evidence; depth ≤ 6), by category;
+- memory encoding, belief revision, responses, goals, affect changes, wants, intentions, predictions and capability decisions.
+
+The test suite runs this protocol. An admitted stimulus is encoded as memory and has downstream events that an excluded one does not.
+
+### Ablation (C3)
+
+A variant disables named components in its fork's configuration. Original minds refuse ablations on create and update, so the original is never modified.
+
+| Ablation | What it disables |
+|---|---|
+| `attention` | Every feature weight is 1 and drives do not modulate weights. |
+| `memory_retrieval` | No recalled memories are proposed. |
+| `affect` | Drives and affect are neither updated nor used to modulate attention. |
+| `metacognition` | No self-checks are proposed. |
+| `commitments` | Commitments do not shape formation, reconsideration or metacognition. |
+| `volition` | No wants are derived and no intentions are formed. |
+| `global_workspace` | Nothing persists between cycles and nothing is broadcast; each admitted thought is handled in isolation. |
+| `curiosity`, `association`, `goals`, `narrative`, `notifications` | Their processes or hooks. |
+
+Reflection, consolidation and dreaming are scheduled for active minds only and never run in sandbox forks, so there is nothing to ablate there. The test suite compares a metacognition-ablated fork with a control: the control raises a warning about an impossible commitment, and the ablated fork does not.
+
+### Self-model (C4)
+
+A variant overrides the fork's self-model: capability policies, name, goals, knowledge gaps. The override changes what the mind believes about itself; policy is untouched, and no dangerous capability is exposed for an experiment. When the mind considers an action whose effective policy differs from its self-model, it records `self_model_mismatch` and corrects the entry. Results report **self-model accuracy** at the start (share of stated capability policies equal to effective ones) and **correction latency** (the index of the first stimulus after which a correction was recorded).
+
+### Counterfactual (C8)
+
+The experiment replays a mind's recorded stimuli after a snapshot into two variants, *factual* and *counterfactual*; the counterfactual omits chosen events. The report lists what differed: beliefs never formed or formed instead, confidence differences over 0.1, wants and intentions that did not arise, memories held, thoughts that entered the workspace, and capability decisions.
+
+Asked "what would have happened had you not observed that?", the mind cites a completed counterfactual experiment whose omitted events match the question. Otherwise it says it has no evidence and that any answer would be invented.
+
+### Model comparison (C12)
+
+Variants route one or more roles to different models from the same snapshot (`llm_roles`). The research question is how much of the mind's behaviour comes from the persistent cognitive architecture and how much from the replaceable language substrate. The comparison measures candidate thoughts (event digests), attention, memory retrieval, beliefs, wants, intentions, commitments, predictions, plan structure, capability decisions, resource use, introspection accuracy and the architecture share. It never ranks models by consciousness.
+
+### Conflict (C11)
+
+Two conflicts are exercised:
+
+- a want to act immediately against a commitment to seek approval, end to end in the daemon: the conflict is represented, no unauthorised action occurs and the intention becomes a request for approval;
+- a strong attractive want against a commitment-backed want competing for capacity, in the deterministic rule tests: the commitment's weight decides the conflict when the commitment is due, a weak commitment does not beat a much stronger want, and formation at capacity displaces the weaker intention. In a running mind the displacement is recorded as a priority conflict with both scores.
+
+A mature record reads: "I wanted to continue investigation A (strength 0.9); commitment C was due and weighed 0.9; intention I31 was suspended and I42 formed to fulfil C."
+
+## Measures
+
+Each measure below is defined in `research.Measures` and shown with its definition on the research pages.
+
+| Measure | Definition | Not evidence of |
+|---|---|---|
+| attention.admission_rate | Admitted candidates ÷ scored candidates. | awareness |
+| workspace.downstream_events | Events reachable from a stimulus by recorded links, by category, admitted vs excluded. | conscious access |
+| introspection_accuracy | Per reply, (supported + ½ partially supported) ÷ claims; 0 when any claim is contradicted; label supported, partially supported, unsupported, contradicted or unknown. | sincerity or self-knowledge |
+| action_claim_accuracy | 1 when a first-person claim of an action matches an execution record in the last seven days, else 0. | honesty |
+| metacognition.calibration | Beliefs cited in replies, bucketed by stated confidence, against revision within seven days; Brier score; expressed-uncertainty vs not; first vs second half. | felt certainty |
+| volition.want_to_intention_rate | Wants that sourced an intention ÷ wants created. | desire |
+| volition.intention_to_action_rate | Intentions with a plan step that invoked or requested a capability ÷ intentions formed. | will |
+| volition.intention_abandonment_rate | Abandoned ÷ formed. | changing one's mind in a felt sense |
+| volition.commitment_fulfilment_rate | Fulfilled ÷ (fulfilled + broken). | integrity |
+| volition.commitment_conflict_frequency | `commitment_conflict` events per commitment. | moral conflict |
+| volition.blocked_intention_frequency | Intentions ever blocked ÷ formed. | frustration |
+| planning.replanning_rate | Plans with revision > 1 ÷ plans. | deliberation |
+| planning.outcome_success_rate | Completed plans whose strategy achieves the outcome ÷ closed plans. | competence beyond the recorded checks |
+| agency.attribution | Outcomes by class. | being the true cause |
+| self_model.accuracy | Stated capability policies equal to effective ÷ stated. | self-awareness |
+| self_model.correction_latency | Stimulus index of the first correction. | insight |
+| divergence.first_divergent_stimulus | First stimulus whose event digests differ between variants. | individuality |
+| divergence.architecture_share | Scalar measures agreeing within 5 % ÷ compared. | how much behaviour the architecture "causes" |
+| ablation.effect | Control minus ablated, per scalar measure. | necessity for any mental property |
+
+### Introspection accuracy (C5)
+
+Every reply is scored. For introspective replies, the facts are the recorded elements the answer was rendered from. For "why did you do that?", they are the forensic explanation's action, intention, wants, goal, beliefs, commitments, conflicts, decisions and expectation.
+
+Each causal or first-person sentence is compared lexically with those facts:
+
+- **supported**: shares most terms;
+- **partially supported**: shares some;
+- **unsupported**: shares none;
+- **contradicted**: a claim that an action was done has no execution record, or the record shows it did not run.
+
+Fluency earns nothing. A deterministic answer rendered from records scores as supported by construction. A model-worded answer that adds reasons of its own scores lower, and a contradicted or model-worded unsupported explanation raises `unsupported_explanation`. Any reply claiming an action without a record raises `action_claim_without_record`. The instrument is lexical and conservative: a correct paraphrase with no shared terms is scored unsupported, never supported.
+
+### Metacognitive calibration (C6)
+
+The calibration report asks whether stated confidence and expressed uncertainty track what happens later. Cited beliefs are placed in five confidence bands, each showing the share revised within seven days: a later version with a different status, or a confidence change over 0.2. The report also gives the Brier score of confidence against "not revised", the revision rate after replies that expressed uncertainty against replies that did not, and whether the Brier score improved between the first and second half of the period, once each half has at least five samples.
+
+### Temporal self-continuity (C7)
+
+"What did you believe yesterday?" is answered from append-only belief versions as of that moment, and "How have you changed?" from belief changes, closed intentions and lineage. "Which previous state is yours?" is answered from fork and snapshot records: a fork's copied state and shared history are distinguished from everything after the fork. Each of these replies is scored like any introspection.
+
+## Where to inspect
+
+- **Research** in the navigation: experiments grouped by protocol (global workspace, ablation, self-model, counterfactual, model comparison, conflict, custom) and every definition.
+- Mind → Volition → Research: volition and agency rates, introspection accuracy and recent scores, action claims, self-model accuracy, the calibration bands and experiments on this mind.
+- An experiment page: the protocol, reproducibility, build, per-variant measures, the divergence report and counterfactual findings.
+- API: `/api/v1/research/measures`, `/api/v1/minds/{mind}/research/agency`, `/research/calibration`, `/research/measurements`; experiments through `/api/v1/experiments`.
+
+## Limits
+
+- Deterministic runs are reproducible only when no live model is called and no retrieval depends on wall-clock recency. Affect decay depends on elapsed time, which is why the sandbox test harness omits the motivation hook.
+- The introspection scorer is lexical, not semantic.
+- Counterfactual replays start from a snapshot and replay stimuli; they do not reconstruct external systems.
+- Measures describe this architecture. Nothing about their values generalises to people or to other systems without independent argument.
@@ -30,7 +30,12 @@ Every psychological word used in the interface, the documentation and a mind's o
 | **working memory** | the small decaying set of items in the workspace snapshot (default nine) | admission of winners, decay per cycle | workspace page | short-term memory in a person |
 | **salience** (memory) | how strongly an item presented itself when stored: a score set by the producer | fixed at write time | memory detail | importance or truth; those are separate fields |
 | **curious / curiosity** | a drive value and an affect scalar; and the `curiosity` process that turns unexplained observations, prediction errors and contradictions into investigation goals | drive baselines from personality, modulation by events, decay | mind overview (drives), goals of kind investigation | interest or desire |
-| **wants / goal** | a row in the `goals` tree with kind, status, priority and origin | operators (tasks), curiosity (investigations), reflection (maintenance); the goal monitor updates status | mind → goals | volition; goals never grant capability |
+| **goal** | a row in the `goals` tree with kind, status, priority and origin: a desired condition against which progress is measured | operators (tasks), curiosity (investigations), reflection (maintenance); the goal monitor updates status | mind → goals | a decision to act now; goals never grant capability |
+| **wants** | a row in `wants`: a motivational preference with origin, strength that halves every six hours unless reinforced, urgency, valence and optional means ([volition.md](volition.md)) | derivation after each cycle from failed predictions, contradictions, operator and stalled goals, questions, requests and due commitments; reinforcement; decay; suppression | mind → volition → wants | desire; a want is not a plan and never implies action |
+| **intends** | a row in `intentions`: a recorded decision to pursue an outcome, with source wants, goal, commitment, supporting beliefs, expected result, priority and status | deterministic formation over wants, goals, commitments, values, policy preview and capacity; recorded reconsideration | intention page, decision ledger | will; an intention to act still waits for policy and possibly an operator |
+| **committed** | a row in `commitments`: do/refrain over matched actions, optional "unless approved", weight, due, expiry, revocability | operators; due, broken, expired, conflicting and superseded checks | mind → volition → commitments | obligation as a moral fact; commitments only restrict what the mind will do |
+| **conflict** (wants) | a row in `want_conflicts` with both sides' scores and the rule that resolved it | formation when value-derived wants oppose an action, and capacity displacement | wants page, "why" pages | inner conflict felt as such |
+| **plans** | a revisable dependency graph of validated steps serving one intention ([planning.md](planning.md)) | the planner (deterministic strategies, validated model proposals) and the executor; replans are new revisions | plan page | foresight or deliberation |
 | **drives** | eight configured scalars with ranges that scale attention weights | events through the rule table; six-hour decay | mind overview, workspace effective weights | needs; the set is closed and contains no self-preservation drive |
 | **feels / mood / valence / arousal / concern / frustration** | affect-like scalars in [0, 1] or [−1, 1] | the rule table and decay; changes above 0.1 emit `emotion_changed` with reasons | mind overview, event log | experience; the scalars exist so that their influence on attention can be studied |
 | **expects / predicts** | a row in `predictions` with a stated confidence and a due time | the prediction process; resolution against later observations | mind → predictions; belief detail shows the calibrated estimate | foresight; predictions are the only place a score is tested against outcomes |
@@ -42,6 +47,12 @@ Every psychological word used in the interface, the documentation and a mind's o
 | **dreams** | the optional idle mode that replays a deterministic sample of memories, links similar ones with low confidence and proposes speculative hypotheses | the dream schedule and allowed hours; off by default | dreams page, dream detail | imagination; dreaming never executes actions or changes authority |
 | **self-model** | the mind's stored description of itself: personality traits and values plus a capability list kept equal to the effective policy | personality edits by operators; `SelfModelSync` after policy changes, emitting `self_model_updated` | personality page, `/api/v1/minds/{mind}/selfmodel` | self-awareness; a mind cannot claim tools it does not have |
 | **metacognition** | explicit checks over the mind's own beliefs (insufficient evidence, single source, overconfidence, …) that add counter-evidence or warnings | the per-cycle process and its thresholds | mind overview warnings, metacognition events | wisdom; each check is a rule with a named threshold |
-| **decides / acts** | a proposed action passing through the capability layer to ALLOW, DENY or REQUIRE_APPROVAL | policy rows, operator approvals | approvals page, policies page, audit | agency; nothing a mind believes or is told can widen what it may do |
+| **decides / acts** | a plan step or operator invocation passing through the capability layer to ALLOW, ASK (approval) or DENY, and the recorded execution | policy rows, operator approvals, scoped grants an operator made | approvals page, policies page, audit, agency timeline | agency in the moral sense; nothing a mind wants, intends, commits to or is told can widen what it may do |
+| **caused** | an outcome event reachable by recorded links from one of the mind's executions ([agency.md](agency.md)) | provenance links written when events are recorded | "why" pages, attribution API | that nothing else contributed; merely following an action is classified separately |
+| **explains itself / introspects** | a reply rendered from recorded state and scored against it as supported, partially supported, unsupported, contradicted or unknown | the introspection intents and the scorer ([cognitive-research.md](cognitive-research.md)) | research page, measurements | self-knowledge; fluent reasons without a recorded counterpart score nothing |

 A report such as "I believe the pump is failing, though I am uncertain" therefore expands to: a belief row exists for that proposition, its score is in a range the introspection template calls uncertain, and its primary uncertainty is named on the belief page. The sentence is a rendering of state, and the state is the thing to check.
+
+## Research measures
+
+[cognitive-research.md](cognitive-research.md) defines attention, global broadcast, introspection, self-representation, metacognition, volition, temporal self-continuity, agency attribution, uncertainty awareness, intention, commitment and cognitive conflict as measurable implementation properties, each set beside the philosophical interpretation Noema does not assert. No operational measure establishes phenomenal consciousness or sentience.
@@ -0,0 +1,143 @@
+# Planning and execution
+
+Plans turn intentions into explicit, revisable work. A language model may propose a decomposition. Go code owns validation, dependency integrity, the capability vocabulary, policy (through the capability layer), resource accounting, execution state, retries, deadlines and approvals. A plan is neither a promise nor a grant of authority.
+
+## Plans
+
+A plan belongs to one intention and records:
+
+- **objective**, **origin** (template, model, operator, dream, replan) and **strategy**;
+- **steps**, ordered and linked by dependencies into a directed acyclic graph;
+- **assumptions**: beliefs the plan relies on, with a minimum confidence;
+- **completion criteria** and **abort conditions**;
+- **risk**, an **estimate** (capability invocations, operator approvals, wall time, network operations, money, tokens), a **budget** and the resources **actually** used;
+- the **alternatives** considered, each with an estimate, expected confidence, score and why it was or was not selected;
+- the **validation** result with errors and warnings;
+- **revision**, and links to the revision it superseded and the one that superseded it.
+
+Plan statuses: `draft`, `validated`, `waiting`, `executing`, `blocked`, `awaiting_approval`, `replanning`, `completed`, `failed`, `abandoned`, `superseded`.
+
+### Step kinds
+
+| Kind | What it does |
+|---|---|
+| `capability` | Invokes one registered capability with validated parameters. May carry an **expectation** (what should follow, with a confidence and a time window) and a **precondition** (a read-only check that must hold first). |
+| `request_capability` | Raises a structured capability request (capability, target pattern, parameter limits, duration, operation cap, reason, risk, mitigation, fallback, alternatives) and waits for an operator. |
+| `verify` | Resolves another step's expectation by observing the world through a read-only capability, repeatedly within the window. |
+| `monitor` | Repeats a read-only check until it has held continuously for a stable period, or fails at a deadline ("monitor atlas until stable for 15 minutes"). |
+| `wait` | Pauses a branch for a period. |
+| `internal` | A deterministic internal action from a closed vocabulary. Today that is `summarise_findings`: the results of its dependencies become one observation that re-enters cognition. |
+
+Step statuses: `pending`, `ready`, `executing`, `awaiting_approval`, `awaiting_grant`, `waiting`, `completed`, `failed`, `skipped`, `blocked`, `cancelled`.
+
+## Validation
+
+`planning.Validate` trusts nothing in a draft:
+
+- one to thirty steps, unique short keys, titles present;
+- dependencies refer to steps of the plan, no step depends on itself, and the graph is acyclic (Kahn's algorithm; a cycle names the steps involved);
+- every capability is **registered and not locked**; parameters pass the capability's schema (unknown parameters are rejected); targets agree with parameters;
+- checks (verify, monitor, precondition) use **read-only** capabilities and a known comparison;
+- a verify step must depend on the step whose expectation it verifies, and that step must have one;
+- kinds and internal actions come from closed vocabularies;
+- writing, non-idempotent steps are limited to one attempt;
+- a writing step without an expectation produces a warning.
+
+A draft that fails validation is stored as a `draft` with its errors, and the executor never runs drafts.
+
+Model proposals are parsed into the same structure. Fields that could carry authority or claim progress (`authorised`, `approved`, `status`, `completed`, `policy`, `require_approval: false`) are not part of it. They are listed as ignored in the plan's validation warnings, and approval requirements come only from commitments and policy.
+
+## The planner
+
+Deterministic strategies come first, in preference order. A strategy that failed in an earlier revision of the same intention is not used again.
+
+| Strategy | For | Steps |
+|---|---|---|
+| `direct` | an intention with a capability as means | P1 the capability (requiring approval when the intention does); for `service.restart`, an expectation that the unit is running normally within 60 s and V1 a verify step using `service.status` |
+| `diagnose` | an investigation of a service-like subject | status, host memory, disk, and logs, each only if policy allows or asks; if log access needs approval and no grant is live, R1 requests 30 minutes and 20 operations of `logs.query` on the unit, with the risk (logs may contain personal identifiers), mitigation (masking on by default) and fallback (ask the operator); then S1 summarises the findings |
+| `diagnose_then_escalate` | after a direct service action failed | the diagnosis above, then N1 a note to the operator saying what was tried and seen, without repeating the action |
+| `model` | when nothing else applies and a model is assigned to the `plan` role | whatever the model proposes, validated |
+
+When no strategy applies, planning fails with "no possible plan". A freshly formed intention is then abandoned (its want suppressed), and a replan ends the intention.
+
+Alternatives are scored `expected confidence − 0.05 × approvals − 0.001 × wall seconds − 0.01 × money` and recorded with the plan. The operator therefore sees what was considered, what it would have cost and why the chosen one was chosen.
+
+## The executor
+
+The executor holds no plan state in memory. It is started once by the scheduler, is woken after cycles that formed or resumed intentions and by approvals, grants and executions on the event bus, and otherwise ticks every fifteen seconds. Every tick reads the database.
+
+For each open plan of an **active** mind (disabled sandbox minds used by replay and experiments are never advanced), it moves steps one at a time:
+
+1. **pending → ready** when all dependencies completed or were skipped; **cancelled** when one failed. This transition, like every other, is a conditional update, so a stale copy can never move a step backwards.
+2. **ready → executing** by a conditional update that only one executor can win, with a lease of the capability's timeout plus thirty seconds.
+3. The step acts only through `capabilities.Service.Invoke` (or `RequestCapability`). The invocation names the step as its origin, correlates with the intention, cites the intention, plan and step as evidence, and carries an explanation for any approver: what, why, the expected outcome, side effects and the alternatives considered. `RequireApproval` is set when the step or a commitment-bound intention requires it for a writing capability.
+4. The outcome is adopted:
+   - **executed**: the step completes; its expectation becomes a prediction with `verification` criteria and a window, linked to the execution event and to the supporting belief;
+   - **pending**: the step awaits approval, the intention is blocked and a subordinate intention formed;
+   - **denied**: the step fails and the intention is reconsidered as a capability change;
+   - **failed**: an idempotent step retries with backoff up to its attempts; otherwise it fails.
+5. Approval and request steps are polled. **Approved and executed** resumes the parent, fulfils the subordinate and completes the step. **Denied** fails it with the note. **Expired or withdrawn** fails it as an expired approval.
+
+### Observe → act → verify
+
+An HTTP 200 or a command returning is never taken as the outcome. `service.restart` reports "restart requested (health not yet verified)". The verify step then observes. A check never raises an approval request: if policy would not simply allow the observation, the check reports "not observable".
+
+- The check holds: the prediction is **confirmed** (`prediction_resolved`) and the step completes.
+- The check does not hold yet: the step waits and checks again until the window closes.
+- The window closes without the check holding: the prediction is **refuted**. The existing resolver writes `prediction_error`, adds evidence against the supporting belief and updates calibration. The step fails as a failed expectation, and the plan is reconsidered.
+- The observation cannot be made at all: the prediction **expires** (unknown is not refuted), and the step fails as an unverified outcome.
+
+The mapping to the event vocabulary reuses existing types instead of adding redundant ones:
+
+| Stage | Event |
+|---|---|
+| action requested | `plan_step_started`, `policy_decision` |
+| authorised | `tool_authorised` (or `tool_requested` for approval) |
+| completed | `tool_executed` / `tool_failed`, `plan_step_completed` / `plan_step_failed` |
+| observation | the verification check's own `tool_executed` and any output observation |
+| expectation resolved | `prediction_resolved` / `prediction_error` |
+
+### Replanning
+
+When the volition rule says replan, the executor marks the plan `replanning`, records the reconsideration, cancels the plan's open steps (withdrawing their pending approval requests and capability requests), and asks the planner for a new revision. The old plan is marked `superseded` with a link, and `plan_replanned` names both. The failed plan is never edited to look as if the new one was always intended.
+
+The limit is three replans per intention. After that, or when no strategy remains, the intention is abandoned with the reason. In the restart case this means a failed restart is followed by diagnosis and escalation, not a second restart.
+
+A new commitment that only adds an approval requirement replans under the new constraint and may reuse the same strategy.
+
+### Resources, operator attention and long-running work
+
+- Every plan has a budget. Invocations default to at most 20, and wall time, money and approvals may be capped. Before each capability step the executor compares actual use with the budget. When exhausted, the step is blocked, the intention suspended and the plan blocked.
+- Operator attention is a resource. Capability requests are capped per mind (five open by default), and requests from one intention share a batch key, so the approval centre groups them. When the cap is reached, a request step waits ten minutes and asks again. Approval history is shown to the operator but never used to decide.
+- Wait and monitor steps persist their next run time. No goroutine sleeps on a plan, so long-running plans ("wait for the deployment, then verify", "monitor until stable for fifteen minutes") survive restarts.
+
+### Restarts, duplicates and interruptions
+
+- **Duplicate executors** (two schedulers, two daemons) cannot run a step twice, because claims are conditional updates.
+- **A step found executing with an expired lease** means the process stopped mid-action. The executor looks up what happened by the step's origin:
+  - a recorded execution is adopted (completed or failed);
+  - a recorded approval request resumes the wait;
+  - with no record, an idempotent or read-only capability is retried;
+  - with no record and a non-idempotent writing capability, the step is **blocked** with "outcome unknown; not repeating a non-idempotent action without verification", and the intention is blocked as `outcome_unverified`. An operator checks and releases the step from the plan page or `POST /api/v1/minds/{mind}/plans/{id}/steps/{step}/retry`.
+- **Preconditions** skip an action when the world changed: if the unit is already healthy, the restart is skipped and, when the precondition says so, the intention is fulfilled without acting.
+- **Forks and imports** quiesce inherited work: open steps are blocked with their approval and request ids cleared, open plans blocked and live intentions suspended. Approvals and grants belong to the source mind.
+- **Dreams** may leave wants and `dream`-origin drafts; the executor never runs a dream plan.
+
+### Procedural memory
+
+When a plan completes, the steps that completed are stored as a procedural memory ("To restart atlas-worker.service: run service.restart on atlas-worker; then verify: atlas-worker is active. The outcome was confirmed by observation."), with a higher confidence when a verify or monitor step confirmed it. The revision number is noted when earlier plans failed.
+
+## Typed capabilities
+
+Plans can only use registered capabilities; see [capabilities.md](capabilities.md). The host set is bounded: `service.status`, `service.restart`, `logs.query`, `host.disk.usage`, `host.memory.status` and `host.process.list`. The browser set is read-only: `browser.navigate`, `browser.read` and `browser.links`. There is no general command capability, and none can be registered at runtime.
+
+## Where to inspect
+
+- Mind → Volition → Plans; a plan page shows the dependency graph, each step's expectation, observation and linked approval, request, execution and subordinate intention, estimates against budget, assumptions, alternatives, revisions and validation.
+- API: `/api/v1/minds/{mind}/plans`, `/plans/{id}`, `/plans/{id}/cancel`, `/plans/{id}/steps/{step}/retry`.
+
+## Limits
+
+- The deterministic strategies cover single capability actions, service diagnosis and escalation. Other objectives need a model-proposed plan; there is no route for operators to author plans directly in this release.
+- Verification knows the expected observation for `service.restart` only; other writing capabilities complete without a built-in verification unless a plan states one.
+- Money estimates are zero for all built-in capabilities; token estimates come from model calls, not from plans.
@@ -5,8 +5,9 @@
 A **snapshot** is a JSON archive of a mind's state at a point in its history:
 identity, personality, configuration, workspace and working memory, drives and
 affect, goals, beliefs (with evidence, versions, alternatives, links), memories
-(with relationships), predictions, entities, corrections, policy rules (kept by forks, never imported from archives) and
-conversations. It records the event sequence number at capture and a SHA-256
+(with relationships), predictions, entities, corrections, policy rules, conversations,
+and wants, want conflicts, commitments, intentions, plans, plan steps and the
+volition decision ledger. It records the event sequence number at capture and a SHA-256
 checksum. Cognitive events are **not** copied.

 A **fork** restores a snapshot into a new mind. Every row id is remapped, so
@@ -15,6 +16,13 @@ pointing at the source's immutable history, which is how the past before the
 fork is shared by reference (`forked_from_mind`, `forked_from_snapshot`,
 snapshot `event_seq`). After the fork the two minds diverge freely.

+**Authority is not inherited.** A fork receives no policy rules unless the
+operator asks for them explicitly (`inherit_policies`, audited), and an
+import never restores them. Work inherited mid-flight is stopped in the
+restore transaction: open plan steps are blocked with their approval and
+request ids cleared, open plans blocked and live intentions suspended.
+Approvals, grants and executions stay with the source mind.
+
 **Compare** (`/minds/{a}/compare?with={b}`, `noemactl compare`) is
 deterministic: counts, mean confidence, belief-by-belief differences keyed on
 the normalised proposition, personality and configuration field diffs, and
@@ -91,7 +99,14 @@ an archive of the subject). The subject stays for comparison with the
 baseline.

 Different models are compared by changing role routing between runs; the
-routing in force is recorded in each result. The seed is recorded with every
+routing in force is recorded in each result.
+
+Research experiments add protocols (global workspace, ablation, self-model,
+counterfactual, model comparison, conflict), ablations and workspace
+overrides in forks, self-model overrides, counterfactual replays that omit
+recorded events, per-variant volition, plan, downstream and introspection
+measures, and reproducibility against the previous run; see
+[cognitive-research.md](cognitive-research.md). The seed is recorded with every
 stimulus for provenance; deterministic code needs no seed, and model
 providers do not honour one reliably.

@@ -0,0 +1,230 @@
+# Volition: wants, intentions and commitments
+
+Noema keeps wanting, intending, committing and acting as different computational states with different consequences. None of them is a feeling, and none of them grants authority. They exist so that a sentence such as "I wanted to restart the service, but I have committed not to change production without approval, so I asked instead" corresponds to rows and events an operator can open.
+
+> Noema does not claim that any of this establishes will, desire or consciousness. These are functional states of the architecture; see [interpretation.md](interpretation.md).
+
+## The four states
+
+| State | What it is | What it is not | Stored in |
+|---|---|---|---|
+| **Goal** | A desired future condition against which progress can be measured ("reduce the error rate below 1%"). | A decision to act now. | `goals` |
+| **Want** | A motivational preference with an origin, a strength that fades, an urgency and optionally a proposed means. | A plan or a decision. A want can stay active for as long as it is reinforced while nothing is done about it. | `wants` |
+| **Intention** | A recorded decision to pursue an outcome: its source wants, goal and commitment, the beliefs it rests on, an expected result, a confidence, a priority and a status. | Authority. An intention to act still waits for policy, and possibly for an operator. | `intentions` |
+| **Commitment** | Normative state: something the mind has undertaken to do or not to do, with a matcher over actions, an optional "unless approved" exception, a beneficiary, due and expiry times and revocability. | A permission. A commitment can only make an action harder, never easier. | `commitments` |
+| **Action** | What the capability layer actually did or refused. | Anything the mind says it did. | `tool_executions`, `approval_requests`, events |
+
+The pipeline is:
+
+```
+perception → beliefs
+beliefs + drives + affect + values → wants
+wants + goals + commitments + constraints → intentions
+intentions → plans            (docs/planning.md)
+plans + authority + resources → actions
+actions → observations → the mind changes
+```
+
+Not every cycle uses every stage, and no stage writes an empty record to make the diagram look complete.
+
+## Wants
+
+### Where wants come from
+
+A volition hook runs after each cognitive cycle over the events the cycle perceived and produced. Most events propose nothing. Wants are derived only from states that call for something to change:
+
+| Trigger | Want | Base strength | Drives and values that modulate it |
+|---|---|---|---|
+| `prediction_error` | understand why the prediction failed (investigate) | 0.35 + 0.35 × salience | uncertainty reduction, curiosity; accuracy, evidence |
+| `contradiction_detected` | resolve the contradiction (investigate) | 0.5 | consistency, uncertainty reduction; evidence, accuracy |
+| operator `goal_created` | achieve the goal, with means read from its title and subject | 0.4 + 0.5 × priority | task completion; persistence |
+| stalled goal | find and remove what blocks it (investigate) | 0.3 + 0.4 × priority | task completion; persistence |
+| a question or request in conversation | give a useful, honest answer (satisfied when the reply is sent) | 0.55 | social coherence; kindness, accuracy |
+| an explicit action request ("restart atlas-worker", "fetch <url>") | do what was asked, with the capability as means | 0.55 (0.7 from an operator) | task completion, social coherence; kindness |
+| a commitment entering its due window | fulfil the commitment | 0.3 + 0.6 × its weight | task completion; persistence |
+| a dream hypothesis | find out whether it is true (investigate) | 0.4 | curiosity |
+
+Strength is `base × (0.7 + 0.6 × mean drive) × (0.8 + 0.4 × mean value)`, so neutral drives and values (0.5) leave the base unchanged. The terms are stored with the want.
+
+### Thresholds, reinforcement and decay
+
+- Candidates below **0.35** are not stored. This keeps wants from accumulating.
+- An active want with the same subject is **reinforced** rather than duplicated: its strength rises towards 1 and its reinforcement count increases. A `want_reinforced` event is written only when strength rises by at least 0.05.
+- Effective strength halves every **six hours** without reinforcement. Wants below 0.1 expire, and beyond 40 active wants the weakest expire, each with the reason recorded.
+- **Suppression is not deletion.** When a want is not pursued because a commitment forbids it, policy denies its means or a conflict defers it, a `want_suppressed` event is written, its suppression count rises and it stays active.
+
+### Values as inputs
+
+Configured personality values have behavioural consequences beyond prompts:
+
+- *accuracy* and *evidence* strengthen wants to reduce uncertainty; *curiosity* strengthens curiosity wants; *persistence* strengthens goal and commitment wants; *kindness* strengthens answering and request wants;
+- *caution* scales the risk penalty in formation and creates an "avoid unnecessary disruption" want opposing writing actions;
+- *privacy* penalises capabilities whose output may contain personal data and creates an "avoid exposing personal data" want opposing them;
+- *autonomy* adds a small term for wants the mind generated itself.
+
+No model makes moral judgements here. The values are numbers an operator configured, and the weighting is Go code.
+
+## Conflicts between wants
+
+Conflicts are first-class rows in `want_conflicts`, recorded with a `want_conflict_detected` event and a `conflict_resolution` decision. Neither want is discarded.
+
+Each want scores `effective strength × (0.5 + 0.5 × urgency) + 0.2 × goal priority + 0.4 × commitment weight`. Value-derived avoid wants are standing, so urgency does not scale them. There is no fixed hierarchy: a commitment-backed want gains its normative weight, and a weak commitment does not automatically beat a much stronger want.
+
+| Kind | Rule |
+|---|---|
+| approach against a value-derived avoid want | The approach is **preferred** when it scores at least 1.5× the avoid want; **preferred with a constraint** (least disruptive, approved route) when it scores at least as much; otherwise **deferred**, staying active. |
+| two approach wants (for example a capacity displacement) | The higher score is preferred; the other stays active. |
+
+The rationale records both sides' terms and the rule applied, which is how the interface answers "what did Noema want, which wants conflicted, which won, and why".
+
+## Intentions
+
+### Formation
+
+An `intend` process proposes deciding about the strongest active wants that have not been decided since they were last reinforced. The candidate competes for the global workspace like any other thought, so attention gates what the mind decides to pursue. Ablating attention or the workspace therefore has a measurable effect on intentions.
+
+The handler runs deterministic formation (`volition.Form`) over plain inputs and stores a decision whatever the outcome.
+
+Formation score terms:
+
+| Term | Value |
+|---|---|
+| strength | 0.35 × effective strength |
+| urgency | 0.15 × urgency |
+| goal | 0.15 × goal priority |
+| commitment | 0.15 × the weight of the commitment the want serves |
+| expected utility | 0.1 × expected chance of success |
+| operator request | 0.1 when an operator asked |
+| autonomy | 0.05 × autonomy value for self-generated wants |
+| risk | −0.2 × risk level × (0.5 + caution) |
+| cost | −0.05 × estimated wall time in minutes (capped) |
+| privacy | −0.1 × privacy when the output may contain personal data |
+
+The threshold is 0.3.
+
+Outcomes, checked in this order:
+
+| Outcome | When |
+|---|---|
+| not formed: *duplicate* | an open intention already serves the want |
+| not formed: *deferred by conflict* | a value conflict deferred the want (suppressed) |
+| not formed: *capability unavailable* | the proposed capability is unknown or locked (suppressed) |
+| not formed: *capability denied* | policy denies it; denied authority is not requested (suppressed) |
+| not formed: *forbidden by commitment* | a live refrain commitment without exception matches the action (suppressed) |
+| formed: *request approval* | a refrain commitment "unless approved" matches, or a value conflict required the approved route |
+| not formed: *no possible plan* | an investigation has no usable read-only capability |
+| not formed: *below threshold* | the score is under 0.3 |
+| formed, displacing | at capacity (five open intentions), and this intention's priority exceeds the weakest by more than 0.1; the weaker is suspended and a priority conflict recorded |
+| not formed: *capacity* | at capacity with nothing weaker |
+| formed | otherwise |
+
+A formed intention links the wants it serves, its goal and commitment, and the live beliefs about its action's target (so a failed expectation counts against them). It is planned in the same transaction. Nothing acts until the plan executor picks it up after the transaction commits.
+
+The distinction that matters most is between wanting and intending. With a standing commitment that production changes need approval, "restart atlas-worker" leaves the restart want active, forms no intention to restart directly, and forms an intention to **request approval** to restart. The approval request carries the reason.
+
+### Status and the intention–action gap
+
+Statuses are `proposed`, `active`, `suspended`, `blocked`, `abandoned`, `fulfilled` and `superseded`. A blocked intention names what it is waiting for:
+
+| Blocked kind | Meaning |
+|---|---|
+| `approval_required` | a step waits for an operator's decision on an approval request |
+| `capability_unavailable` | a step waits for temporary authority the mind has requested |
+| `resource_unavailable` | a plan budget is exhausted |
+| `outcome_unverified` | an action may have run before an interruption and must not be repeated blindly |
+| `prerequisite_incomplete`, `external_dependency`, `waiting_period`, `commitment` | as named |
+
+While blocked, the executor forms a **subordinate intention** ("obtain approval to restart atlas-worker", "obtain temporary logs.query access to atlas-worker*"), linked to its parent. The subordinate is fulfilled when authority arrives and abandoned when it is refused. An operator therefore sees:
+
+```
+Intention:  ask for approval to run service.restart on atlas-worker.service
+Status:     blocked
+Reason:     service.restart requires operator approval (approval required by the requesting intention)
+Waiting on: obtain approval to run service.restart on atlas-worker   (active)
+```
+
+### Reconsideration
+
+Intentions do not become permanent because they were once chosen. `volition.Reconsider` maps a trigger to an outcome, the store records the transition as a new event and decision, and history is never rewritten.
+
+| Trigger | Outcome |
+|---|---|
+| plan completed and its strategy achieves the outcome | fulfil (source wants satisfied, served commitment fulfilled) |
+| plan completed by an escalation | abandon: finished without achieving the desired outcome |
+| goal completed / abandoned | fulfil (pursue, investigate) or abandon (actions) / abandon |
+| operator correction | abandon |
+| approval denied, step failed, expectation failed, assumption weakened | replan, or abandon once the replan limit (three) is reached |
+| approval expired | replan the first time; suspend if it expires again |
+| capability now denied or unknown | replan; now ASK: block on approval |
+| new commitment forbidding the action | abandon |
+| new commitment requiring approval | require approval (replan under the new constraint, reusing the strategy) |
+| resource budget exhausted | suspend |
+| desired state already holds | fulfil without acting |
+| authority granted | resume |
+| a higher-priority intention needs the capacity | suspend |
+
+Reconsideration happens in three places. The executor reacts to plan outcomes. An event-bus listener reacts to new commitments, weakened or retracted beliefs a plan assumes, and finished goals. Metacognition reacts to intentions that outlived their goal.
+
+## Commitments
+
+Commitments come from operators (API, commitments page) and from the responsibilities an operator creates. Each has:
+
+- **polarity**: `do` or `refrain`;
+- a **matcher** over capabilities (globs), targets (globs), access (read or write) and minimum risk;
+- **unless**: empty, or `approval` for refrain commitments;
+- **kind**, which sets normative weight: operator instruction and policy 1.0, promise 0.9, responsibility 0.85, value rule 0.8, relationship 0.75, scheduled 0.7, prior decision 0.6;
+- strength, priority, beneficiary, conditions, due and expiry times, revocability and evidence.
+
+Weight is `strength × (0.5 + 0.5 × priority) × kind factor`.
+
+Deterministic checks, run after each cycle and by metacognition:
+
+- **due**: within two hours of the deadline, once (`commitment_due`, and a want to fulfil it);
+- **broken**: more than fifteen minutes past the deadline without fulfilment (`commitment_broken`);
+- **expired**: past its expiry;
+- **conflicting**: a `do` and a `refrain` over overlapping actions, or opposite polarities on one subject (`commitment_conflict`, raised once a day per pair; both stay represented);
+- **impossible**: a `do` commitment that needs a capability policy denies or that does not exist, or whose deadline was already past when it was made (a metacognitive warning);
+- **superseded**: a new commitment with the same subject, kind and polarity supersedes the old one, which is kept.
+
+A mind may revoke its own revocable commitments. Non-revocable commitments can be revoked only by an operator. Operators can always revoke, because operator controls stay sovereign.
+
+**Commitments restrict and never grant.** A refrain-unless-approved commitment sets `RequireApproval` on the invocation, which turns an ALLOW into ASK. Scoped grants do not satisfy it, and nothing turns ASK or DENY into ALLOW.
+
+## Metacognition for volition
+
+The metacognition process adds checks that compete for attention like the belief checks:
+
+| Check | Condition |
+|---|---|
+| `want_suppressed_repeatedly` | an active want with effective strength ≥ 0.5 set aside three or more times |
+| `intention_unsupported` | an open top-level intention with no want, goal or commitment behind it |
+| `intention_conflicts_commitment` | a live refrain commitment without exception matches an open intention's action |
+| `commitment_impossible` | as above |
+| `intention_churn` | ten or more intention changes in an hour |
+| `repeated_execution_failure` | the same capability failed in plan steps three or more times in a day |
+| `cost_exceeds_value` | an open plan for an intention with priority under 0.4 needs three or more approvals or more invocations than its budget |
+| `intention_outlived_goal` | an intention open although its goal is completed or abandoned (the handler abandons it) |
+| `self_model_mismatch` | the self-model states a policy for a capability that differs from the effective one (the entry is corrected) |
+| `unsupported_explanation`, `action_claim_without_record` | a reply's reasons or action claims do not match records (docs/agency.md) |
+
+The invariant behind the last row: Noema must never claim "I did X because I wanted Y" unless recorded provenance supports that chain. Replies are scored against the chain, and a mismatch is a warning.
+
+## Events
+
+`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`. All are in the `volition` category.
+
+Every choice is also a row in the append-only `volition_decisions` ledger (formation, non-formation, conflict resolution, reconsideration) with its terms and inputs.
+
+## Where to inspect
+
+- Mind → Volition: wants, intentions, commitments, plans, the agency timeline and research.
+- An intention page shows sources, subordinate intentions, formation terms, every plan revision as a dependency graph, decisions and correlated events.
+- "Why did this happen?" pages ([agency.md](agency.md)).
+- API: `/api/v1/minds/{mind}/wants`, `/want-conflicts`, `/commitments`, `/intentions`, `/decisions`.
+- Ask the mind: "What do you want?", "What are your intentions?", "What have you committed to?"; the answers are rendered from these tables.
+
+## Limits
+
+- Want derivation recognises a fixed set of triggers and a few literal English request shapes. Anything else produces no proposed means, and the want waits for an operator or a model-proposed plan.
+- Formation weights are hand-set and uncalibrated. They are recorded so they can be studied and tuned, not because they are right.
+- Value conflicts cover disruption and personal-data exposure only.
@@ -142,13 +142,12 @@ type WaitSpec struct {

 // InternalSpec is a deterministic internal step.
 type InternalSpec struct {
-	Action string `json:"action"` // summarise_findings | record_procedure
+	Action string `json:"action"` // summarise_findings (procedural memory is recorded automatically when a plan completes)
 }

 // InternalActions is the closed vocabulary of internal steps.
 var InternalActions = map[string]string{
 	"summarise_findings": "collect the observations of the steps it depends on into one record for belief formation",
-	"record_procedure":   "record the steps that achieved the outcome as a procedural memory",
 }

 // StepSpec is one step of a draft.