Website prose isolation, audit cleanup, schema validator green

.github/workflows/website.yml

@@ -10,7 +10,9 @@ on:
       - 'scripts/publish-artifacts.py'
       - 'scripts/publish-resources.py'
       - 'scripts/check-website-links.py'
+      - 'scripts/helix_validate_artifact_meta.py'
       - 'tests/validate-website-generated.sh'
+      - 'workflows/activities/**/artifacts/**'
       - '.vale.ini'
       - '.vale/**'
       - '.github/workflows/website.yml'
@@ -65,6 +67,9 @@ jobs:
       - name: Generator drift + coverage gate
         run: bash tests/validate-website-generated.sh
 
+      - name: Validate artifact-type schemas
+        run: uv run scripts/helix_validate_artifact_meta.py
+
       - name: Build site (Hugo)
         working-directory: website
         # Build with the production base path so the link check validates the

docs/helix/02-design/adr/ADR-004-dependencies-encoding.md

@@ -0,0 +1,110 @@
+---
+ddx:
+  id: ADR-004
+  depends_on:
+    - helix.prd
+---
+# ADR-004: Artifact Dependencies Are Encoded in `meta.yml.relationships` Only (No Separate `dependencies.yaml`)
+
+| Date | Status | Deciders | Related | Confidence |
+|------|--------|----------|---------|------------|
+| 2026-05-30 | Accepted | HELIX maintainers | artifact-schema, frame action, audit plan 2026-05-30 | High |
+
+## Context
+
+| Aspect | Description |
+|--------|-------------|
+| Problem | The artifact-type rubric historically expected each artifact-type directory to ship a separate `dependencies.yaml` file describing inputs, outputs, and validation rules. In practice, no such file exists for any artifact type, while the same information is already encoded in `meta.yml` under `relationships` (and adjacent `validation.*` sections). The audit (`docs/helix/02-design/plan-2026-05-30-artifact-types-and-concerns-audit.md`) found `dependencies.yaml` absent for 48/48 artifact types. |
+| Current State | `meta.yml.relationships` already names `depends_on` and `informs` per artifact type. `meta.yml.validation` already carries `required_sections`, `quality_checks`, and friends. The phantom `dependencies.yaml` reference survives only in two prose locations: `workflows/actions/frame.md` (validation-gate step) and `workflows/activities/01-frame/README.md` (artifact-directory description). No consumer script actually opens a `dependencies.yaml` file: `scripts/helix_align_check.py` parses the spec stack from markdown (PRD, FEAT, US, ADR) and does not touch `dependencies.yaml`; `workflows/actions/reconcile-alignment.md` references "dependencies" only as a conceptual notion. |
+| Requirements | The catalog must have a single source of truth for artifact-type dependencies. The rubric must stop asking for a file the catalog does not produce. Any consumer that currently mentions `dependencies.yaml` must be repointed at `meta.yml` so the rubric and the workflow agree. |
+
+## Decision
+
+We ratify **`meta.yml.relationships`** as the canonical encoding of artifact-type
+dependencies, and we drop `dependencies.yaml` from the artifact-type rubric.
+There is no second file. There is no generated projection.
+
+- Type-level dependencies (`depends_on`, `informs`, peer relations) live in
+  `meta.yml` under `relationships`. The structured shape is already defined in
+  `workflows/artifact-schema.md` under "Recommended fields".
+- Type-level validation (`required_sections`, `quality_checks`,
+  `pattern_checks`, `automated_checks`) lives in `meta.yml` under `validation`.
+- Instance-level dependencies (one artifact instance depending on another)
+  continue to live in instance frontmatter under `ddx.depends_on`, exactly as
+  `workflows/artifact-schema.md` already specifies. ADR-004 does not change
+  that.
+
+**Key Points**: one source of truth (`meta.yml`) | no `dependencies.yaml`
+generation step | consumer prose realigned to `meta.yml`
+
+## Consumer-side compatibility
+
+We choose **option (a): update consumers to read `meta.yml` directly** over
+option (b): generate a transient `dependencies.yaml` projection at build/check
+time. Rationale:
+
+- `scripts/helix_align_check.py` does not currently read `dependencies.yaml` at
+  all. It parses markdown (`prd.md`, `FEAT-*.md`, `US-*.md`, `ADR-*.md`) and
+  scans the code tree for `@covers` citations. There is no flat dependencies
+  projection to preserve. Option (b) would invent a consumer that does not
+  exist.
+- `workflows/actions/reconcile-alignment.md` likewise does not open a
+  `dependencies.yaml` file. Its references to "dependencies" are conceptual,
+  not file-bound.
+- The only two real `dependencies.yaml` mentions are prose in
+  `workflows/actions/frame.md` (validation-gate step) and
+  `workflows/activities/01-frame/README.md` (artifact-directory description).
+  Both are documentation of *where validation rules live*, not code that opens
+  a file. Repointing the prose at `meta.yml.validation` and
+  `meta.yml.relationships` is a textual edit, no runtime impact.
+- Option (b) would add a build/check step, a generated file, and a drift
+  surface (projection out of sync with `meta.yml`) for no consumer benefit.
+  That is the opposite of the audit's goal.
+
+If a future consumer ever needs a flat dependencies graph, it can either parse
+`meta.yml` directly or compose a projection at read time. That decision belongs
+to that consumer, not to the catalog.
+
+## Alternatives
+
+| Option | Pros | Cons | Evaluation |
+|--------|------|------|------------|
+| Generate `dependencies.yaml` per artifact type from `meta.yml` as a build step | Preserves the historical rubric shape | Adds a generated file, a drift surface, and a build/check step with no consumer that needs it | Rejected: no consumer reads the file; cost without benefit |
+| Hand-author both `dependencies.yaml` and `meta.yml.relationships` | Matches the historical rubric literally | Two sources of truth; 48 missing files; encodes the same data twice; drift inevitable | Rejected: contradicts single-source goal |
+| **Ratify `meta.yml.relationships` as canonical and drop `dependencies.yaml` from the rubric** | One source of truth; matches what the catalog actually ships; no generation step; rubric stops lying about expected files | Existing prose in `frame.md` and `01-frame/README.md` must be updated in the same change | **Selected: smallest sufficient alignment** |
+
+## Consequences
+
+| Type | Impact |
+|------|--------|
+| Positive | Catalog has one place to look for artifact-type dependencies and one place to look for validation rules: `meta.yml`. |
+| Positive | The rubric stops asking for a file that does not exist; the 48/48 absence reported by the audit is no longer a violation. |
+| Positive | Workflow prose (`workflows/actions/frame.md`, `workflows/activities/01-frame/README.md`) is repointed at the file that actually carries validation rules, removing a documentation-to-reality gap. |
+| Positive | No generated projection means no projection-drift class of failure to defend against. |
+| Negative | The rubric line in `workflows/artifact-schema.md` ("Recommended fields") and the prose in `workflows/actions/frame.md` / `workflows/activities/01-frame/README.md` must be updated in lockstep with this ADR; any future doc that re-introduces `dependencies.yaml` must be rejected as drift. |
+| Neutral | Instance-level dependencies in `ddx.depends_on` frontmatter are unaffected; this ADR is about type-level rubric, not instance-level graph. |
+
+## Risks
+
+| Risk | Prob | Impact | Mitigation |
+|------|------|--------|------------|
+| A future workflow re-introduces `dependencies.yaml` by force of habit | M | L | Audit gate: a grep for `dependencies.yaml` outside ADR-004 itself should return zero hits after this change |
+| A future consumer wants a flat dependencies projection and reinvents it ad hoc | L | M | Consumers may compose a projection from `meta.yml` at read time; no canonical file required |
+| The audit's "48/48 absent" finding gets re-reported because the rubric is read out of date | L | L | Update the rubric prose in the same commit as this ADR so the next audit sees the canonical shape |
+
+## Validation
+
+| Success Metric | Review Trigger |
+|----------------|----------------|
+| Grep for `dependencies.yaml` outside ADR-004 returns zero hits in `workflows/` and `scripts/` | A workflow doc or script re-introduces `dependencies.yaml` |
+| `workflows/actions/frame.md` validation-gate step references `meta.yml.validation` (not `dependencies.yaml`) | A reviewer cannot tell where validation rules live for an artifact type |
+| `workflows/activities/01-frame/README.md` artifact-directory description does not list `dependencies.yaml` | A new artifact type ships a `dependencies.yaml` instead of `meta.yml` updates |
+| `workflows/artifact-schema.md` "Recommended fields" no longer implies a separate dependencies file | A consumer ships code that opens `dependencies.yaml` |
+
+## References
+
+- [Audit plan 2026-05-30](../plan-2026-05-30-artifact-types-and-concerns-audit.md)
+- [PRD](../../01-frame/prd.md)
+- [Artifact schema](../../../../workflows/artifact-schema.md)
+- ADR-002: HELIX Tracker Write Safety Model
+- ADR-003: Autonomy Spectrum

