coulomb/decision-canon
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Record the kernel proposal for DECISION-WP-0003.

Browse source 
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
This commit is contained in:
tegwick 2026-10-04 20:56:28 +02:00
parent 6c7279efbe
commit dcbdb02c77
5 changed files with 114 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

2
AGENTS.md
View file

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

2
SCOPE.md
View file

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

2
examples/README.md
View file

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

101
reviews/kernel-proposal.md Normal file
View file

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

12
workplans/DECISION-WP-0003-kernel-proposal.md
View file

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