diff --git a/GOAL.md b/GOAL.md index e3cbe40..4b22dca 100644 --- a/GOAL.md +++ b/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.** diff --git a/INTENT.md b/INTENT.md index 874b2b5..ec50449 100644 --- a/INTENT.md +++ b/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 -> 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 diff --git a/README.md b/README.md index b62be53..bb854bf 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/SCOPE.md b/SCOPE.md index 4096c38..3f3559c 100644 --- a/SCOPE.md +++ b/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 diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index a3f2824..a088345 100644 --- a/WORK-RECORDS.md +++ b/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 | diff --git a/docs/specs/ArchitectureBlueprint.md b/docs/specs/ArchitectureBlueprint.md index 07cb2cc..1181d7a 100644 --- a/docs/specs/ArchitectureBlueprint.md +++ b/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 diff --git a/docs/specs/DecisionLifecycleService.md b/docs/specs/DecisionLifecycleService.md new file mode 100644 index 0000000..68c8c1f --- /dev/null +++ b/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. diff --git a/docs/specs/ProductRequirementsDocument.md b/docs/specs/ProductRequirementsDocument.md index b3ce6f6..4b08b11 100644 --- a/docs/specs/ProductRequirementsDocument.md +++ b/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` diff --git a/workplans/INFD-WP-0007-decision-lifecycle-service.md b/workplans/INFD-WP-0007-decision-lifecycle-service.md new file mode 100644 index 0000000..602cb17 --- /dev/null +++ b/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.