docs/helix/02-design/adr/ADR-005-concern-practices-activity-keyed.md

@@ -0,0 +1,80 @@
+---
+ddx:
+  id: ADR-005
+  depends_on:
+    - helix.prd
+---
+# ADR-005: Concern practices.md is HELIX-activity-keyed
+
+| Date | Status | Deciders | Related | Confidence |
+|------|--------|----------|---------|------------|
+| 2026-05-30 | Accepted | HELIX maintainers | concerns library, context-digest assembly | High |
+
+## Context
+
+| Aspect | Description |
+|--------|-------------|
+| Problem | Concern `practices.md` files use two incompatible organizing principles. Some are keyed by HELIX activity (Discover / Frame / Design / Test / Build / Deploy / Iterate), so per-activity context-digest assembly is a mechanical lookup. Others are keyed by topic (Implementation / Quality Gates / etc.), forcing the context assembler to guess which heading belongs to which activity. |
+| Current State | Ten concerns are topic-keyed: `auth-local-sessions`, `caching-strategy`, `classic-layered`, `cqrs`, `domain-driven-design`, `enterprise-application-patterns`, `hexagonal-architecture`, `mcp-server`, `onion-architecture`, `sample-data`. The remaining concerns already organize practices by HELIX activity. |
+| Requirements | Per-activity context-digest assembly must be a deterministic lookup, not a heuristic. The concerns library must use one consistent organizing principle so that any consumer — context assembler, alignment review, methodology docs — extracts the practices for a given activity by reading the corresponding heading. |
+
+## Decision
+
+Every concern's `practices.md` organizes its per-activity content under HELIX
+activity headings: **Discover**, **Frame**, **Design**, **Test**, **Build**,
+**Deploy**, **Iterate**. Topic-keyed or quality-gates-keyed organization is no
+longer acceptable for `practices.md`.
+
+Activity-keying makes per-activity context-digest assembly a mechanical lookup:
+the assembler reads the heading whose name matches the current activity and
+pulls the bullets underneath. No guessing, no mapping table, no per-concern
+schema.
+
+The ten topic-keyed concerns named above convert to activity-keying in Phase 3
+of the artifact-types-and-concerns audit. New concerns ship activity-keyed from
+day one.
+
+**Key Points**: HELIX activity headings are the only acceptable top-level
+structure in `practices.md` | mechanical per-activity lookup | ten existing
+topic-keyed concerns convert in Phase 3
+
+## Alternatives
+
+| Option | Pros | Cons | Evaluation |
+|--------|------|------|------------|
+| Keep both styles (activity-keyed and topic-keyed) | No conversion work | Context-digest assembly must implement per-concern mapping logic and stay in sync as concerns evolve | Rejected: pushes guesswork into every consumer |
+| Topic-keyed everywhere (Implementation / Quality Gates / ...) | Matches a few existing concerns | Forces the assembler to guess which topic applies to which activity; topics differ by concern | Rejected: not mechanically extractable |
+| Add a frontmatter mapping table from topic → activity in each `practices.md` | Preserves topic prose | Introduces a per-concern schema to maintain; the heading and the mapping can drift | Rejected: heading is already the natural index |
+| **Activity-keyed everywhere; convert the ten topic-keyed concerns in Phase 3** | One consistent structure; mechanical lookup; matches the majority of existing concerns | Requires per-concern restructuring for ten concerns | **Selected: smallest sufficient unification** |
+
+## Consequences
+
+| Type | Impact |
+|------|--------|
+| Positive | Per-activity context-digest assembly becomes a mechanical heading lookup across every concern. |
+| Positive | Downstream consumers (alignment review, methodology docs, the website mirror) get a uniform structure to render and reason about. |
+| Positive | New concerns have one obvious shape to follow; no per-concern bikeshed about structure. |
+| Negative | The ten topic-keyed concerns require restructuring; some topic prose (e.g. cross-cutting Quality Gates) has to be reseated under the activity it applies to. |
+| Neutral | The bullet content of each concern is preserved; only the organizing headings change. |
+
+## Risks
+
+| Risk | Prob | Impact | Mitigation |
+|------|------|--------|------------|
+| Conversion silently drops practice content during restructuring | M | M | Phase 3 conversion reviews the diff per concern; bullets must land under exactly one activity heading |
+| Cross-cutting content (e.g. Quality Gates) has no natural single activity home | M | M | Allow the same bullet to appear under more than one activity heading when it genuinely applies across activities; prefer the closest activity otherwise |
+| New concerns drift back to topic-keying | L | M | Lint or review check rejects `practices.md` whose top-level headings are not from the HELIX activity vocabulary |
+
+## Validation
+
+| Success Metric | Review Trigger |
+|----------------|----------------|
+| Every `practices.md` uses HELIX activity headings as its top-level structure | A `practices.md` lands or merges with topic-keyed headings |
+| The ten named concerns are converted in Phase 3 with no lost content | Phase 3 closes with any of the ten still topic-keyed |
+| Context-digest assembly extracts per-activity practices by heading lookup, with no per-concern mapping | The assembler grows per-concern conditional logic |
+
+## References
+
+- [PRD](../../01-frame/prd.md)
+- Phase 1A plan: `docs/helix/02-design/plan-2026-05-30-artifact-types-and-concerns-audit.md`
+- Concerns library: `workflows/concerns/`