Initial entity shape and roster

Status: open/draft · Target date: 2026-06-17

Goal

M0001 settles MML68’s upstream documents in five groups:

1. Evolutionary project structure — declare the current state (substrate at apps/sdlc/lib/) and the end-state target (a standalone top-level substrate when a non-plugin consumer appears), with the supporting code reorganization shipped now.
2. First-pass datamodel description — qualitative categorization of entity types, the proposed entity roster, the entity-definition contract (canonical markdown + machine-readable projections), and first-pass project-local validation.
3. Initial set of entity definitions against that contract — decision, milestone, principle, and standard — shipped at their canonical home under apps/sdlc/lib/model/entities/.
4. Self-improvement working rules — codify the apply-now-not-later default observed across M0001 (per-type identifier migration pulled in, Decision Summary retrofit, contradiction-fix pass, the markdown-standard work’s bundled corpus reformat). Captured as P-0011-avoid-deferral-for-simple-tasks so future milestones inherit the default rather than relitigate it.
5. Markdown Standard
   1. T-0006 — Research and declare a standard (ADR + Standard) for markdown with Obsidian compatibility as a primary constraint
   2. T-0007 — Research formatting tools
   3. T-0008 — Implement formatting in commit hooks and with a skill launcher

Document-only; the framework code that consumes these declarations lands in MML68.

Success criteria

• D-0001-project-structure — Evolutionary Project Structure Description (decision + code reorg)
  • declaration of current state versus end-state
  • description of current state
• First pass datamodel descriptions. Artificats: decisions, standards, project skills
  • Data Model Categorization — qualitative categorization of entity types
  • D-ORMG-data-model — proposed roster of entities with one-line purpose statements
  • D-0002-entity-identifier-shape — identifier convention for entity filenames + wikilinks
  • S-0005-entity-definition-contract — Define the datamodel entity definition contract.
    • where the definitions go
    • files and formats comprising the definition
      • canonical document (markdown)
      • machine-readable projections (JSON/YAML/MD)
    • first pass validation (with project-local skills) — T-0001
• Entity specifications coherent
  • each entity’s schema.json / body-schema.yaml / body-template.eta / definition.md internally consistent
  • existing standards corpus (S0001–S0005) validates against the new standard schema
• Define initial set of entities against the aforementioned contract (in-code entity definitions):
  • decision
  • milestone
  • principle
  • standard
• P-0011-avoid-deferral-for-simple-tasks — self-improvement working rule authored; M0000 Project roster updated; examples cite M0001 evidence

Deliverables

Project structure (evolutionary)

• D-0001-project-structure — Decision section names current state (substrate at apps/sdlc/lib/) and end-state target (standalone top-level substrate on second consumer); current-state survey enumerates the substrate libraries; transition rule and layout rules explicit.
• Code reorganization. Substrate co-located with the SDLC app at apps/sdlc/lib/ (git history preserved via git mv); no separate top-level substrate directory. No semantic change; this aligns authoring location with the deployed shape per the ADR.

Datamodel description

• D-0003-datamodel-categorization — qualitative categorization of entity types: the five-layer model (Product / Architecture / SDLC / Work / Planning-meta). Layer definitions, rationale, and design framing for each layer. Supersedes the broader entity-model document; per-entity discussion now lives in D-ORMG-data-model and per-entity definition.md files.
• D-ORMG-data-model — five-layer roster with per-layer tables (status, purpose, source). Source column points at apps/sdlc/lib/model/entities/<type>/ for entities specified there. Reviewed for completeness; gaps either closed or marked deferred.
• D-0002-entity-identifier-shape — per-type filename-shape rule (slug-bearing for Milestone / Decision / Standard / Principle / Epic; slug-less for Task / Backlog); ids per D-0002-entity-identifier-shape (milestones random base-36, other types sequential zero-padded), order in roadmap manifest. Migration of the existing catalogued corpus lands in M0001 via T-0002.
• S-0005-entity-definition-contract — the entity-definition contract:
  • Where the definitions go: apps/sdlc/lib/model/entities/<type>/.
  • Files and formats comprising the definition:
    • Canonical document: definition.md (markdown — authoritative for what the entity is).
    • Machine-readable projections: schema.json (frontmatter contract), body-schema.yaml (H2 body manifest), base.yaml (frontmatter defaults), body-template.eta (starting-point markdown for new instances).
  • First-pass validation: the entity-drift check landed via T-0001 enforces contract / schema / body shape across apps/sdlc/lib/model/entities/.
  • Scaffolding-registration and validator-registration obligations are non-file requirements the framework enforces.
• T-0001 — adds an entity-drift check to the project-local .claude/skills/project-check/ skill, wired into lefthook.yml as a pre-commit step. Walks apps/sdlc/lib/model/entities/ and reports contract drift (missing S0005 artifacts), schema drift (frontmatter not validating), body drift (H2 structure violations). Establishes the “skill references the canonical document, doesn’t duplicate it” pattern.

