Define headless decision lifecycle product and delivery plan

Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a10780-6d41-7952-9718-dfbc1f41236f
This commit is contained in:
tegwick 2026-10-04 17:33:43 +02:00
parent 5dd68eb8c1
commit 871f5e05e8
9 changed files with 381 additions and 7 deletions

14
GOAL.md
View file

@ -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.**

View file

@ -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
> binds their identity to it — and owns the evidence that the presentation
> actually happened.**
> **informed-decision provides the decision lifecycle service for agents and
> humans: research, retrieve, prepare, evaluate, register, publish, comment on,
> 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

View file

@ -1,7 +1,14 @@
# informed-decision
User interface for executive decisions, modelled as a sign-and-return book —
the German *Umlaufmappe* / *Zeichnungsbuch*, made cryptographic.
Decision lifecycle service for agents and humans: research, retrieve, prepare,
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

View file

@ -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

View file

@ -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 |

View file

@ -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

View file

@ -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.

View file

@ -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`

View file

@ -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.