This policy defines how decisions are made, recorded, and enforced in the project. It covers the charter’s role as a frozen decision document, the requirements lifecycle, the decision log format, and the approval workflows for commits and requirement changes.
Who this is for
- Implementors proposing changes that affect scope, architecture, or validation rules.
- Developers understanding when and how to document decisions and request exceptions.
- AI agents following correct change control workflows when modifying CORE-OWNED files, changing requirement statuses, or creating commits.
Charter as Frozen Decision Document
The project charter (.docs/charter.md) is the authoritative source for high-level decisions: technology choices, component inventories, token rules, configuration schemas, and architectural boundaries. It contains 28 decision sections.
What the charter governs
- Technology stack and framework version targets
- Tier-1 curated sources for UI components
- Design token architecture (primitives, semantic, bridge)
- Content collection schemas and route structures
- File ownership model (CORE vs SITE zones)
- Validation pipeline requirements and quality gates
- Accessibility and performance standards
Amendment process
The charter is frozen after approval. Existing decisions cannot be modified without a formal change request:
- Identify the section — cite the specific
(§N)section that would change. - Document the proposal — state what changes and why the original decision no longer holds.
- Get project owner approval — the owner must explicitly approve the amendment.
- Append, don’t rewrite — new decisions are added to section 28 (post-freeze addenda). Original sections are not edited.
If a decision does not conflict with the charter, it does not require an amendment — it goes in the decision log instead.
Decision Log (.docs/decisions.md)
Implementation decisions made after the charter was frozen are recorded in .docs/decisions.md. This is the record of how the charter is interpreted and extended during implementation.
When to log a decision
Log a decision when:
- An implementation choice interprets or extends a charter section
- A tradeoff is made between competing approaches
- A requirement is deprecated or its scope is changed
- A convention is established that future work must follow
- An architectural pattern is adopted or rejected (REQ-00196)
Format conventions
Each entry is a row in the decision log table:
| Field | Content |
|---|---|
| Date | ISO date (YYYY-MM-DD) |
| Decision | Short identifier (e.g., D-C7-01) followed by a concise description |
| Rationale | Why this decision was made, with charter section references using (§N) |
| Status | Approved, Superseded, or Reverted |
Rules
- Append-only. New entries are added at the top. Existing entries are never edited or deleted.
- Supersede, don’t edit. If a decision is reversed, add a new entry that supersedes it. Mark the original as
Superseded. - Cite charter sections. Every entry that relates to a charter decision must reference the section:
(§N).
Requirement Lifecycle (REQ-00138)
Requirements in src/core/config/requirements.catalog.ts move through defined statuses. Status changes reflect real progress and require explicit approval.
Statuses
| Status | Meaning |
|---|---|
draft | Proposed, not yet reviewed or approved |
planned | Approved for implementation in a future work package |
normative | Active and enforced — the requirement governs current work |
implemented | Code exists that satisfies the requirement |
verified | Implementation has been tested and confirmed correct |
deprecated | No longer applicable — superseded or removed |
Approval rules
- Status changes require project owner approval. No agent or contributor may change a requirement’s
statusfield without presenting the proposed change and receiving explicit sign-off. - Prevent placeholder drift. Statuses must reflect current reality. A requirement marked
implementedmust have shipping code. A requirement markedverifiedmust have passed validation.
Requirement Metadata (REQ-00139)
Requirements should define appliesTo and dependsOn metadata when material dependencies or documentation applicability exist.
appliesTo
An array of DOC-NNNNN identifiers linking a requirement to the documentation pages it governs. This metadata powers the related requirements section on doc pages and helps implementors find the rules that apply to their work.
dependsOn
An array of REQ-NNNNN identifiers indicating that a requirement cannot be implemented until its dependencies are satisfied. This supports sequencing decisions in work planning.
Not every requirement needs these fields. Add them when the linkage is meaningful — do not force metadata on entries where no material dependency or documentation applicability exists.
Architecture Decision Records (REQ-00196)
Significant architectural, technology, and process decisions must be documented and tracked in the project decisions log. This formalizes the existing .docs/decisions.md practice as a normative requirement.
ADRs are not a separate document type in this project. They are entries in the decision log with sufficient detail to capture:
- What was decided
- Why (rationale and tradeoffs considered)
- What charter section(s) it relates to
- Status (Approved, Superseded, Reverted)
Commit and PR Approval Workflows
Commit approval
Every commit requires explicit project owner sign-off before staging and committing. The workflow:
- Present the full proposed commit message.
- Wait for explicit approval (“yes”, “approved”, or equivalent).
- Stage the specific files and create the commit.
- Never commit without approval — even if the change is small.
This applies to all contributors and AI agents. The commit message format is defined in .docs/standards/GIT.md.
Requirement status changes
When a requirement’s status needs to change:
- Present the proposed status change — requirement ID, current status, proposed status, and justification.
- Wait for explicit project owner approval.
- Make the change only after sign-off.
This rule exists because requirement statuses drive planning and reporting. Unauthorized changes create drift between the catalog and reality.
Exception Process
When a policy or validation rule cannot be satisfied, follow the exception process defined in the Validation Pipeline (DOC-00007):
- Document the specific failure.
- Justify why it cannot be fixed now.
- Scope the exception narrowly (specific rule, specific file or element).
- Set an expiry with a follow-up task.
- Get project owner approval.
- Track the exception in the relevant config file.
Exceptions are never open-ended. Blanket waivers are not permitted.