governance: constitution, enforcement table and ADRs 0001-0003 (draft for review)

[mlieberman85]

Summary

Draft for maintainer review. This PR proposes a governance model for darnit, adapted from swansong's governance/:

• a short constitution in which every rule carries an enforcement id;
• ENFORCEMENT.md, which records each check's honest status;
• where-decisions-live.md, which routes each kind of decision to its document;
• immutable ADRs.

Nothing outside governance/ changes. CLAUDE.md, the Spec Kit constitution and framework-design.md are untouched until the ADRs are accepted.

What to review:

• governance/decisions/0001-what-darnit-is.md decides what darnit is for. darnit is a framework that aligns a project's setup with a hygiene goal, and it does not verify runtime behavior or tool outcomes. For example, it checks that gittuf is set up, not that history passes gittuf policy. It also defines a three-question admission test and lists the consequences, including which controls are cut or reframed.
  • It is an ADR rather than a "charter" because CHARTER.md is the LF Technical Charter.
• governance/constitution.md holds 18 rules:
  • S1–S6, scope and conservatism: setup not outcomes, unverified is not compliant, judgment values are never concluded, remediation does no harm, the audited repository is untrusted, authority ceilings.
  • F1–F6, framework shape: no implementation imports, controls in TOML, no premature extension points, everything accepted has a reader, every function and default implementation runs in a test, no new type errors.
  • C1, contracts.
  • A1–A4 and R1, contributors and agents.
• governance/ENFORCEMENT.md gives one row per rule, with an honest status and a build order. main currently requires no passing checks and no approvals, so CI gates nothing; R1 is first in the build order.
• governance/decisions/0002-governance-follows-swansong.md covers four changes:
  • the Spec Kit constitution becomes a pointer;
  • framework-design.md stops being "authoritative";
  • CLAUDE.md shrinks to routing;
  • governance/ is not a Spec Kit feature (as swansong's ADR-0006 decided).
• governance/decisions/0003-docs-consolidation.md gives a disposition for every doc, a section-by-section split of framework-design.md, and the contradictions to resolve first.

Decisions needed

1. Scope edge cases. Should the Baseline controls that grade zizmor findings stay? Are the threat-model analysis engine (006, 010, 011, 014) and the Scorecard wiring (023) in or out?
2. Model judgments. Should model judgments of document content stay, as PASS candidates a person confirms?
3. Report wording. Reports and the attestation would say "set up for", not "compliant with", for controls phrased as outcomes.
4. Contradictions from ADR-0003. For each, the draft proposes:
   • phase ordering: not enforced;
   • unknown step keys: fail loading;
   • remediation: FAIL only, not WARN;
   • [plugins] table: moves out of framework TOML;
   • RFC-0001's .baseline.toml promise: superseded by feat!: stop reading a repository's .baseline.toml #556.
5. Rule count. 18 rules is above swansong's "twelve steers" guidance. Trim?

Type of Change

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update
• Refactoring (no functional changes)

Framework Changes Checklist

• Updated framework spec (docs/architecture/framework-design.md) if behavior changed. Not applicable: no behavior changes, and ADR-0002 proposes retiring this checkbox.
• Ran uv run python scripts/validate_sync.py --verbose and it passes. No code changed.

Testing

• Tests pass locally (uv run pytest tests/ -v). Not applicable: docs only.
• Added tests for new functionality (if applicable)
• Linting passes (uv run ruff check .)

AI assistance

• No AI assistance was used
• AI assistance was used

Claude (Claude Code, claude-opus-5-5) drafted all of these documents at my request. The inputs were:

• swansong's governance model;
• the 2026-10-10 wiring audit, whose W-NN IDs are cited in ENFORCEMENT.md;
• an inventory of darnit's existing docs.

This description was also drafted with Claude. The commit carries an Assisted-by: Claude:claude-opus-5-5 trailer.

🤖 Generated with Claude Code

[Marc-cn]

Agree with the direction and with R1 first. On the five decisions:

1. Scope. zizmor controls: reframe to reading the workflow file. The zizmor result can change with the zizmor version, and with no workflows it is an exit-code WARN (#584). Threat-model engine and Scorecard wiring, don't havea strong view.
2. Model judgments. Keep them, as PASS candidates a person confirms. That is how it behaved when I ran an audit through LLMs.
3. "Set up for". Yes.
4. Contradictions. Unknown step keys fail loading: yes (--profile was accepted and ignored, #576). Remediation on FAIL only: yes.
5. Rule count. No opinions. Two bugs this week fit none of the 18: undeclared dependencies (#573) and the CLI and MCP paths giving different answers (#576, #577).