Skip to content

docs(spec): ratify the Webware Theme constitution v1.0.0 - #15

Open
tyrsson wants to merge 3 commits into
1.0.xfrom
docs/ratify-constitution
Open

tyrsson wants to merge 3 commits into
1.0.xfrom
docs/ratify-constitution

Conversation

@tyrsson

@tyrsson tyrsson commented Oct 10, 2026 •

Copy link
Copy Markdown
Member

Replaces the unfilled init template at .specify/memory/constitution.md. The repository has been running without a ratified constitution, so specs/001-theme-resolution/plan.md records that there are no project principles to gate against and substitutes a hand-written gate list.

This needs your read before it means anything. A constitution that does not match reality produces noise in every later gate check. The source of every claim is listed below so you can verify or reject each one.

Where each principle comes from

Principle Source
I. Library-First Shared with the console and migration constitutions
II. Resolution by Lookup specs/001-theme-resolution/decisions.md, .github/instructions/memory.instructions.md, data-model.md
III. Consumer-Agnostic Ecosystem composition doctrine
IV. Webware Quality Gates webware-ci.json (MSI 95/95), the console and migration constitutions
V. Naming & Compatibility composer.json PHP constraint, the console and migration constitutions
VI. Asset Serving Contract .github/instructions/memory.instructions.md
VII. Cross-Platform Development Environment compose.yml, plus the host-native toolchain decision taken 2026-10-10
VIII. Reference Repositories Are Read-Only .github/instructions/memory.instructions.md

New relative to console and migration: II (resolver semantics and the 100/50/1 aggregate order), VI (asset path and config key), VII (host-native toolchain), VIII (read-only references). Everything else is the shared fleet set.

What to check

  1. Principle II, the aggregate order. Recorded as theme 100, TemplateMapResolver 50, path stack 1, and ConfigProvider merged after Mezzio\LaminasView\ConfigProvider. Confirm that is the settled contract and not a current accident.
  2. Principle VI, the asset path. Recorded as /theme/<theme>/{css,js,img,fonts} and the key as view_helper_config.asset.resource_map. Confirm the path shape is final.
  3. Principle VII, second paragraph. Records that agents run on the Windows host and tooling scripts must be host-native. Confirm this belongs in the constitution rather than only in the memory file.
  4. Principle VIII. Names ims as read-only. Confirm the scope is that repository and no other.
  5. Version and dates. Set to 1.0.0, ratified 2026-10-10. Adjust if you want to backdate to when the practices actually began.
  6. Anything missing. The console constitution carries a Dependencies section; this one does not. Say if you want one.

The technology stack is deliberately not here

An earlier revision of this branch added a ## Technology Stack section. It has been removed, and the branch rebased so this PR contains nothing but the constitution.

docs/reference/agentic-sdd.md places the stack in the plan: /speckit.specify leaves it out, and /speckit.plan is where the tech stack, architecture and technical constraints are supplied. The constitution is the guiding principles every later phase is evaluated against. composer.json, phpunit.xml.dist, mago.toml and webware-ci.json already hold the stack facts authoritatively, so a second copy in the constitution would only be able to drift.

Constitution files are not manifest-managed, so specify integration upgrade does not touch this file.

@codecov

codecov Bot commented Oct 10, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Replaces the unfilled init template in .specify/memory/constitution.md. The
repository has been running without a ratified constitution, so plan.md for
001-theme-resolution records that there are no project principles to gate
against and substitutes a hand-written gate list.

Content is derived from what the repository already enforces and documents,
not invented to fill the template: the fleet quality gates the console and
migration constitutions share, the resolution semantics recorded in
001-theme-resolution/decisions.md, and the operational rules in
.github/instructions/memory.instructions.md.

Principles: Library-First; Resolution by lookup, encoding the resolver formula,
the aggregate priority order 100/50/1 and the ConfigProvider merge ordering;
Consumer-Agnostic; Webware Quality Gates; Naming and Compatibility; Asset
serving contract, encoding /theme/<theme>/{css,js,img,fonts} and the
view_helper_config.asset.resource_map key; Cross-Platform Development
Environment, including that agents work on the Windows host so tooling scripts
must be host-native; and Reference Repositories Are Read-Only.

The technology stack is deliberately absent. The agentic-sdd command reference
places the stack in the plan, and composer.json, phpunit.xml.dist, mago.toml and
webware-ci.json already hold those facts authoritatively.

Constitution files are not manifest-managed, so specify integration upgrade does
not touch this file.

Signed-off-by: Joey Smith <jsmith@webinertia.net>
@tyrsson
tyrsson force-pushed the docs/ratify-constitution branch 2 times, most recently from cdee92f to c9fa4e9 Compare October 10, 2026 17:41
Signed-off-by: Joey Smith <jsmith@webinertia.net>
Signed-off-by: Joey Smith <jsmith@webinertia.net>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant