stacklok / stacklok/modelith

Design follow-ups from the pre-OSS audit (7 items, non-blocking)

Open
#4 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
32
Forks
5
PR merge metrics
No merged PRs in 30d

Description

Parked design items from audits/2026-06-30-pre-oss-audit.md — none blocked
the public launch, but they were meant to be tracked as issues rather than
left sitting only in the audit file. Filing as one issue to avoid spawning
seven low-traffic tickets; split any of these out separately if one actually
gets worked.

  1. DDD omissions undocumenteddocs/06-schema-reference.md:79. Add a
    "What this format deliberately leaves out" section covering aggregates,
    value objects, domain events, bounded contexts, with a per-item
    out-of-scope/roadmap call. Probably the highest-leverage item here for
    credibility with a DDD-literate audience.

  2. Glossary/entity namespace collision unguarded
    internal/schema/v1/modelith.schema.json:28. A glossary key that promotes
    to an entity is silently ambiguous. Add a lint error, next to the existing
    duplicate-invariant-id check.

  3. Completeness check pressures junk invariants
    internal/lint/lint.go:496. The "entity has no invariants" warning +
    strict CI + the author skill together teach newcomers to invent
    cardinality-restating filler invariants. Soften the message; document that
    genuinely rule-free entities are fine.

  4. Ticket as value object in the flagship example
    docs/05-parking-garage/garage.modelith.yaml:222. Ticket is a textbook
    value object modeled as an owned 1:1 entity, since the format has no
    first-class value-object concept. The worked example should name this
    tension explicitly, turning a hidden limitation into a teaching moment.

  5. Cardinality optionality foot-gun
    internal/schema/v1/modelith.schema.json:148. 1:n carries no
    optionality; minimums live as invariants instead. The Mermaid renderer
    always emits ||--o{ (zero-or-many) even when an invariant says "at
    least one." Document this in schema-reference and cross-check
    04-reading-the-diagrams.md.

  6. Example violates its own relationship guidance
    docs/06-schema-reference.md:113. The reference recommends declaring a
    relationship from a single side, but example.modelith.yaml declares
    ProjectUser n:n redundantly from both ends. Either fix the example or
    make it the explicit "both ends add clarity" exception, with an
    explanation.

  7. Scenario steps have no stress-test convention
    docs/06-schema-reference.md:188. The reference calls scenarios
    "diagnostics," but nothing enforces or teaches the
    violation-then-refusal pattern (at least one scenario per invariant that
    attempts to violate it and shows the refusal).

Context / priority

All non-urgent — none of these blocked launch, and the audit only flagged
them as design (needs a decision/discussion), not easy. Pick off
individually as time allows; #1 and #3 probably have the best
credibility/clarity payoff for the effort.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with audits/2026-06-30-pre-oss-audit.md, then choose one item and read its referenced file: docs/06-schema-reference.md, internal/schema/v1/modelith.schema.json, internal/lint/lint.go, docs/05-parking-garage/garage.modelith.yaml, or docs/04-reading-the-diagrams.md. Confirm the scope and design decision with maintainers before changing anything; done means the selected concern is addressed with corresponding documentation, code, examples, or tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.