From dcbdb02c77a1c288a6756efd0f3ad2b39004ee5d Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 4 Oct 2026 20:56:28 +0200 Subject: [PATCH] Record the kernel proposal for DECISION-WP-0003. A D1 decision is question, choice, and reason. Every other draft section stays an envelope, and the schema draft is unchanged. Assistant: grok Assistant-Session: 01a1082a-858c-7fe2-9b5a-0b5332107eb3 --- AGENTS.md | 2 +- SCOPE.md | 2 +- examples/README.md | 2 +- reviews/kernel-proposal.md | 101 ++++++++++++++++++ workplans/DECISION-WP-0003-kernel-proposal.md | 12 ++- 5 files changed, 114 insertions(+), 5 deletions(-) create mode 100644 reviews/kernel-proposal.md diff --git a/AGENTS.md b/AGENTS.md index 320da37..aa9f286 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -263,7 +263,7 @@ Read in this order before editing a concept: `INTENT.md`, `SCOPE.md`, `DecisionC Verification is editorial. After a change, re-read the edited document against `SCOPE.md` and the non-goals in `INTENT.md`. A simple decision must still be writable without the heavy fields. Policy and constitutional decisions stay decisions whose effects shape later decisions. -Do not add a normative schema, a runtime, or further examples inside an unrelated edit. Schema pressure from the six examples is `reviews/schema-pressure.md`. A kernel proposal is `DECISION-WP-0003`. Identifiers such as `DEC-EX-NNN` are example identity ids, not State Hub work-record ids. +Do not add a normative schema, a runtime, or further examples inside an unrelated edit. Schema pressure from the six examples is `reviews/schema-pressure.md`. The unadopted kernel proposal is `reviews/kernel-proposal.md`. Identifiers such as `DEC-EX-NNN` are example identity ids, not State Hub work-record ids. Workplan files are the source of task state. From this checkout, after changing them: diff --git a/SCOPE.md b/SCOPE.md index 790fcad..1bf74c3 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -25,7 +25,7 @@ A research canon for one decision object that can stay light for an informal cho ## Current state -Milestone M0, the concept seed, is in the repository. [DECISION-WP-0002](workplans/DECISION-WP-0002-schema-probe.md) added six illustrative examples under `examples/` and the pressure note `reviews/schema-pressure.md`. The schema draft is still unfrozen, and there is still no validation command and no normative schema. The next work is [DECISION-WP-0003](workplans/DECISION-WP-0003-kernel-proposal.md): propose the kernel boundary from that note. +Milestone M0, the concept seed, is in the repository. [DECISION-WP-0002](workplans/DECISION-WP-0002-schema-probe.md) added six illustrative examples and `reviews/schema-pressure.md`. [DECISION-WP-0003](workplans/DECISION-WP-0003-kernel-proposal.md) recorded a kernel proposal in `reviews/kernel-proposal.md`. The proposal is not adopted. `DecisionObjectSchemaDraft.md` is still the unfrozen draft, and there is still no validation command and no normative schema. ## Getting oriented diff --git a/examples/README.md b/examples/README.md index ace5a0e..6e1f5b3 100644 --- a/examples/README.md +++ b/examples/README.md @@ -21,4 +21,4 @@ The decision's identity id has the form `DEC-EX-NNN`. That id is an example iden | `DEC-EX-005` | Deployment policy | [DEC-EX-005-deploy-policy.md](DEC-EX-005-deploy-policy.md) | | `DEC-EX-006` | Constitutional governance rule | [DEC-EX-006-binding-policy-rule.md](DEC-EX-006-binding-policy-rule.md) | -Hiring, procurement, investment, budget allocation, and public-style policy are not in this set. They stay deferred in `DECISION-WP-0003` until a kernel proposal says whether more situations would show something these six did not. +Hiring, procurement, investment, budget allocation, and public-style policy are not in this set. `reviews/kernel-proposal.md` concludes they would not move the D1 minimum. They are not a further workplan. diff --git a/reviews/kernel-proposal.md b/reviews/kernel-proposal.md new file mode 100644 index 0000000..6bdc814 --- /dev/null +++ b/reviews/kernel-proposal.md @@ -0,0 +1,101 @@ +# Kernel proposal + +Proposal from `DECISION-WP-0003`. Evidence is [schema-pressure.md](schema-pressure.md) and the six examples under `examples/`. This note does not freeze the kernel. `DecisionObjectSchemaDraft.md` is unchanged. Nothing here is a schema edit. + +## D1 minimum + +`DEC-EX-001` is a valid decision object. A recorded decision must be able to carry these three fields and no others: + +```yaml +decision: + question: Which database should we use for the new service? + choice: PostgreSQL + reason: It is sufficient and already operationally familiar. +``` + +| Field | Role | +| --- | --- | +| `question` | What is being decided. A string is the question text. An object is allowed, and then `question.text` is that text. | +| `choice` | What was selected. Prose, as in `DEC-EX-001`, or an `alternatives[].id` when an `alternatives` envelope is present. | +| `reason` | Why, in the words available at decision time. This is the kernel home for what `UnifiedDecisionObject.md` calls `rationale`. | + +`identity`, `kind`, `state`, and `commitment` are not required for this object to count. Adding them is what made the draft unable to hold `DEC-EX-001`. + +A question with no `choice` is not yet a decision. The `choice` is the commitment. A separate `commitment` section is how a later envelope records who committed, when, and under what mode. `DEC-EX-003` needs that envelope. `DEC-EX-001` does not. + +## Envelopes + +Every other draft section is an optional envelope. Absence means the situation did not need it. It does not mean the field was considered and left blank. + +| Envelope | D1 | First example that needed it | +| --- | --- | --- | +| `identity` | no | `DEC-EX-002`. Also required on any decision that another decision points at. | +| `kind` | no | `DEC-EX-002` (`choice`). `DEC-EX-004` uses `exception`, `DEC-EX-005` uses `policy`, `DEC-EX-006` uses `constitutional`. | +| `state` | no | `DEC-EX-002` | +| `frame` | no | `DEC-EX-002` | +| `alternatives` | no | `DEC-EX-002`, including the do-nothing alternative. `DEC-EX-003` adds wait. | +| `values` | no | `DEC-EX-002`. Objectives, constraints, and vetoes stay separate fields. | +| `analysis` | no | `DEC-EX-002`, which needed two results. | +| `world_model` | no | Not required even for `DEC-EX-002`. Competing causal stories live in `analysis`. | +| `commitment` | no | `DEC-EX-002` and `DEC-EX-003`, for who, when, mode, and reservations. | +| `governance` | no | `governance.owner` in `DEC-EX-002`. `authority` in `DEC-EX-004`, `DEC-EX-005`, and `DEC-EX-006`. | +| `uncertainty` | no | `DEC-EX-003` | +| `execution` | no | `DEC-EX-003` | +| `outcome` | no | `DEC-EX-003` | +| `learning` | no | `DEC-EX-003` | +| `temporal` | no | `DEC-EX-003`, so decision time and observation time stay distinct. | +| `effects` | no | `DEC-EX-004`, `DEC-EX-005`, and `DEC-EX-006`. | +| `relationships` | no | `DEC-EX-004` (`exception-to`). | +| `metadata` | no | `DEC-EX-004` (`formality_level`). | +| `evidence` | no | None of the six. The envelope stays available. | +| `information_options` | no | None of the six. The envelope stays available. | +| `optionality` | no | None of the six. Reversibility of a candidate stays on that alternative. | + +`UnifiedDecisionObject.md` section 3 lists a larger conceptual kernel (`id`, `kind`, `state`, `context`, `owner`, `alternatives`, `commitment`, `created_at`). Those are envelopes in this proposal. The D1 minimum is the smaller set the probe could not remove. + +## Homes kept + +Where the pressure note found two homes for one fact, this proposal keeps one. + +| Fact | Kept home | Other home, not used for this fact | +| --- | --- | --- | +| Question text | A string `question`, or `question.text` when `question` is an object | A second copy elsewhere | +| Trigger | `frame.trigger` | `question.trigger` | +| What was selected | `choice` | `commitment.selected` must match `choice` when both are present. It is not a second choice. | +| Why | `reason` | `analysis.recommendation` may name the same alternative. It is not the reason. `learning.lessons` is later. | +| Reversibility of a candidate | `alternatives[].reversibility` | Top-level `optionality`, unless it says something about the chosen alternative that the candidate entry does not | +| Who committed, when, and how | `commitment.by`, `commitment.at`, `commitment.mode` | Putting those facts into `choice` or `reason` | +| When the decision is in force | `temporal.effective_from` and `temporal.effective_until` | `commitment.conditions` for a pure end time. `effects[].effective_when` and `effects[].expires_when` only when that one effect starts or ends at a different time from the decision. | +| Current lifecycle | `state.lifecycle`, one current value | A history inside `state`. Times that must survive live in `temporal`. | +| Decision-time assumptions | `frame.assumptions`, sealed once `choice` is recorded | Editing that list after the fact. A later correction goes in `learning`. | +| Competing causal stories | `analysis.analyses[]` | A second `world_model`. If `world_model` is present, it is the model the choice relied on. | +| Confidence | A word is enough (`high`, `medium`, `low`) on the envelope that owns it | A required number | +| Policy | The decision, with `kind: policy`, plus one `effects` entry of type `policy` that holds the rule | Repeating the rule in `commitment.selected` or `commitment.conditions` | +| What a policy governs | A later decision's `relationships` entry `governed-by`, pointing at the policy id | An inverse list on the policy. `effects[].target` names the class in words. | +| Exception | `kind: exception`, an effect of type `authorization`, and `exception-to` | A second kind `authorization` that only repeats the effect | +| Constitutional character | `kind: constitutional` | An effect type `constitutional`. Effects stay `requirement` or `constraint`. | +| How this rule may be changed | `relationships` type `supersedes` on the later decision | A nested object inside the earlier decision. The earlier decision may state the requirement in an effect. | +| Authority source | `governance.authority.source` | A parallel field. Use a decision id when one exists (`DEC-EX-004` points at `DEC-EX-005`). A sentence is allowed when there is no prior decision (`DEC-EX-006`). | +| `can` / `may` / `must` | Strings on `governance.authority` | Booleans. `DEC-EX-006` needs the sentence. A boolean capability can be written as a sentence. | +| Effect target | `effects[].target` | A second target field in this proposal. The writer says whether the value is an id or a class. A later schema may split the field. This note does not. | +| Executable rule text | Prose in `effects[].value` until a rule language is chosen | A copy in `commitment.conditions`, and a new kernel field | + +## Recommendations for a later schema revision + +Not applied in this workplan: + +1. Describe the D1 object (`question`, `choice`, `reason`) as valid, including a string `question`. +2. Add `choice` and `reason` to the draft's kernel story, and state the homes in the table above. +3. Say that `confidence` may be a word. +4. Say that `frame.assumptions` is not rewritten after `choice` is recorded, and that later facts go in `learning`. +5. Leave the executable rule language unspecified. `DEC-EX-005` does not justify a DMN or OPA field yet. + +Still open, and not answered by another example of the same six shapes: + +- The root of authority, when `authority.source` is a sentence rather than a decision id (`DEC-EX-006`). +- A structural bound on rules that change the rules for changing rules. This proposal keeps `kind`, effects, and `supersedes` on the successor. It does not add a depth counter. +- Which existing rule language to reuse, and where an executable body would sit. + +## Situations not in the six + +Hiring, procurement, investment, budget allocation, and public-style policy would not move this D1 minimum. Allocation, bet, and value-of-information would exercise envelopes the six left empty (`effects` type `allocation`, `kind: bet`, `information_options`). They are not a reason to write those examples before a schema revision adopts this cut. They are not a separate workplan. diff --git a/workplans/DECISION-WP-0003-kernel-proposal.md b/workplans/DECISION-WP-0003-kernel-proposal.md index 2d3ffd1..75644a2 100644 --- a/workplans/DECISION-WP-0003-kernel-proposal.md +++ b/workplans/DECISION-WP-0003-kernel-proposal.md @@ -4,7 +4,7 @@ type: workplan title: "Propose the Decision Object kernel from the schema probe" domain: infotech repo: decision-canon -status: proposed +status: finished flavor: planning depends_on: [] owner: codex @@ -35,9 +35,17 @@ Verification: `reviews/kernel-proposal.md` exists, cites the pressure note, and ```task id: DECISION-WP-0003-T01 -status: todo +status: done priority: high state_hub_task_id: "f9cb09e1-be50-5c80-bcbb-085d1283830f" ``` Write `reviews/kernel-proposal.md`. State which fields a trivial decision must be able to carry so that `DEC-EX-001` is a valid decision object, and which sections from `DEC-EX-002` through `DEC-EX-006` remain optional envelopes. Where the pressure note shows two homes for one fact, name the home the proposal keeps. Do not edit `DecisionObjectSchemaDraft.md`. Recommendations that would change the draft belong in the proposal note. + +Done. The proposal is `reviews/kernel-proposal.md`. The D1 minimum is `question`, `choice`, and `reason`. Every other draft section is an envelope. `DecisionObjectSchemaDraft.md` was not edited. + +## Evidence and handoff + +The proposal is recorded and not adopted. Applying it to the schema draft would freeze a cut this workplan does not freeze, so no successor workplan was opened. The remaining M1 situations are closed in the proposal as kernel-neutral. They are not a separate workplan. + +Definition of Done is unassessed. This repository has no automated test suite.