Governance area
Conventions and project memory. Touches Communication and, as a follow-up,
Linting.
Current situation
The project has no defined mechanism for recording significant, hard-to-reverse
decisions: toolchain choices, structural conventions, deferred migrations, the
rejection of alternatives. Today the reasoning behind such decisions survives
only in meetings, chat, and the memory of whoever was present. Version-control
history records what changed and when, but it is a forensic substrate, not a
readable one. A future builder, reviewer, or auditor has no durable answer to
"why was it done this way, and what else was considered?"
Proposed change
Adopt a decision record practice (the industry "Architecture Decision
Record" practice, generalised beyond architecture to any decision of
consequence):
- Add a normative governance document
00-project-governance/decision-records.md
defining the practice: what belongs in a record, scope, lifecycle, the
immutability rule, the record template, and enforcement.
- Establish the
decisions/ folder convention: PDR- records for project-wide
decisions in 00-project-governance/decisions/; DR- records for
repository-local decisions in each repository's own decisions/ folder.
- Add
PDR-0000 as the meta-record that adopts the practice, plus a folder
README.md and index.
- Register the new document in the governance
README.md and in
00-project-governance/manifest.yaml.
Rationale
A decision record captures the reasoning as it stood at decision time. Made
immutable once accepted, it becomes durable evidence rather than a mutable
wiki page: the supersession chain stays readable as whole documents, and the
record survives repository migrations and version-control history rewrites. The
discipline is small and the cost it prevents, institutional amnesia, is large.
Impact
Affects every repository in the project and all builders, legal, technical,
operational, and audit. The change is non-breaking: it adds a convention and
leaves existing artefacts untouched.
Transition considerations
- The initial change is documentation-only.
SET-GOV in manifest.yaml may warrant a version bump per the configuration
management strategy; the new file has been added to contains: either way.
- A matching "Decision Records" section in
linting-rules.md (formal LINT-
rules) is a sensible follow-up so the immutability and numbering checks become
mechanical.
- Each repository adopts its own
DR-0000 over time.
References
00-project-governance/decision-records.md
00-project-governance/decisions/PDR-0000-adopt-decision-records.md
00-project-governance/decisions/README.md
00-project-governance/communication-and-project-management.md
00-project-governance/linting-rules.md
Governance area
Conventions and project memory. Touches Communication and, as a follow-up,
Linting.
Current situation
The project has no defined mechanism for recording significant, hard-to-reverse
decisions: toolchain choices, structural conventions, deferred migrations, the
rejection of alternatives. Today the reasoning behind such decisions survives
only in meetings, chat, and the memory of whoever was present. Version-control
history records what changed and when, but it is a forensic substrate, not a
readable one. A future builder, reviewer, or auditor has no durable answer to
"why was it done this way, and what else was considered?"
Proposed change
Adopt a decision record practice (the industry "Architecture Decision
Record" practice, generalised beyond architecture to any decision of
consequence):
00-project-governance/decision-records.mddefining the practice: what belongs in a record, scope, lifecycle, the
immutability rule, the record template, and enforcement.
decisions/folder convention:PDR-records for project-widedecisions in
00-project-governance/decisions/;DR-records forrepository-local decisions in each repository's own
decisions/folder.PDR-0000as the meta-record that adopts the practice, plus a folderREADME.mdand index.README.mdand in00-project-governance/manifest.yaml.Rationale
A decision record captures the reasoning as it stood at decision time. Made
immutable once accepted, it becomes durable evidence rather than a mutable
wiki page: the supersession chain stays readable as whole documents, and the
record survives repository migrations and version-control history rewrites. The
discipline is small and the cost it prevents, institutional amnesia, is large.
Impact
Affects every repository in the project and all builders, legal, technical,
operational, and audit. The change is non-breaking: it adds a convention and
leaves existing artefacts untouched.
Transition considerations
SET-GOVinmanifest.yamlmay warrant a version bump per the configurationmanagement strategy; the new file has been added to
contains:either way.linting-rules.md(formalLINT-rules) is a sensible follow-up so the immutability and numbering checks become
mechanical.
DR-0000over time.References
00-project-governance/decision-records.md00-project-governance/decisions/PDR-0000-adopt-decision-records.md00-project-governance/decisions/README.md00-project-governance/communication-and-project-management.md00-project-governance/linting-rules.md