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

Finish the State Hub bootstrap for decision-canon.

Browse source 
Replace the generated scope, record the documentation workflow, and open DECISION-WP-0002 to probe the schema draft.

Assistant: grok
Assistant-Session: 01a1082a-858c-7fe2-9b5a-0b5332107eb3
This commit is contained in:
tegwick 2026-10-04 20:42:00 +02:00
parent ac58582bf8
commit 55141cc0e9
5 changed files with 129 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

16
AGENTS.md
View file

@ -254,3 +254,19 @@ To create a new workplan:
1. Write the file following the format above
2. Run `uv run --project ~/repo-manager rmgr sync --path . --push`.
3. Run `statehub fix-consistency` only when a separate deep audit is needed.
## Decision Canon workflow
This checkout is a Markdown research canon. It has no package, service, installer, build, or run command, and it has no test or lint suite.
Read in this order before editing a concept: `INTENT.md`, `SCOPE.md`, `DecisionCanon.md`, `UnifiedDecisionObject.md`, `DecisionObjectSchemaDraft.md`, `Glossary.md`, `ResearchProgram.md`.
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 an example set inside an unrelated edit. Schema pressure from examples is `DECISION-WP-0002`. Identifiers such as `DEC-...` inside canon prose are concept ids, not State Hub work-record ids.
Workplan files are the source of task state. From this checkout, after changing them:
```bash
statehub fix-consistency
```

9
README.md
View file

