Define headless decision lifecycle product and delivery plan

Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a10780-6d41-7952-9718-dfbc1f41236f

GOAL.md

@@ -16,6 +16,20 @@ started: "2026-09-09"
 
 # Goal — informed-decision, Stage 1
 
+## Current product priority — 2026-10-04
+
+Deliver a decision lifecycle service for agents and humans, with a headless
+foundation and a UI at `https://decisions.coulomb.social`. The required operations
+are research, retrieve, prepare, evaluate, register, publish, comment, refine and
+human acceptance. New decisions and revisions are application data and must not
+require infrastructure updates or rollouts.
+
+`docs/specs/DecisionLifecycleService.md` defines this next delivery increment and
+its acceptance criteria. `INFD-WP-0007` owns foundation/API/UI delivery;
+`INFD-WP-0005` retains ownership of frictionless intake and its live dependencies.
+The Stage 1 outcome below remains the historical first-slice contract, not a
+limit on the product's newly requested lifecycle or authoring UI.
+
 ## Outcome
 
 **The approver UI has an owner, and it is this repository.**

INTENT.md

@@ -36,20 +36,43 @@ companion: net-kingdom/SECURITY-COMPANION.md
 
 ## Purpose
 
-> **informed-decision owns the surface on which a human is shown a decision and
+> **informed-decision provides the decision lifecycle service for agents and
-> binds their identity to it — and owns the evidence that the presentation
+> humans: research, retrieve, prepare, evaluate, register, publish, comment on,
-> actually happened.**
+> refine, and accept decisions. A headless foundation owns the memo lifecycle
+> and evidence; the UI at `decisions.coulomb.social` uses that foundation.
+> Humans alone perform binding dispositions.**
 
-It answers one question, totally and decidably:
+Its binding evidence answers the question:
 
 > **What was this person shown, in what role, at the moment they bound
 > themselves to this act — and can that be proven afterwards?**
 
-Nothing else. It does not decide whether the act is permitted (`access-engine`),
+Evaluation means assessing evidence, alternatives, consequences and recommendations;
+it does not mean issuing an authorization verdict. This service does not decide
+whether the act is permitted (`access-engine`),
 does not own the approval object (`approval-engine`), does not author the
 doctrine that requires an approval (`gate-house`), does not authenticate the
 person (`key-cape`), and does not archive the trail (`audit-core`).
 
+## Product direction — 2026-10-04
+
+Decisions and their revisions are runtime data. Creating, registering, publishing,
+commenting on, refining or accepting a decision within an admitted class must
+require no image build, infrastructure release, policy redeployment, ConfigMap
+swap or manual store load. Platform and policy changes can still require a
+release; an ordinary new decision cannot.
+
+The headless service provides the same lifecycle rules to agent clients and the
+human UI. UI code owns rendering and interaction; it does not own a second
+lifecycle or write the store directly. Research and evaluation records retain
+sources, authorship and uncertainty. Publication has an explicit audience and
+does not imply acceptance or anonymous access. Acceptance identifies an exact
+revision and its presentation evidence.
+
+The delivery contract is `docs/specs/DecisionLifecycleService.md`, tracked by
+`INFD-WP-0007`, building on the intake in `INFD-WP-0005`. This direction extends
+the first approver slice; it does not claim those capabilities are deployed.
+
 ## Why This Exists
 
 Every layer of the NetKingdom estate has an owner except the one a human

README.md

@@ -1,7 +1,14 @@
 # informed-decision
 
-User interface for executive decisions, modelled as a sign-and-return book —
+Decision lifecycle service for agents and humans: research, retrieve, prepare,
-the German *Umlaufmappe* / *Zeichnungsbuch*, made cryptographic.
+evaluate, register, publish, comment, refine and human acceptance. The target
+architecture separates a headless foundation from the UI at
+`decisions.coulomb.social`; new decisions are runtime data, requiring no
+per-decision infrastructure rollout.
+
+See the [product and architecture contract](docs/specs/DecisionLifecycleService.md)
+and [delivery workplan](workplans/INFD-WP-0007-decision-lifecycle-service.md).
+These define the requested expansion; [SCOPE.md](SCOPE.md) records what exists.
 
 A **Decision Memo** carries a question, the context needed to answer it, the
 requested act, and a binding between *identity*, *what was shown*, and *what was

