docs(decisions): accept ADRs 0018, 0020, 0021 and enforce the record contract

.github/instruction-surfaces.json

@@ -875,6 +875,18 @@
       "review_owner": "z-shell maintainers",
       "canonical_for": ["chroma-command-knowledge"]
     },
+    {
+      "id": "decision-index",
+      "path": "decisions/README.md",
+      "kind": "runbook",
+      "authority": "advisory",
+      "consumers": ["codex", "claude-code", "copilot", "gemini-cli", "human"],
+      "tasks": ["architecture-decision", "onboarding"],
+      "file_patterns": ["**"],
+      "required": false,
+      "review_owner": "z-shell maintainers",
+      "canonical_for": []
+    },
     {
       "id": "zsh-standard-policy",
       "path": "lib/zsh-standard-policy.json",
@@ -915,6 +927,18 @@
       "review_owner": "z-shell maintainers",
       "canonical_for": ["public-policy-validation"]
     },
+    {
+      "id": "decision-records-validator",
+      "path": "scripts/decision-records.py",
+      "kind": "enforcement",
+      "authority": "canonical-detail",
+      "consumers": ["ci", "human"],
+      "tasks": ["architecture-decision", "validation"],
+      "file_patterns": ["**"],
+      "required": true,
+      "review_owner": "z-shell maintainers",
+      "canonical_for": ["decision-record-validation"]
+    },
     {
       "id": "agent-instruction-workflow",
       "path": ".github/workflows/agent-instructions.yml",

.github/workflows/agent-instructions.yml

@@ -26,6 +26,8 @@ on:
       - "scripts/test_validate_agent_policy.py"
       - "scripts/validate-zsh-standard-policy.py"
       - "scripts/test_validate_zsh_standard_policy.py"
+      - "scripts/decision-records.py"
+      - "scripts/test_decision_records.py"
   push:
     branches:
       - main
@@ -53,6 +55,8 @@ on:
       - "scripts/test_validate_agent_policy.py"
       - "scripts/validate-zsh-standard-policy.py"
       - "scripts/test_validate_zsh_standard_policy.py"
+      - "scripts/decision-records.py"
+      - "scripts/test_decision_records.py"
 
 permissions:
   contents: read
@@ -80,6 +84,9 @@ jobs:
       - name: Run agent policy unit tests
         run: python3 -m unittest scripts/test_validate_agent_policy.py -v
 
+      - name: Run decision record unit tests
+        run: python3 -m unittest scripts/test_decision_records.py -v
+
       - name: Run Zsh standard policy unit tests
         run: python3 -m unittest scripts/test_validate_zsh_standard_policy.py -v
 
@@ -88,3 +95,6 @@ jobs:
 
       - name: Validate agent policy
         run: python3 scripts/validate-agent-policy.py
+
+      - name: Validate decision records and index
+        run: python3 scripts/decision-records.py --check

decisions/0011-zsh-lint-semantic-analyzer-architecture.md

@@ -1,12 +1,10 @@
 # 11. zsh-lint Conditional Semantic Analysis Pipeline
 
-Date: 2026-07-25
-
-Deciders: ss-o
-
-## Status
-
-ACCEPTED
+- **Status:** ACCEPTED
+- **Date:** 2026-07-25
+- **Deciders:** ss-o
+- **Supersedes:** None
+- **Superseded by:** None
 
 ## Context
 

decisions/0018-portable-worktree-management.md

@@ -1,6 +1,6 @@
 # 18. Adopt Portable Worktree Management
 
-- **Status:** PROPOSED
+- **Status:** ACCEPTED
 - **Date:** 2026-08-27
 - **Deciders:** ss-o
 - **Supersedes:** None

decisions/0020-adopt-zsh-plugin-standard-2.md

@@ -1,6 +1,6 @@
 # 20. Adopt Zsh Plugin Standard 2 as a Clean Portable Contract
 
-- **Status:** PROPOSED
+- **Status:** ACCEPTED
 - **Date:** 2026-08-28
 - **Deciders:** ss-o
 - **Supersedes:** None

decisions/0021-derive-chroma-knowledge-at-runtime.md

@@ -1,6 +1,6 @@
 # 21. Derive Chroma Command Knowledge at Runtime
 
-- **Status:** PROPOSED
+- **Status:** ACCEPTED
 - **Date:** 2026-08-29
 - **Deciders:** ss-o
 - **Supersedes:** None

decisions/README.md

@@ -0,0 +1,34 @@
+<!--
+GENERATED FILE. DO NOT EDIT DIRECTLY.
+Regenerate: python3 scripts/decision-records.py
+Check: python3 scripts/decision-records.py --check
+-->
+
+# Architecture decision records
+
+Durable organization decisions. Draft new records with `runbooks/adr.md`; only
+a maintainer moves a record from `PROPOSED` to `ACCEPTED`.
+
+| ADR                                                     | Title                                                          | Status   | Date       | Deciders          |
+| ------------------------------------------------------- | -------------------------------------------------------------- | -------- | ---------- | ----------------- |
+| [0001](0001-meta-repo-and-agents-md.md)                 | Adopt a meta-repo pattern centered on `AGENTS.md`              | ACCEPTED | 2026-05-29 | ss-o              |
+| [0002](0002-zi-as-canonical-plugin-manager.md)          | `zi` is the canonical plugin manager for the z-shell ecosystem | ACCEPTED | 2026-05-29 | ss-o              |
+| [0003](0003-conventional-commits.md)                    | Adopt Conventional Commits across z-shell repositories         | ACCEPTED | 2026-05-29 | ss-o              |
+| [0004](0004-dependabot-unification.md)                  | Standardize on Dependabot for Dependency Management            | ACCEPTED | 2026-05-20 | ss-o, Gemini CLI  |
+| [0005](0005-workflow-naming-conventions.md)             | No Emojis in Workflow and Job Name Fields                      | ACCEPTED | 2026-05-21 | ss-o, Claude Code |
+| [0006](0006-wiki-content-root-boundaries.md)            | Wiki Content-Root Boundaries                                   | ACCEPTED | 2026-05-29 | ss-o, Claude Code |
+| [0007](0007-release-publication-flow.md)                | Release and Publication Flow                                   | ACCEPTED | 2026-05-26 | ss-o, Claude Code |
+| [0008](0008-branching-model.md)                         | Branching Model                                                | ACCEPTED | 2026-07-25 | ss-o              |
+| [0009](0009-testing-ci-strategy.md)                     | Testing and CI Strategy                                        | ACCEPTED | 2026-07-25 | ss-o              |
+| [0010](0010-security-incident-response.md)              | Security Incident Response                                     | PROPOSED | 2026-05-29 | TBD               |
+| [0011](0011-zsh-lint-semantic-analyzer-architecture.md) | zsh-lint Conditional Semantic Analysis Pipeline                | ACCEPTED | 2026-07-25 | ss-o              |
+| [0012](0012-hybrid-dependency-management.md)            | Split Dependency Updates Between Renovate and Dependabot       | ACCEPTED | 2026-06-21 | ss-o              |
+| [0013](0013-repository-settings-baseline.md)            | Repository Settings Baseline by Class                          | ACCEPTED | 2026-07-25 | ss-o              |
+| [0014](0014-portable-agent-instruction-architecture.md) | Adopt portable agent-instruction delivery                      | ACCEPTED | 2026-07-23 | ss-o              |
+| [0015](0015-zsh-scripting-standard.md)                  | Adopt an organization-wide Zsh scripting standard              | ACCEPTED | 2026-08-27 | ss-o              |
+| [0016](0016-promotion-trigger-criteria.md)              | Next-to-Main Promotion Trigger Criteria                        | ACCEPTED | 2026-08-16 | ss-o              |
+| [0017](0017-licensing-standard-by-provenance.md)        | Licensing Standard by Provenance and Consumption               | ACCEPTED | 2026-08-18 | ss-o              |
+| [0018](0018-portable-worktree-management.md)            | Adopt Portable Worktree Management                             | ACCEPTED | 2026-08-27 | ss-o              |
+| [0019](0019-trunk-on-main-default.md)                   | Trunk-on-Main Default with a Zi Integration Exception          | ACCEPTED | 2026-08-28 | ss-o              |
+| [0020](0020-adopt-zsh-plugin-standard-2.md)             | Adopt Zsh Plugin Standard 2 as a Clean Portable Contract       | ACCEPTED | 2026-08-28 | ss-o              |
+| [0021](0021-derive-chroma-knowledge-at-runtime.md)      | Derive Chroma Command Knowledge at Runtime                     | ACCEPTED | 2026-08-29 | ss-o              |