@ -1,6 +1,6 @@
# decision-canon
Othogonal vocabulary and canonical model for decision related concepts.# decision-canon
Orthogonal vocabulary and canonical model for decision-related concepts.
`decision-canon` is a research and design repository for a unified language, object model, and practical system architecture for representing decisions from lightweight informal choices through governed, executable, policy-shaping, and constitutional decisions.
@ -30,13 +30,16 @@ At higher levels, decisions may create policies that constrain later decisions,
decision-canon/
├── README.md
├── INTENT.md
├── SCOPE.md
├── AGENTS.md
├── DecisionCanon.md
├── UnifiedDecisionObject.md
├── DecisionObjectSchemaDraft.md
├── ResearchProgram.md
├── Glossary.md
└── history/
└── 2026-10-04-initial-exploration.md
├── history/
│ └── 2026-10-04-initial-exploration.md
└── workplans/
```
## Working principle

43
SCOPE.md
View file

@ -1,32 +1,37 @@
# SCOPE
> This file was generated by `statehub register`. Refine it as the repository
> boundaries become clearer.
Reviewed: 2026-10-04, against the seed documents at commit `ac58582`.
## One-liner
Research and design repository for a unified language, object model, and architecture for decisions, from informal choices through governed, executable, policy-shaping, and constitutional decisions.
A research canon for one decision object that can stay light for an informal choice and can carry authority, effects, and learning when the decision governs later decisions.
## Core Idea
## In scope
decision-canon exists to provide the capability described in INTENT.md.
- The shared language in `Glossary.md`.
- The lifecycle, decision kinds, and governance distinctions in `DecisionCanon.md`.
- The unified decision object in `UnifiedDecisionObject.md`.
- The loose structural draft in `DecisionObjectSchemaDraft.md`.
- The research program, hypotheses, and milestone order in `ResearchProgram.md`.
- Workplans under the prefix `DECISION-WP-`.
## In Scope
## Out of scope
- Maintain the repository's primary implementation.
- Keep docs, tests, and operational metadata current.
- A running decision service, approval UI, or policy engine. `informed-decision` owns the presentation and binding surface for decisions that already exist.
- InfoTechCanon shared roots, including identity, evidence, and generic governance vocabulary. Later mappings import them.
- Security authority vocabulary. That canon is `security-canon`.
- A normative JSON Schema, a conformance suite, or a frozen kernel. `DecisionObjectSchemaDraft.md` keeps field names unfrozen. Kernel freeze is research milestone M2, after comparative examples.
- Replacing existing decision-analysis methods, requiring quantitative analysis of every decision, forcing one workflow, or collapsing values, evidence, uncertainty, and authority into one score. Those limits are in `INTENT.md`.
## Out of Scope
## Current state
- Own unrelated adjacent systems.
- Make irreversible operational decisions without human approval.
Milestone M0, the concept seed, is in the repository: intent, canon, decision object, schema draft, glossary, and the 2026-10-04 exploration history. There is no `examples/` directory, no `schemas/` directory, and no validation command. The next work is [DECISION-WP-0002](workplans/DECISION-WP-0002-schema-probe.md): six diverse examples and a note on where the draft schema is awkward.
## Current State
## Getting oriented
- Status: active; implementation and stability should be verified by the repo agent.
## Getting Oriented
- Start with: INTENT.md
- Agent instructions: AGENTS.md
- Workplans: workplans/
1. `INTENT.md`
2. `DecisionCanon.md`
3. `UnifiedDecisionObject.md`
4. `DecisionObjectSchemaDraft.md`
5. `ResearchProgram.md`
6. `workplans/`

18
workplans/DECISION-WP-0001-statehub-bootstrap.md
View file

@ -4,7 +4,7 @@ type: workplan
title: "Bootstrap State Hub integration"
domain: infotech
repo: decision-canon
status: ready
status: finished
owner: codex
topic_slug: canon
created: "2026-10-04"
@ -20,7 +20,7 @@ Research and design repository for a unified language, object model, and archite
```task
id: DECISION-WP-0001-T01
status: todo
status: done
priority: high
state_hub_task_id: "8f334a2a-dc2a-57e9-9e16-f17bc9fa157f"
```
@ -28,11 +28,13 @@ state_hub_task_id: "8f334a2a-dc2a-57e9-9e16-f17bc9fa157f"
Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
Replace generated placeholders with repo-specific facts where needed.
Done. `INTENT.md` is the authored intent and was kept. `SCOPE.md` now states the seed boundary, the neighbouring canons, and milestone M0. `AGENTS.md` had no remaining template tokens. `.custodian-brief.md` is generated by `fix-consistency` and was not edited by hand. The README heading was split where two titles had been joined, and its file tree now includes the governance files.
## Verify Local Developer Workflow
```task
id: DECISION-WP-0001-T02
status: todo
status: done
priority: high
state_hub_task_id: "40779ae9-4ce7-5f50-9f87-805b5332f01a"
```
@ -41,11 +43,13 @@ Identify the repo's install, test, lint, build, and run commands. Add or refine
those commands in the agent instructions so future coding sessions can verify
changes confidently.
Done. There is no install, test, lint, build, or run command. `AGENTS.md` records that verification is an editorial re-read against `SCOPE.md` and the non-goals in `INTENT.md`, and that workplan changes are synced with `statehub fix-consistency`.
## Seed First Real Workplan
```task
id: DECISION-WP-0001-T03
status: todo
status: done
priority: medium
state_hub_task_id: "b1e64084-ffed-5079-ae05-2e0984a9d13a"
```
@ -57,3 +61,9 @@ checkout:
```bash
statehub fix-consistency
```
Done. The next main work is [DECISION-WP-0002](DECISION-WP-0002-schema-probe.md). It is a planning workplan, not a residual: ResearchProgram milestone M1 is the program's next evidence step. No separate residual intake was opened.
## Evidence and handoff
`DECISION-WP-0001` is finished. The successor is [DECISION-WP-0002](DECISION-WP-0002-schema-probe.md). Definition of Done is unassessed: this repository has no automated test suite, so the test item in the workplan DoD does not pass.

69
workplans/DECISION-WP-0002-schema-probe.md Normal file
View file

@ -0,0 +1,69 @@
---
id: DECISION-WP-0002
type: workplan
title: "Probe the schema draft with a diverse decision set"
domain: infotech
repo: decision-canon
status: ready
flavor: planning
depends_on: []
owner: codex
topic_slug: canon
lane: green
created: "2026-10-04"
updated: "2026-10-04"
reviewed_at: "2026-10-04"
reviewed_against_commit: "ac58582"
quality_dor: DoR-Ok
quality_dor_at: "2026-10-04"
quality_dor_by: "grok"
quality_dor_note: "Bounded documentation probe. Verification is the review note. No production lane."
---
# Probe the schema draft with a diverse decision set
Opened from `DECISION-WP-0001-T03`.
Milestone M0 is already in the tree. `ResearchProgram.md` collects comparative examples (M1) before any kernel freeze (M2). This workplan starts that probe with six situations and a written account of where `DecisionObjectSchemaDraft.md` is awkward. It does not freeze field names, publish a JSON Schema, or write the rest of the 25-decision corpus.
## Scope
In scope: an example convention, six Markdown examples, and one review note.
Out of scope: a normative schema, application code, mappings to DMN or policy engines, kernel freeze, and the remaining M1 situations (hiring, procurement, investment, budget allocation, and public-style policy). Those wait on what the six examples show.
Dependencies: none. The seed documents reviewed at `ac58582` are sufficient.
Lane: `green`. Documentation in this repository only. No production change and no credential use.
Verification: each example file exists and uses only the schema-draft sections the situation needs. `reviews/schema-pressure.md` names, for every example, the sections that were necessary, the sections that were awkward, and any question from ResearchProgram section 7 that the example raises. No automated test applies. The repository has no test command.
## Define the example convention
```task
id: DECISION-WP-0002-T01
status: todo
priority: high
```
Add `examples/README.md` stating the file shape: one Markdown decision per file, an identity id of the form `DEC-EX-NNN`, and only the schema-draft sections the situation needs. Name the six situations this workplan covers, taken from ResearchProgram M1: a trivial engineering choice, an architecture decision, an incident-response decision, a security exception, a deployment policy, and a constitutional governance rule. Do not add a JSON Schema.
## Write the six examples
```task
id: DECISION-WP-0002-T02
status: todo
priority: high
```
Write one example file for each situation named in T01. Keep the trivial choice to the question, the choice, and the reason. Let the constitutional example carry governance and effects on later decisions. Leave unknown fields absent.
## Record schema pressure
```task
id: DECISION-WP-0002-T03
status: todo
priority: medium
```
Write `reviews/schema-pressure.md`. For each example, record which schema sections were necessary, which were awkward, and which questions from ResearchProgram section 7 the example raises. Stop when that note exists. Leave the schema draft unchanged unless an example cannot be written without one named clarification, and record that clarification in the note.