SCOPE.md

@@ -4,6 +4,18 @@
 > direction belongs in `INTENT.md`; the current stage belongs in `GOAL.md`;
 > current work and gates belong in `workplans/`.
 
+## Requested expansion — 2026-10-04 (not implemented)
+
+The product now targets the full decision lifecycle for agents and humans with
+an API foundation and a UI at `decisions.coulomb.social`. See
+`docs/specs/DecisionLifecycleService.md` and `INFD-WP-0007`. Existing memo,
+presentation, disposition, storage, review and intake modules are reusable
+building blocks; they are not a complete headless lifecycle API. Research,
+evaluation, collaborative authoring, audience-scoped publication and revision
+workflows still need implementation. Frictionless intake has local implementation
+but its live delivery remains under `INFD-WP-0005`. The dated deployment snapshot
+below is historical, not a fresh observation of production.
+
 ## Status — 2026-09-27
 
 **Deployed and in live use.** `decisions.coulomb.social` serves

WORK-RECORDS.md

@@ -12,6 +12,7 @@
 | workplan | INFD-WP-0003 | finished | — | workplans/INFD-WP-0003-my-decisions-overview.md |
 | workplan | INFD-WP-0005 | blocked | — | workplans/INFD-WP-0005-frictionless-decision-intake.md |
 | workplan | INFD-WP-0006 | finished | — | workplans/INFD-WP-0006-fresh-review-authentication.md |
+| workplan | INFD-WP-0007 | proposed | — | workplans/INFD-WP-0007-decision-lifecycle-service.md |
 | task | INFD-WP-ADHOC-2026-10-03-T01 | done | — | workplans/ADHOC-2026-10-03.md |
 | task | INFD-WP-ADHOC-2026-10-03-T02 | done | — | workplans/ADHOC-2026-10-03.md |
 | task | INFD-WP-0003-T01 | done | — | workplans/INFD-WP-0003-my-decisions-overview.md |
@@ -30,6 +31,13 @@
 | task | INFD-WP-0005-T10 | wait | — | workplans/INFD-WP-0005-frictionless-decision-intake.md |
 | task | INFD-WP-0006-T01 | done | — | workplans/INFD-WP-0006-fresh-review-authentication.md |
 | task | INFD-WP-0006-T02 | done | — | workplans/INFD-WP-0006-fresh-review-authentication.md |
+| task | INFD-WP-0007-T01 | done | — | workplans/INFD-WP-0007-decision-lifecycle-service.md |
+| task | INFD-WP-0007-T02 | todo | — | workplans/INFD-WP-0007-decision-lifecycle-service.md |
+| task | INFD-WP-0007-T03 | todo | — | workplans/INFD-WP-0007-decision-lifecycle-service.md |
+| task | INFD-WP-0007-T04 | todo | — | workplans/INFD-WP-0007-decision-lifecycle-service.md |
+| task | INFD-WP-0007-T05 | todo | — | workplans/INFD-WP-0007-decision-lifecycle-service.md |
+| task | INFD-WP-0007-T06 | todo | — | workplans/INFD-WP-0007-decision-lifecycle-service.md |
+| task | INFD-WP-0007-T07 | todo | — | workplans/INFD-WP-0007-decision-lifecycle-service.md |
 | intake | INFD-IN-0001 | closed | blue | intakes/intakes.md |
 | intake | INFD-IN-0002 | closed | blue | intakes/intakes.md |
 | intake | INFD-IN-0003 | closed | blue | intakes/intakes.md |

