From 46b588acc4017aa7c0bb5e2cd10ba46b0949dcd6 Mon Sep 17 00:00:00 2001
From: John Vandenberg <jayvdb@gmail.com>
Date: Wed, 29 Apr 2026 05:57:29 +0800
Subject: [PATCH] Fix db U011, add notes doc type

---
 .dg/org.kdl                                   |  20 ++
 .dg/schema.kdl                                | 322 ++++++++++++++++++
 .editorconfig                                 |   3 +
 .gitignore                                    |   1 +
 .mise.toml                                    |   4 +-
 README.md                                     |   4 +
 dg.toml                                       |  51 ---
 docs/architecture/adr-001-decisions.md        |   2 -
 .../adr-003-cluster-generation.md             |   3 +-
 9 files changed, 354 insertions(+), 56 deletions(-)
 create mode 100644 .dg/schema.kdl
 delete mode 100644 dg.toml

diff --git a/.dg/org.kdl b/.dg/org.kdl
index 7c69714..32c2181 100644
--- a/.dg/org.kdl
+++ b/.dg/org.kdl
@@ -1,3 +1,23 @@
 org "edge-toolkit" {
     name "edge-toolkit"
 }
+
+user "jayvdb" {
+    name "John Vandenberg"
+    title "Research Associate"
+    email "jayvdb@gmail.com"
+    org "edge-toolkit"
+}
+
+user "pierre-tenedero" {
+    name "Pierre Tenedero"
+    title "Research Associate"
+    email "pierre.tenedero@gmail.com"
+    org "edge-toolkit"
+}
+
+user "jamesbychance" {
+    name "James Eggleston"
+    title "Research Fellow"
+    org "edge-toolkit"
+}
diff --git a/.dg/schema.kdl b/.dg/schema.kdl
new file mode 100644
index 0000000..4cd912c
--- /dev/null
+++ b/.dg/schema.kdl
@@ -0,0 +1,322 @@
+// DecisionGraph schema
+// Edit freely. Validate with `dg validate`.
+
+// ─── Reference resolution rules ──────────────────────────────────────────────
+
+ref-format {
+    string-id pattern="^(ADR|INC|POL|OPP|SPEC|PROC)-\\d+$"
+    relative-path pattern="\\.md$"
+}
+
+// ─── Relations ───────────────────────────────────────────────────────────────
+
+relation "supersedes" inverse="superseded_by" cardinality="one" description="Replaces a previous document"
+relation "enables" inverse="enabled_by" cardinality="many" description="Prerequisite — target can exist but can't succeed without source"
+relation "triggers" inverse="triggered_by" cardinality="many" description="Direct cause — target was created specifically because of source"
+relation "depends_on" inverse="dependency_of" cardinality="many" description="Cannot proceed until target is resolved"
+relation "implements" inverse="implemented_by" cardinality="many" description="Technical realization of a policy or opportunity"
+relation "conflicts_with" cardinality="many" description="Contradicts or creates tension with target"
+relation "related" cardinality="many" description="Loosely associated — use a more specific relation when possible"
+
+// ─── ADR: Architecture Decision Record ───────────────────────────────────────
+
+type "adr" description="Architecture Decision Record" folder="docs/architecture" {
+    alias "architecture" "tech"
+    field "status" type="enum" required=#true default="proposed" description="Lifecycle state" {
+        values "proposed" "accepted" "rejected" "deprecated" "superseded"
+        transition "proposed" "accepted" "rejected"
+        transition "accepted" "deprecated" "superseded"
+    }
+    field "author" type="user" required=#true description="Decision author"
+    field "date" type="string" required=#true pattern="^\\d{4}-\\d{2}-\\d{2}$" default="$TODAY"
+    field "tags" type="string[]"
+    field "code_paths" type="string[]" description="Glob patterns of source code paths related to this decision"
+
+    section "Context" required=#true description="Problem statement and constraints" {
+        content min-paragraphs=1
+    }
+    section "Decision" required=#true description="The decision and rationale" {
+        content min-paragraphs=1
+    }
+    section "Consequences" required=#true {
+        section "Positive" required=#true
+        section "Negative"
+    }
+}
+
+// ─── POL: Policy Document ────────────────────────────────────────────────────
+
+type "pol" description="Policy Document" folder="docs/policies" {
+    alias "policy"
+    field "status" type="enum" required=#true default="proposed" description="Lifecycle state" {
+        values "proposed" "active" "deprecated" "superseded"
+        transition "proposed" "active"
+        transition "active" "deprecated" "superseded"
+    }
+    field "author" type="user" required=#true description="Policy author"
+    field "owner" type="user" description="Current policy owner"
+    field "date" type="string" required=#true pattern="^\\d{4}-\\d{2}-\\d{2}$" default="$TODAY"
+    field "review_date" type="string" pattern="^\\d{4}-\\d{2}-\\d{2}$" description="Next review date"
+    field "tags" type="string[]"
+    field "code_paths" type="string[]" description="Glob patterns of source code paths related to this policy"
+
+    section "Purpose" required=#true description="Why this policy exists" {
+        content min-paragraphs=1
+    }
+    section "Policy" required=#true description="The policy statement" {
+        content min-paragraphs=1
+    }
+    section "Scope" required=#true description="Who and what this policy applies to"
+    section "Compliance" description="How compliance is measured"
+    section "Roles" description="Roles and responsibilities"
+    section "Enforcement" description="Consequences of non-compliance"
+    section "Review History" {
+        table {
+            column "Date" type="string" required=#true
+            column "Reviewer" type="user" required=#true
+            column "Changes" type="string" required=#true
+        }
+    }
+}
+
+// ─── OPP: Opportunity ────────────────────────────────────────────────────────
+
+type "opp" description="Opportunity" folder="docs/opportunities" {
+    alias "opportunity"
+    field "status" type="enum" required=#true default="identified" description="Discovery phase" {
+        values "identified" "validating" "pursuing" "completed" "deprecated" "declined"
+        transition "identified" "validating" "declined"
+        transition "validating" "pursuing" "declined"
+        transition "pursuing" "completed" "declined"
+        transition "completed" "deprecated"
+    }
+    field "author" type="user" required=#true description="Opportunity author"
+    field "owner" type="user" description="Current opportunity owner"
+    field "priority" type="enum" description="Priority level" {
+        values "critical" "high" "medium" "low"
+    }
+    field "effort" type="enum" description="Estimated effort" {
+        values "small" "medium" "large"
+    }
+    field "impact" type="enum" description="Expected impact" {
+        values "critical" "high" "medium" "low"
+    }
+    field "date" type="string" required=#true pattern="^\\d{4}-\\d{2}-\\d{2}$" default="$TODAY"
+    field "tags" type="string[]"
+
+    section "Description" required=#true description="What is the opportunity and why it matters" {
+        content min-paragraphs=1
+    }
+    section "Impact" description="Expected business impact with evidence (revenue, retention, competitive advantage)"
+    section "Success Metrics" description="Measurable KPIs to evaluate if this delivered value" {
+        list min-items=1
+    }
+    section "Non-Goals" description="What is explicitly out of scope to prevent scope creep" {
+        list min-items=1
+    }
+    section "Alternatives Considered" description="Other approaches evaluated and why they were not chosen" {
+        table {
+            column "❓" type="string" required=#true
+            column "Option" type="string" required=#true
+            column "Rationale" type="string" required=#true
+        }
+    }
+    section "Risks" description="Known risks and mitigations that could prevent success"
+    section "Requirements" description="Technical and business requirements for pursuing this opportunity"
+
+    rule "active requires Requirements table" {
+        when "status" equals-any="pursuing,completed"
+        then-section-table "Requirements" {
+            table {
+                column "Status" type="enum" required=#true {
+                    values "completed" "in-progress" "pending"
+                }
+                column "Requirement" type="string" required=#true
+                column "Owner" type="user" required=#true
+            }
+        }
+    }
+}
+
+// ─── INC: Incident Report ────────────────────────────────────────────────────
+
+type "inc" description="Incident Report" folder="docs/incidents" {
+    alias "incident"
+    field "status" type="enum" required=#true default="open" description="Incident state" {
+        values "open" "mitigated" "resolved"
+        transition "open" "mitigated" "resolved"
+        transition "mitigated" "resolved"
+    }
+    field "severity" type="enum" required=#true description="Severity level" {
+        values "sev1" "sev2" "sev3" "sev4"
+    }
+    field "commander" type="user" description="Incident commander"
+    field "responders" type="user[]" description="Incident responders"
+    field "date" type="string" required=#true pattern="^\\d{4}-\\d{2}-\\d{2}$" default="$TODAY"
+    field "duration" type="string" description="Total incident duration (e.g. 2h 30m, 45m, 3d)"
+    field "tags" type="string[]"
+
+    section "Summary" required=#true description="What happened" {
+        content min-paragraphs=1
+    }
+    section "Timeline" required=#true description="Chronological events" {
+        table {
+            column "Time" type="string" required=#true
+            column "Event" type="string" required=#true
+            column "Actor" type="user"
+        }
+    }
+    section "Root Cause" required=#true description="Root cause analysis"
+    section "Five Whys" description="5-Whys root cause drill-down" {
+        list min-items=1 ordered=#true
+    }
+    section "Action Items" {
+        table {
+            column "Status" type="enum" required=#true {
+                values "completed" "in-progress" "pending"
+            }
+            column "Action" type="string" required=#true
+            column "Owner" type="user" required=#true
+            column "Due Date" type="date"
+        }
+    }
+}
+
+// ─── README: Project overview ────────────────────────────────────────────────
+
+type "readme" folder="." max_count=1 singleton=#true description="Project README" {
+    match "README.md"
+
+    section "Architecture" required=#true description="High-level system diagram (C4, block, etc.)" {
+        diagram required=#true
+    }
+    section "Risks" required=#true min-subsections=1 callout=#true description="Top business risks: data breach, GDPR, data loss, pricing errors, theft, reputation damage, etc." {
+    }
+    section "License" required=#true description="License name or proprietary notice" {
+        content min-paragraphs=1
+    }
+}
+
+// ─── Service README: Per-service overview ────────────────────────────────────
+
+type "service-readme" folder="services" singleton=#true description="Service README in monorepo" {
+    match "README.md"
+
+    section "Architecture" required=#true description="Service-level architecture diagram" {
+        diagram required=#true
+    }
+    section "Local Development" required=#true description="Setup, build, test, run instructions" {
+        section "Setup" required=#true description="Environment setup" {
+            content min-paragraphs=1
+        }
+        section "Build" description="Build instructions" {
+            content min-paragraphs=1
+        }
+        section "Test" required=#true description="How to run tests" {
+            content min-paragraphs=1
+        }
+        section "Run" required=#true description="How to run locally" {
+            content min-paragraphs=1
+        }
+    }
+}
+
+type "app-readme" folder="apps" singleton=#true description="App README in monorepo" {
+    match "README.md"
+
+    section "Local Development" required=#true description="Setup, build, test, run instructions" {
+        section "Setup" required=#true description="Environment setup" {
+            content min-paragraphs=1
+        }
+        section "Test" required=#true description="How to run tests" {
+            content min-paragraphs=1
+        }
+        section "Run" required=#true description="How to run locally" {
+            content min-paragraphs=1
+        }
+    }
+}
+
+// ─── SPEC: Behavioral Specification / User Story ────────────────────────────
+
+type "spec" description="Behavioral Specification / User Story" folder="docs/specs" nav_label="specifications" {
+    alias "feature"
+    field "status" type="enum" required=#true default="draft" description="Spec lifecycle" {
+        values "draft" "proposed" "approved" "implemented" "deprecated"
+        transition "draft" "proposed"
+        transition "proposed" "approved"
+        transition "approved" "implemented" "deprecated"
+        transition "implemented" "deprecated"
+    }
+    field "priority" type="enum" description="MoSCoW priority" {
+        values "must" "should" "could"
+    }
+    field "author" type="user" required=#true description="Spec author"
+    field "date" type="string" required=#true pattern="^\\d{4}-\\d{2}-\\d{2}$" default="$TODAY"
+    field "tags" type="string[]"
+
+    section "Story" required=#true description="User story (As a / I want / So that)" {
+        content min-paragraphs=1
+    }
+    section "Scenarios" required=#true description="Gherkin scenarios in code blocks"
+    section "Acceptance Criteria" description="Non-Gherkin acceptance conditions" {
+        list min-items=1
+    }
+}
+
+// ─── PROC: Process Document ─────────────────────────────────────────────────
+
+type "proc" description="Process Document" folder="docs/processes" {
+    alias "process"
+    field "status" type="enum" required=#true default="draft" description="Process lifecycle" {
+        values "draft" "proposed" "active" "deprecated" "superseded"
+        transition "draft" "proposed"
+        transition "proposed" "active"
+        transition "active" "deprecated" "superseded"
+    }
+    field "author" type="user" required=#true description="Process author"
+    field "owner" type="user" description="Accountable process owner"
+    field "date" type="string" required=#true pattern="^\\d{4}-\\d{2}-\\d{2}$" default="$TODAY"
+    field "review_date" type="string" pattern="^\\d{4}-\\d{2}-\\d{2}$" description="Next review date"
+    field "tags" type="string[]"
+
+    section "Overview" required=#true description="Purpose and scope of the process" {
+        content min-paragraphs=1
+    }
+    section "Inputs and Prerequisites" required=#true description="Triggers and required state to begin" {
+        list min-items=1
+    }
+    section "Outputs" required=#true description="Expected artifacts and end state" {
+        list min-items=1
+    }
+    section "Roles and Responsibilities" description="RACI matrix for the process" {
+        table {
+            column "Role" type="string" required=#true
+            column "Responsibility" type="string" required=#true
+            column "Owner" type="user"
+        }
+    }
+    section "Process Flow" required=#true description="High-level visual flow" {
+        diagram required=#true
+    }
+    section "Steps" required=#true description="Detailed step-by-step procedure" {
+        list min-items=1 ordered=#true
+    }
+    section "Exceptions and Escalation" description="Handling edge cases and failure modes"
+    section "Metrics" description="Key performance indicators and SLAs"
+    section "Revision History" {
+        table {
+            column "Date" type="string" required=#true
+            column "Author" type="user" required=#true
+            column "Changes" type="string" required=#true
+        }
+    }
+}
+
+type "note" description="Note" folder="docs/notes" {
+    alias "note"
+
+    field "author" type="user" required=#true description="Spec author"
+    field "date" type="string" required=#true pattern="^\\d{4}-\\d{2}-\\d{2}$" default="$TODAY"
+    field "tags" type="string[]"
+}
diff --git a/.editorconfig b/.editorconfig
index ef6c51e..503ed25 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -8,6 +8,9 @@ indent_style = space
 max_line_length = 120
 trim_trailing_whitespace = true
 
