diff --git a/AGENTS.md b/AGENTS.md index 6bb7ed6..dc82aff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 +``` diff --git a/README.md b/README.md index ee9c622..729be19 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/SCOPE.md b/SCOPE.md index c9d47ef..5eb1134 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -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/` diff --git a/workplans/DECISION-WP-0001-statehub-bootstrap.md b/workplans/DECISION-WP-0001-statehub-bootstrap.md index dcc396e..c94f34d 100644 --- a/workplans/DECISION-WP-0001-statehub-bootstrap.md +++ b/workplans/DECISION-WP-0001-statehub-bootstrap.md @@ -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. diff --git a/workplans/DECISION-WP-0002-schema-probe.md b/workplans/DECISION-WP-0002-schema-probe.md new file mode 100644 index 0000000..d9e1732 --- /dev/null +++ b/workplans/DECISION-WP-0002-schema-probe.md @@ -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.