Identifier migration + verification

• T-0002 — single coordinated pass: Milestones M<NNNN>.md → M<NNNN>-<slug>.md; Decisions get D<NNNN> ids and rename to D<NNNN>-<slug>.md; inbound wikilinks swept across docs/; roadmap.md created/ updated as the milestone manifest. Pulled in from MML68.
• T-0003 — adds an identifier-shape check to .claude/skills/project-check/, wired into lefthook.yml. Checks filename shape, frontmatter id: consistency, wikilink resolution, id uniqueness. Reads the prefix table from D-ORMG-data-model at runtime; no rule duplication.

Skills

• T-0004 — new project-local skill at .claude/skills/contradiction-review/. Spawns a fresh-context subagent to find contradictions within a PR’s diff and against the existing tree; output is short bullets, no narrative. Establishes the “fresh-context subagent for repeatable review” pattern.
• T-0005 — adds an awaiting-llm-review value to every M0001 entity’s status enum (post-proposed, pre-accepted/active) plus a distributed SDLC skill at apps/sdlc/skills/sdlc-llm-review/. Scans docs/planning/ for entities at that status, spawns a fresh-context subagent per file to author placeholder sections, flips status back to proposed, and opens one PR per authored file. Workflow is uniform for any downstream consumer of the plugin.

Entity specifications (apps/sdlc/lib/model/entities/)

• decision — full file set. Body convention: Summary (required, at top, with ^summary block-id; placeholder allowed until status: accepted) + Decision (required, with aliases) + flexible optional sections. Status enum: proposed | accepted | superseded | deprecated.
• milestone — full file set. Body convention: Goal / Success criteria / Deliverables / Out of scope / Risks.
• principle — full file set. Body convention: Statement / Why / How it applies / Examples / Implications / Notes / Summary. First Summary bullet carries ^summary.
• standard — full file set. Body convention: Rule (required, with aliases) / Why / How to apply / Anti-examples / Scope / Notes / References. Status enum: proposed | active | superseded | deprecated. Frontmatter MUST carry applies_to.paths.

Self-improvement working rules

• P-0011-avoid-deferral-for-simple-tasks — codifies the apply-now-not-later default surfaced repeatedly across M0001 (per-type identifier migration pulled into M0001 rather than deferred to MML68; Decision Summary retrofit on the 3 existing ADRs; contradiction-fix pass after the prototype subagent run; markdown-standard work bundled with its corpus reformat). Body shape (Statement / Why / How it applies / Examples / Implications / Notes / Summary) populated; ^summary block-id present; added to M0000’s Project principles roster. Status: proposed; flips to accepted at milestone close.

Reviews

• S0005 verified against all four specifications: every required artifact present, body manifests match the entity definition’s “Body shape” sections, no contract clauses unsatisfied without explicit note.
• Existing standards (S0001–S0005) validated against the new standard schema + body manifest. Divergences either fixed in the instances or recorded as schema adjustments before close.
• D-ORMG-data-model rows for Milestone, Principle, Decision, Standard reflect status: spec shipped (M0001).
• User-acceptance pass on each Decision (ADR) before this milestone closes.

Out of scope

• Task file migration (YYYY-MM-DD-<slug>.md → id+slug shape): deferred to a later milestone after the catalogued corpus stabilizes, per D-0002-entity-identifier-shape.
• Legacy scaffold and validator code migration into the entity substrate: M-ML68.
• The entity validator framework code itself: M-ML68.
• The definition.md → schema.json / body-schema.yaml projector / generator: deferred to a later milestone after the entity specifications stabilize.
• Capability tree validation, ADR/Principle scaffold migration: M-ML68.
• Task lifecycle reference doc: M-ML68.
• Lifting the substrate to a standalone top-level location: deferred until a non-plugin consumer appears, per D-0001-project-structure.
• Task tightening: M-VRVE. Orchestration: M-QDQ4.

Risks / open questions

• Contract drift across entities. The four entity specs were authored against the S0005 contract in parallel; the review pass may surface contract clauses no spec satisfies or spec fields the contract doesn’t mention. Fix the contract or the instance; don’t paper over.
• Boundary between Principle and Standard. Working rubric: if judgment is required for edge cases, it’s a Principle; if a validator could check it on a scoped path, it’s a Standard. Test against the review work.
• Decision entity body manifest permissiveness. allow_unknown: true + order: lenient accepts the variety of shapes existing ADRs exhibit, but may be too permissive long-term. Tighten once a larger corpus of Decisions accumulates.
• Standard entity status enum. Existing standards use status: active; the schema lands proposed | active | superseded | deprecated. Confirm against the existing S0001–S0005 corpus during review.
• Substrate boundary discipline. Authoring substrate under apps/sdlc/lib/ relies on import discipline (no substrate module reaches into harness-coupled surface) rather than directory placement. Worth a Standard-derived validator pass once the substrate stabilizes per D-0001-project-structure.

---

← Back to Milestones