+[schema.kdl]
+max_line_length = 250
+
 [SKILL.md]
 max_line_length = 200
 
diff --git a/.gitignore b/.gitignore
index c6fedbc..1bd10c5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 .DS_Store
 .dg/
 .dg.lock
+cache/
diff --git a/.mise.toml b/.mise.toml
index 41085c1..afae846 100644
--- a/.mise.toml
+++ b/.mise.toml
@@ -36,4 +36,6 @@ harper-cli lint --user-dict-path .config/lingo.dic --dialect au \
 """
 
 [tasks.dg-check]
-run = "dg validate --pattern 'docs/architecture/*.md'"
+# Ignore some S rules that apply to README.md
+# U011 ignored as dg appears unable to resolve user identifiers
+run = "dg validate --skip S032,S010"
diff --git a/README.md b/README.md
index 14f583a..08cba86 100644
--- a/README.md
+++ b/README.md
@@ -6,9 +6,13 @@ This repository uses [`mise`](https://mise.jdx.dev/) for tool management and tas
 
 After installing `mise`, run `mise run check` to check the repository contents.Decision Graph
 
+## Architecture
+
 This repository uses [decision graph](https://decisiongraph.dev/) CLI to assist manage
 the documents here.
 
+The Architecture docs are located under [docs/architecture](docs/architecture).
+
 ## Spelling and grammar
 
 The following Rust utilities used for spelling and grammar.
diff --git a/dg.toml b/dg.toml
deleted file mode 100644
index ee2665a..0000000
--- a/dg.toml
+++ /dev/null
@@ -1,51 +0,0 @@
-record_types = []
-
-[site]
-title = "Decision Graph"
-description = "Company decisions and knowledge graph"
-primary_color = "#0f3460"
-accent_color = "#e94560"
-quick_preview = true
-github_avatars = true
-
-[authors]
-
-[users.pierre-tenedero]
-name = "Pierre Tenedero"
-github = "pierre-tenedero"
-
-[users.claude]
-name = "Claude"
-email = "claude@anthropic.com"
-teams = ["llms"]
-roles = [
-  "llm",
-  "assistant",
-]
-
-[users.michaeljfazio]
-name = "Michael J. Fazio"
-github = "michaeljfazio"
-
-[users.jamesbychance]
-name = "James Eggleston"
-github = "jamesbychance"
-
-[users.jayvdb]
-name = "John Vandenberg"
-github = "jayvdb"
-email = "jayvdb@gmail.com"
-
-[users.Zoybean]
-name = "Zoey Hewll"
-github = "Zoybean"
-
-[teams.llms]
-name = "AI Assistants"
-description = "LLM-powered assistants"
-
-[teams.core]
-name = "edge-toolkit Core Team"
-description = "Core team members"
-
-[validation]
diff --git a/docs/architecture/adr-001-decisions.md b/docs/architecture/adr-001-decisions.md
index 6da9af5..c67b259 100644
--- a/docs/architecture/adr-001-decisions.md
+++ b/docs/architecture/adr-001-decisions.md
@@ -1,8 +1,6 @@
 ---
-id: ADR-001
 status: proposed
 date: 2026-03-18
-updated: 2026-04-24
 author: jayvdb
 tags: [architecture]
 ---
diff --git a/docs/architecture/adr-003-cluster-generation.md b/docs/architecture/adr-003-cluster-generation.md
index 771e660..3d0891b 100755
--- a/docs/architecture/adr-003-cluster-generation.md
+++ b/docs/architecture/adr-003-cluster-generation.md
@@ -1,5 +1,4 @@
 ---
-id: ADR-003
 status: proposed
 date: 2026-04-28
 author: pierre-tenedero
@@ -13,7 +12,7 @@ tags: [architecture]
 `edge-toolkit` needs a standardised way to define scenarios through configuration files and reliably transform those
 definitions into runnable deployments.
 
-## Decisions
+## Decision
 
 We will introduce `et-cli` as a cluster generation tool that reads a scenario configuration (YAML) file and produces the
 corresponding deployment artifacts.