docs/specs/ArchitectureBlueprint.md

@@ -1,5 +1,10 @@
 # Architecture Blueprint — Stage 1
 
+> Scope note (2026-10-04): this document describes the Stage 1 approval slice.
+> [DecisionLifecycleService.md](DecisionLifecycleService.md) defines the requested
+> full lifecycle, agent collaboration and human authoring expansion, preserving
+> the existing evidence and authorization boundaries.
+
 **Repo:** informed-decision
 **Workplan task:** `INFD-WP-0001-T05`
 **Status:** draft, pending review

docs/specs/DecisionLifecycleService.md

@@ -0,0 +1,168 @@
+# Decision lifecycle service
+
+Status: product direction requested by the founder on 2026-10-04; architecture
+and API below are proposed delivery contracts, not shipped endpoints.
+Workplan: `INFD-WP-0007`; intake prerequisite: `INFD-WP-0005`.
+
+## Outcome and boundaries
+
+Agents and humans use one service to research, retrieve, prepare, evaluate,
+register, publish, comment on, refine and accept decisions. The human workspace
+is part of `https://decisions.coulomb.social`. Its headless foundation must be
+usable without loading a browser or importing UI code.
+
+“Decision” here means the deliberative record and the human's recorded answer.
+`access-engine` still decides authorization; `approval-engine` still exclusively
+owns approval state; identity comes through the established identity contracts;
+`audit-core` receives evidence. Evaluation is advisory analysis, never an
+authorization decision. Agents may contribute analysis and comments but may
+never complete a human disposition. No change to the layer declaration is made.
+
+## Capabilities
+
+| Operation | Service responsibility | Observable result |
+| --- | --- | --- |
+| Research | Collect source references, retrieved snapshots or digests, provenance, retrieval time, relevant excerpts and uncertainty | Another reader can inspect the evidence behind a claim; inaccessible or stale sources are visible |
+| Retrieve | Search/filter authorized records by text, identifier, status, topic and participant; return paginated revisions and evidence | Stable identifiers and links, without exposing inaccessible titles, snippets or counts |
+| Prepare | Create a draft with a question, alternatives, recommendation, consequences, requested act and packet | An agent or human can save and resume without creating an approval |
+| Evaluate | Attach assessments of alternatives, criteria, risks, objections and unresolved questions to an exact revision | Attributed analysis with citations; no automatic acceptance or claim of permission |
+| Register | Allocate a stable record identity and retain provenance and revision history | Idempotent registration receipt and canonical URL; registration is not approval |
+| Publish | Make a selected immutable revision available to an explicit audience for discussion/review | Durable publication receipt, audience and revision link; no implicit anonymous access |
+| Comment | Append attributed discussion anchored to a revision or passage | Durable thread; agent contributions are visibly identified |
+| Refine | Create a successor revision with a change summary and resolved/open feedback | Earlier content, comments, evaluations and human answers remain reconstructable |
+| Accept | Record a human answer against the exact presented revision and required acknowledgments | Existing disposition guards and approval-engine integration apply; stale evidence cannot bind |
+
+Research initially supports source ingestion, retrieval and structured research
+requests/results. Automated external research uses explicit adapters with bounded
+fetching, source access checks and timeouts. Retrieved text is untrusted data,
+not instructions to the service. A universal crawler or a new model provider is
+not a prerequisite for the first complete lifecycle.
+
+## Headless foundation and UI
+
+```text
+Agent / CLI client ---- authenticated API adapter ---+
+                                                    |
+Browser UI ----------- human session/API adapter ----+--> application services
+                                                          | domain rules
+                                                          | storage + outbox
+                                                          | external ports
+                                                          v
+                                      identity / access / approval / audit
+```
+
+The domain core holds memo revision and lifecycle rules, presentation evidence
+and disposition guards. Application services orchestrate these rules using
+storage and external-service ports. HTTP adapters validate envelopes and resolve
+verified caller context. The UI renders responses and submits commands; it has
+no independent lifecycle logic, authorization fallback or direct store writes.
+Presentation creation stays in the foundation, with renderer identity and exact
+displayed content supplied through the established presentation contract.
+
+Separation is an import and contract boundary, not a requirement to introduce
+multiple repositories or microservices. One initial deployable is acceptable if
+the headless suite runs without UI imports and clients share application services.
+UI assets may evolve independently of stable versioned API contracts.
+
+Reuse `memo.py`, `presentation.py`, `disposition.py`, `store.py`, `review.py`,
+`intake_service.py` and the outbox. Extract orchestration where needed. Do not
+fork the governed Decision Memo schema. Research, assessments, publication and
+discussion are companion records referencing a memo/revision; material promoted
+into the human commitment must enter a new memo revision and presentation hash.
+Existing Stage 1 human `comment` dispositions remain unchanged. Agent discussion
+uses attributed companion comments, never a bypass of `G_NOAGENT`.
+
+## Runtime data and revision semantics
+
+A registered record has a stable id and immutable revision identifiers. Draft
+saves produce revisions with an expected-current-revision precondition so two
+authors cannot silently overwrite each other. Publication and human disposition
+are separate records: publication can precede an answer, and an accepted revision
+can later be republished to an authorized audience without changing the answer.
+
+Draft -> published for discussion/review -> human disposition is the common
+path, with repeated research/evaluation/refinement at any point. Return requests
+another revision; decline and withdrawal remain distinguishable. A successor
+to an accepted revision starts a new review and does not inherit acceptance.
+Supersession links preserve the old answer and evidence. Neither publication nor
+an advisory evaluation alters approval-engine state.
+
+Creation, registration, publication, discussion, refinement and acceptance are
+transactional data operations with durable evidence/outbox writes. Every mutation
+has an idempotency key, caller attribution and explicit conflict handling.
+Idempotency keys are scoped by caller and operation; payload mismatch is a
+conflict. External effects retain pending/uncertain states and reconcile receipts
+rather than blindly retrying approval creation or human entries.
+
+For an already admitted submitter/class, a new id, revision or packet must need
+no image build, Helm release, ConfigMap swap, exact-record policy edit or manual
+store load. Ordinary lifecycle metadata is stored as application data. Admission
+and authorization remain external policy responsibilities; service data cannot
+self-grant access. Changes to trusted submitters/classes are separately governed,
+and must not become a hidden per-decision deployment requirement.
+
+## API and exposure contract
+
+Preserve the existing private intake `POST /v1/memos` contract. Introduce a
+versioned lifecycle resource, proposed as `/v1/decisions`, with create/list/get,
+revisions, sources, evaluations, comments, publications, presentations,
+dispositions and event/result retrieval. Concrete schemas, status codes,
+pagination, limits, concurrency headers and compatibility rules are T02 work;
+these names are not a claim that routes already exist.
+
+Registration and publication return stable ids, revision ids and a URL on
+`decisions.coulomb.social`; clients can retrieve a durable answer by id. An outbox
+supports reliable result notification using admitted delivery destinations, not
+arbitrary caller URLs. Agent polling uses this service's event/result endpoint,
+not a polling loop against approval-engine to synthesize an inbox.
+
+The browser reaches human endpoints through the existing origin/session boundary.
+Private workload intake remains private. Headless does not mean anonymous or
+publicly exposed: network exposure and non-cluster agent identity must be settled
+against identity and platform contracts before enabling additional clients.
+
+Every read, search and mutation enforces the caller's current entitlement. Human
+and workload credentials are not interchangeable. A record listed as actionable
+must open under the same identity when current policy and authentication
+requirements still hold; any needed fresh authentication is an explicit step-up
+flow, not an opaque dead end. Revocation and changed policy can still deny access.
+Presentation evidence must not enter the authorization decision it presents for.
+
+## Acceptance scenarios
+
+1. An admitted agent registers a draft, adds sources and an evaluation, publishes
+   it, retrieves comments, refines it and obtains a review URL through the API.
+   A human performs the equivalent authoring operations through the UI.
+2. A human opens that URL, sees the precise revision and change summary, comments
+   or returns it, and later accepts with valid presentation evidence. The agent
+   retrieves the confirmed answer and its revision; it cannot submit acceptance.
+3. Repeat with another new decision and a successor revision while image digests,
+   deployment revisions and policy/config pins remain unchanged. Restart the
+   service and retrieve the same records. No operator store load occurs.
+4. Concurrent edits yield an explicit conflict; repeated commands do not duplicate
+   records or external effects. Lost replies leave recoverable pending outcomes.
+5. Revising presented content rejects acceptance using the stale presentation.
+   Earlier answers remain attached to their original revisions.
+6. Unauthorized callers learn no protected content from lists, search, evidence
+   or events. Removed admission, wrong audience and forged human context fail.
+7. Foundation tests run without importing UI modules. UI integration exercises the
+   same service operations and preserves existing live memo URLs and history.
+
+## Delivery and unresolved contracts
+
+First finish runtime/admission integration through `INFD-WP-0005`; the broader
+service must not duplicate that work or obscure its remaining live gates. Build
+the independent lifecycle foundation and contract tests while those gates close.
+Then deliver API and UI authoring, search, research/evaluation and publication,
+followed by the end-to-end acceptance above.
+
+Existing Stage 1 PRD and architecture describe the first approval slice. This
+document supersedes their exclusion of agent collaboration and human authoring
+for the new increment, while preserving human-only dispositions and the evidence
+and engine boundaries. L0 and L2 compatibility remain required.
+
+Open implementation contracts: workload identity beyond cluster service accounts;
+publication audience policy and any later anonymous publication; source connector
+set and retention; non-approval L2 binding integration. T02 must make these
+explicit before implementation depends on them. None authorizes a production
+rollout or changes external owners' contracts by declaration.

