Name and guard CDD's engineering-practices & self-improvement objectives#30
Merged
Conversation
Audit of CDD's three founding objectives found objective 1 (automate + human gates) well guarded, but objective 2 (instil engineering best practices) only half guarded — documentation enforced, testing/CI/lint merely suggested — and objective 3 (self-improvement) unnamed and weak in steady state. Root cause: §1 named four commitments, leaving objective 2's testing/CI half and objective 3 entirely off the philosophy. - Process doc §1: 4 → 5 commitments. Broaden "documents itself" into "the project holds itself to engineering standards as it grows" (docs as the leading enforced exemplar; tests/CI/lint instilled by mechanism and floor, not prescription); add "the workflow improves itself". - New §2.12 "engineering-practices contract": a canonical, enforced-vs- expected list, shipped as template/doc/knowledge_base/engineering-practices.md and instantiated in the CDD repo and the demo seed. - /cdd-pre-pr (both copies): new step 5 "Test coverage reconciliation" — the recurring objective-2 guardrail, parallel to doc reconciliation; surfaces and records, adds no checkpoint. Steps renumbered 5→6 … 9→10; smoke whitelist token bumped to "steps 3–7". - §3.5 describes test-coverage reconciliation; §6 records the deferred objective-3 standing channel as a known gap. - Investigation note doc/knowledge_base/founding-objectives-audit.md; roadmap Phase 11 capturing what landed and what defers (human-approved). Verified: command-drift clean, bootstrap + demo-seed smoke green. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Pre-PR doc reconciliation: point the surrounding docs at the new engineering-practices contract that landed in this branch. - CLAUDE.md: list engineering practices in the module-layout row. - demo/seed/CLAUDE.md: add the contract to the seed's key-references table (the seed ships the file but didn't point to it). - doc/index.md: add pointers for engineering-practices.md and the founding-objectives-audit.md investigation note. - doc/features/template.md: list engineering-practices.md among shipped template contents; note the bootstrap-phase fill task. - doc/features/demo.md: list the contract among the seed's filled-in docs. - doc/architecture/overview.md: update the knowledge_base tree comment. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
drabaioli
commented
Jun 19, 2026
Per PR review: the audit note was a report of this PR's work living in the knowledge base. Extract the durable decision into a Nygard ADR and drop the report (it already lives in the PR description). - New doc/architecture/adr/0001-name-and-guard-founding-objectives.md: Context = the audit findings, Decision = §1 reframe + §2.12 contract + /cdd-pre-pr reconciliation step, Consequences = guarded vs deferred Phase 11. - Delete doc/knowledge_base/founding-objectives-audit.md. - Repoint references: roadmap Phase 11, doc/index.md (drop the KB pointer), doc/architecture/index.md (list the ADR under adr/). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
drabaioli
commented
Jun 19, 2026
Per PR #30 review: the per-objective audit findings read as a PR report, not a durable record. Drop them, keeping the three founding objectives, the structural root cause that motivates the decision, and the Decision/Consequences sections. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Names and guards two of CDD's three founding objectives that an audit found under-protected, and reconciles the surrounding docs with the new contract.
template/doc/knowledge_base/engineering-practices.mdand instantiated in the CDD repo and the demo seed./cdd-pre-pr(both copies): new step 5 "Test coverage reconciliation" — the recurring objective-2 guardrail, parallel to doc reconciliation; surfaces and records, adds no checkpoint. Steps renumbered; smoke whitelist token bumped to "steps 3–7".doc/knowledge_base/founding-objectives-audit.md; roadmap Phase 11 capturing what landed and what defers.doc/index.md, and the feature/architecture docs at the new contract.Includes a merge of
origin/main(handoff-permission glob fix, #29).Test plan
bash -nacross all scripts — clean./scripts/command-drift-check.sh— clean--local-only) — ready🤖 Generated with Claude Code