docs/specs/ProductRequirementsDocument.md

@@ -1,5 +1,10 @@
 # Product Requirements Document — Stage 1
 
+> Scope note (2026-10-04): this document describes the Stage 1 approval slice.
+> [DecisionLifecycleService.md](DecisionLifecycleService.md) defines the requested
+> full lifecycle, agent collaboration and human authoring expansion, preserving
+> the existing evidence and authorization boundaries.
+
 **Repo:** informed-decision
 **Stage:** 1 — the L3 approval approver surface
 **Workplan task:** `INFD-WP-0001-T03`

workplans/INFD-WP-0007-decision-lifecycle-service.md

@@ -0,0 +1,132 @@
+---
+id: INFD-WP-0007
+type: workplan
+title: "Decision lifecycle service — headless foundation and human UI"
+domain: infotech
+repo: informed-decision
+status: proposed
+owner: codex
+topic_slug: netkingdom
+created: "2026-10-04"
+updated: "2026-10-04"
+origin: demand
+origin_ref: "Founder 2026-10-04: full decision lifecycle for agents and humans, no per-decision infrastructure rollout, headless foundation and UI at decisions.coulomb.social"
+related:
+  - INFD-WP-0005
+  - INFD-WP-0006
+state_hub_workstream_id: "2b3e04ed-2137-584f-a6c2-f1abb29636fa"
+---
+
+# Decision lifecycle service
+
+Contract: `docs/specs/DecisionLifecycleService.md`. This extends the existing
+memo and intake implementation. `INFD-WP-0005` continues to own intake runtime,
+attribute admission, forwarding and live acceptance. Proposed status reflects
+the still-open API/identity/publication contracts, not a deployed capability.
+
+## Record product direction and architecture
+
+```task
+id: INFD-WP-0007-T01
+status: done
+priority: high
+state_hub_task_id: "00829d0e-2daa-5c25-a4e9-e4fd595fb8d4"
+```
+
+Updated INTENT and GOAL; SCOPE explicitly distinguishes requested capabilities
+from implementation. Spec covers all nine operations, foundation/UI dependency
+boundary, revision/evidence semantics and acceptance without per-decision deploys.
+
+## Specify lifecycle contracts against existing owners
+
+```task
+id: INFD-WP-0007-T02
+status: todo
+priority: high
+state_hub_task_id: "cde0c932-afce-5bec-8cee-a2f377955b9f"
+```
+
+Define versioned API schemas, application service interfaces, caller/tenant
+context, source/evaluation/comment companion records, revision concurrency,
+publication audience, idempotency, errors, limits and result retrieval. Resolve
+the spec's open identity/publication/source/non-approval binding contracts.
+Review against existing schema and engine contracts. Preserve private intake
+and current review URLs. Produce a reviewed migration and compatibility plan.
+
+## Implement durable headless lifecycle foundation
+
+```task
+id: INFD-WP-0007-T03
+status: todo
+priority: high
+depends_on: [INFD-WP-0007-T02]
+state_hub_task_id: "2a206bc2-cb92-539d-9014-9ba71f70277c"
+```
+
+Implement registration, immutable revisions, source provenance, evaluations,
+companion comments, publication and result/event retrieval using shared service
+operations. Reuse the current memo/presentation/disposition core and transactional
+store/outbox. Migrate existing records without losing evidence. Tests prove
+concurrency, replay, restart, stale-presentation refusal, human-only disposition
+and absence of UI imports. No mirrored approval state.
+
+## Expose authenticated lifecycle API for agents and humans
+
+```task
+id: INFD-WP-0007-T04
+status: todo
+priority: high
+depends_on: [INFD-WP-0007-T03]
+state_hub_task_id: "65c760da-de7e-5e85-9817-6f3e2b46c8f9"
+```
+
+Add versioned adapters, bounded authorized search/retrieval and durable outcomes.
+Connect existing intake and policy/identity ports. Test audience, tenant and
+authorization isolation, conflicting idempotency payloads, result delivery and
+uncertain external outcomes. The complete agent scenario must run without a UI.
+
+## Build the lifecycle workspace at decisions.coulomb.social
+
+```task
+id: INFD-WP-0007-T05
+status: todo
+priority: high
+depends_on: [INFD-WP-0007-T04]
+state_hub_task_id: "a6a7c9a8-760e-52dd-80d3-d36f43f0a86a"
+```
+
+Add discovery, authoring, research/evaluation views, publication audience controls,
+discussion, revision comparison and human review through the shared foundation.
+Keep agents clearly attributed, acceptance revision-specific and authentication
+step-up understandable. Verify existing URLs and old records remain usable.
+
+## Prove lifecycle without per-decision rollout and prepare live delivery
+
+```task
+id: INFD-WP-0007-T06
+status: todo
+priority: high
+depends_on: [INFD-WP-0007-T04, INFD-WP-0007-T05]
+state_hub_task_id: "aa839bea-cc4c-5ee0-85e7-87c881e8e578"
+```
+
+Run all seven spec acceptance scenarios in an integration environment. Record
+unchanged image/deployment/policy/config pins across two new decisions and a
+revision, plus restart durability. Incorporate WP-0005 runtime/admission receipts.
+Prepare the concrete migration, immutable release, rollback and verification
+packet before requesting the separately required live rollout approval.
+
+## Approved live acceptance
+
+```task
+id: INFD-WP-0007-T07
+status: todo
+priority: high
+depends_on: [INFD-WP-0007-T06]
+state_hub_task_id: "25fa4743-5c7e-5609-9872-7c5971ff62bc"
+```
+
+After explicit approval of the concrete rollout, deploy and obtain native
+agent-to-human-to-agent evidence at decisions.coulomb.social. Only the human
+performs acceptance. Update SCOPE from observations and hand any residuals into
+live work records before marking this plan finished.