Website prose isolation, audit cleanup, schema validator green#20
Merged
Conversation
meta.validation.required_sections listed security_user_stories, risk_assessment, and acceptance_criteria, none of which exist as H2s in template.md. Replace with required_controls and security_risks (which match template H2s) and keep compliance_requirements. The template is authoritative for content. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
meta.validation.required_sections listed objective/scope/approach/ implementation/testing/findings/conclusions/artifacts, but template.md H2s are Objective/Approach/Implementation/Results/Analysis/ Recommendations. scope/findings were template H3s under other H2s; the artifacts H2 was missing entirely though referenced by output.artifacts_location. Aligned meta to template-side terminology (results/analysis instead of testing/findings/conclusions; dropped scope as it lives under Objective) and added an Artifacts H2 to template.md to match the meta requirement and the artifacts_location output contract. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The template.md includes an Analysis H2 (between Findings and Conclusions) that the example.md also uses, but meta.yml's validation.required_sections omitted "analysis". Added analysis to required_sections so the validator's snake-cased H2 ID list matches the template's actual H2s, preserving example fidelity rather than removing the Analysis section from the template. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The meta.validation.required_sections list referenced eight per-dimension sections (technical_feasibility, business_feasibility, ...) that never existed in template.md; the template groups them under a single Feasibility Assessment H2 with H3 subsections. The example.md also had a Decision Framework H2 that the template lacked. Add the Decision Framework H2 to template.md (matching example.md) and rewrite required_sections to the H2s actually present in the template: executive_summary, feasibility_assessment, risks, alternatives, decision_framework, next_steps. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reconcile validator drift in workflows/activities/01-frame/artifacts/data-prd without restructuring the artifact (Phase 2 PRD/data-PRD ADR may collapse it): - required_sections: replace problem_statement + goals_and_objectives (H3s, not H2s) with their parent H2 problem_and_goals; rename databricks_context to databricks_specific_technical_context to match the actual H2 text; reorder data_consumers before data_sources to match template order. - references: align two Databricks resource filenames to the ones the prompt already cites (databricks-lakehouse-medallion-architecture.md and databricks-sdp.md), so meta and prompt point at the same files. Generated website mirror (docs/website/content/artifact-types/frame/data-prd.md) does not surface required_sections or the references list, so the generate-reference.py run produced no mirror changes to stage. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The relationships.informs edge pointed to a `communication-plan` artifact that does not exist in any phase. Communication strategy is already covered in stakeholder-map's own required `communication_plan` section and `communication_matrix` template include, so no replacement edge is needed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
data-prd and data-architecture referenced the Databricks medallion resource doc under two different filenames (databricks-lakehouse-medallion-architecture.md vs databricks-medallion-architecture.md). Canonicalize on the longer name, which already appears 3x across both artifacts' meta/prompt files and matches the Databricks documentation terminology, by updating data-architecture meta.yml's outlier reference. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Delete three orphan Go-only test templates that were not referenced from their artifact meta.yml files: - security-tests/security-test.go.template - test-suites/unit-test.go.template - test-suites/integration-test.go.template HELIX artifact types are runtime-neutral; the "Security Tests" and "Test Suites" artifacts already ship language-agnostic template.md files. The Go-flavored .go.template files (package, testing.T, github.com/stretchr/testify) were misleading language-biased fixtures in generic artifact directories, with no entry in meta.yml or any generator picking them up. Deleting rather than wiring keeps the artifact contract neutral. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…e H2s) Adds scripts/helix_validate_artifact_meta.py, a stdlib-only checker that walks workflows/activities/<phase>/artifacts/<slug>/, reads validation.required_sections from meta.yml, extracts H2 headings from template.md, and asserts each declared section ID matches a slugified H2. Wired into CI via .github/workflows/website.yml (new "Validate artifact-type schemas" step alongside the generator drift gate) and into local dev via the justfile recipe `validate-artifact-schemas`. The CI trigger paths also gain workflows/activities/**/artifacts/** and the new script so drift is caught on artifact edits. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Accepts that concerns include an `ADR References` header only when they actually cite one or more ADRs. Phase 3 mechanical edits remove the empty headers from the 14 concerns that currently ship them. The schema validator keeps the section optional; presence is driven by content, not template shape. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 1A ADR. Every concern's practices.md organizes per-activity content under HELIX activity headings (Discover / Frame / Design / Test / Build / Deploy / Iterate). Topic-keyed organization is no longer acceptable. Ten currently topic-keyed concerns convert in Phase 3 of the artifact-types- and-concerns audit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Codify the catalog contract Phase 1A decision: every concern's boundary lives canonically in concern.md and only there. practices.md's "Boundary with neighbors" section is removed; Constraints / Drift Signals / Quality Gates reference-not-restate the canonical boundary. Restatement becomes a drift signal the schema validator can flag. Fold the dropped concision phase's editorial rules into the same ADR: meta.yml is machine-validation + relationships only; prompt Quality Checklist and template Review Checklist are not both present; tutorial- grade code blocks move to resource docs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Ratify meta.yml.relationships as the single source of truth for artifact-type dependencies and drop the rubric's expectation of a separate dependencies.yaml file. All 48 artifact types already encode the data this way; no consumer script actually opens a dependencies.yaml file. Consumer updates (option a — read meta.yml directly): - scripts/generate-reference.py drops the always-empty load_yaml(dependencies.yaml) call and the deps-then-meta fallback chain in get_artifact_name / get_artifact_description / get_relationships / get_output_location. - workflows/actions/frame.md validation-gate step now points at meta.yml.validation.quality_checks (was: dependencies.yaml). - workflows/activities/01-frame/README.md artifact-directory description now names meta.yml (was: dependencies.yaml). Regenerated docs/website/content/artifacts/ mirror via publish-artifacts.py; generate-reference.py produced no changes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
react-nextjs references ux-radix for UI primitives instead of re-prescribing shadcn directly. Aligns ownership with the interaction-primitives concern and removes the double-prescription that confuses the framework/component-library boundary. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…tection only Records the Phase 2 decision that resolves the ownership collision flagged by the 2026-05-30 artifact-types-and-concerns audit. monitoring-setup is scoped to detection (SLI/SLO definitions, alert routing inputs, threshold tuning); runbook owns incident response (procedures, recovery, escalation). Phase 3 will remove the Incident Response section from monitoring-setup's template and migrate any uncovered content into runbook. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Accept that an artifact may declare informs an artifact in a later phase (e.g., Deploy monitoring-setup informs Iterate metrics-dashboard) when the edge encodes a real evidence flow and is declared on both ends. Symmetry enforcement is filed as a follow-up Phase 1B validator concern. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…/decomposition Phase 2 ADR for the artifact-types-and-concerns audit. Makes the FR -> story -> AC decomposition boundary load-bearing: AC-IDs live only in user-stories; feature-specification owns FR-IDs, functional areas, and the decomposition test. Sets up Phase 3 to remove AC restatement from feature-specification and trim the five-way duplication in user-stories meta to a single canonical rule. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…tection only Records the Phase 2 decision that resolves the ownership collision flagged by the 2026-05-30 artifact-types-and-concerns audit. monitoring-setup is scoped to detection (SLI/SLO definitions, alert routing inputs, threshold tuning); runbook owns incident response (procedures, recovery, escalation). Phase 3 will remove the Incident Response section from monitoring-setup's template and migrate any uncovered content into runbook. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Compliance owns regs->controls, security-requirements owns testable control acceptance criteria, threat-model owns STRIDE + mitigation owners. Each prompt now includes a Traceability chain callout naming its scope and cross-referencing the other two artifacts; bullets that crossed boundaries (e.g. threat enumeration in compliance, control authoring in threat-model) are removed in favor of cross-references. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replace "what this artifact is vs the others" preambles in test-plan, story-test-plan, test-suites, and test-procedures prompts with a one-line scope sentence and a Related list cross-referencing the other three. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…R-012) Per ADR-012, remove the Incident Response section from the monitoring-setup template/example/meta and replace it with an Alert Routing section (alert routing inputs are detection-side). Response procedures, escalation, and recovery are already covered by the runbook template (Common Incident Procedures, Escalation and Communications, Rollback and Recovery), so no edits to the runbook are needed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…atement Add a "What belongs at each level" matrix to the 02-design README mapping decision type to owning artifact across Architecture (system), Solution Design (feature), and Technical Design (story). Replace per-prompt restatements of other levels' scope with a one-line cross-reference to the matrix, so the boundary lives in one place. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…rences (ADR-011) Per ADR-011, the ux-radix concern is the canonical owner of the Radix primitives and shadcn/ui component-library prescription. Tighten ux-radix (concern.md + practices.md) to assert that ownership explicitly, and remove the shadcn/Radix prescription from react-nextjs (concern.md + practices.md), replacing it with a cross-reference to ux-radix for UI primitives. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Regenerate website mirrors for feature-registry and parking-lot prompts after adding the ADR-010 promotion procedure. The source prompt.md edits landed in 61cc709 alongside another agent's commit; this catches the mirrors so the drift gate stays green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…wnership (ADR-009) Per ADR-009 (acceptance criteria ownership), feature-specification stops claiming AC ownership and user-stories trims its 5-way AC-ID restatement down to one canonical statement (prompt) plus a single template review checklist entry. feature-specification: - prompt.md: drop AC section guidance, AC quality-check items, the "concrete acceptance examples" Key Principle, and AC framing from Purpose / opening; Boundary Test now routes AC to User Story. - template.md: remove Acceptance Criteria subsection; review checklist notes AC lives in the decomposing stories (ADR-009). - meta.yml: drop acceptance_criteria from required_sections; drop the acceptance_criteria_observable quality_check; description notes AC lives in user-stories. user-stories: - prompt.md: drop the blocking checklist AC-ID restatement (kept the canonical statement in the Acceptance Criteria section). - template.md: trim Acceptance Criteria section body to defer to the prompt's canonical guidance; review checklist keeps the single entry. - meta.yml: drop the criteria_have_stable_ids quality_check and the US-<n>-AC<m> automated_check (both duplicated the prose rule). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Narrow the two design-phase data artifacts per plan-2026-05-30: - data-architecture: trim ~340 line template to the platform/pipeline scope (medallion topology, processing framework, governance model, pipeline-level quality contracts). Drop hardcoded numeric examples ($/GB, DBU counts, instance types) that read as filler. - Move the Databricks Platform Substitution table out of the generation prompt into docs/resources/databricks-platform-substitution.md so the prompt cites the resource by reference. - data-design: keep at entity level (logical model, stores, access patterns, constraints, migration) and add explicit cross-references to data-architecture for platform decisions and to data-quality-expectations for field-level contracts. Regenerates the artifact-type mirrors for both. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per ADR-007, concerns with no referenced ADRs should not ship an empty "## ADR References" section header. Removed the empty header from the 14 affected concerns: a11y-wcag-aa, demo-asciinema, demo-playwright, design-patterns-gof, e2e-kind, e2e-playwright, go-std, hugo-hextra, i18n-icu, k8s-kind, o11y-otel, python-uv, rust-cargo, scala-sbt. Regenerated the docs/website mirrors. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per ADR-008, the data-prd artifact type collapses into the prd artifact via a `kind` enum (`product` default, `data` variant). The shape of the artifact is unified; the framing is parameterized. - prd/meta.yml: declare `kind` field with `product`/`data` enum, default `product`; extend description to cover both framings - prd/prompt.md: add Variant Selection section explaining `kind`; add `(kind: data)` addendums to Purpose, Reference Anchors, Personas (becomes Data Consumers + Data Sources), Success Metrics, Functional Requirements (adds Data Quality Requirements), and Technical Context (becomes Data Platform Context) - prd/template.md: add `kind: product` to frontmatter; add Variant Guidance block; add `(kind: data)` blocks to Summary, Problem, Users and Scope (Data Consumers + Data Sources), Success Metrics, Requirements (Data Quality Requirements), and Technical Context (Data Platform Context) - data-architecture / data-quality-expectations: redirect `informed_by`, template references, prompt references, and meta validation text from `data-prd` to `prd` (kind: data); drop orphaned `example.data-prd.*` example depends_on with inline note pointing to ADR-008 - regenerate docs/website/content/artifact-types/ mirrors (data-prd page disappears from /artifact-types/frame/) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…statement Add workflows/concerns/README-auth-family.md with the explicit ownership table for the five-way cluster (auth, authorization-model, multi-tenancy, security-owasp) and the two material neighbors (admin-console references auth for operator-workflow gates; unity-catalog references authorization-model for catalog grants composing with app-layer authz). Per ADR-006 (concern boundary lives once, in concern.md), trim the restated per-concern boundary prose in the five family concerns and the two neighbors. Remove "Boundary with neighbors" H2 sections from practices.md (authorization-model, multi-tenancy, unity-catalog) and replace neighbour-restatement bullets in concern.md with a cross-reference to the family README. Fold ambiguous-item ownership into the README (session-token semantics -> auth; audit-logging policy on authz denial -> security-owasp). Add the previously-missing Boundary section to security-owasp/concern.md naming the hardening posture + audit-logging policy it owns. Regenerate website concern mirrors. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… (ADR-005) Per ADR-005, practices.md uses HELIX activity headings as its top-level structure: Discover / Frame / Design / Test / Build / Deploy / Iterate. This restructures the ten remaining topic-keyed concerns (auth-local-sessions, caching-strategy, classic-layered, cqrs, domain-driven-design, enterprise-application-patterns, hexagonal-architecture, mcp-server, onion-architecture, sample-data) without dropping content. Topic prose moves under the activity it applies to; the "Boundary with neighbors" topic sits in a "Cross-cutting" subsection at the bottom of each file. Mirrors under docs/website/content/concerns/ regenerated via scripts/generate-reference.py. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Apply ADR-006 (Boundary lives once in concern.md) to the smaller clusters: testing/verification, e2e-playwright/demo-playwright, concurrency-model/ resilience, caching-strategy/resilience, o11y-otel/resilience/verification, enterprise-integration-patterns/event-sourcing/cqrs, the Databricks family (apps/declarative-pipelines/unity-catalog), and deployment-topology/ k8s-kind/twelve-factor. Each practices.md "Boundary with neighbors" section is trimmed to a cross-link pointing at the canonical Boundary in concern.md; e2e-playwright drops demo-reel content (delegated to demo-playwright); the EIP/event-sourcing/cqrs idempotency restatement is collapsed onto EIP's at-least-once channel-delivery rule; k8s-kind gains a Boundary block documenting it as a deployment-topology runtime implementation. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pick up new ADRs (007-013), auth-family README, and concern README changes from the artifact-types-and-concerns audit workflow. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Link-check gate caught two issues from the artifact-types audit work: 1. README-auth-family.md (the auth-family ownership table) is referenced from seven concern pages via ../README-auth-family.md, but the workflows/concerns -> docs/website/content/concerns mirror flattens per-concern dirs (concern.md becomes <slug>.md), so the relative link resolved to a missing file. Teach generate-reference.py to publish family READMEs alongside concerns and rewrite source links to the Hugo URL (../readme-<family>/). 2. ADR-004 had three absolute /Users/... paths in References. Replaced with relative paths. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
generate-reference.py now publishes workflows/concerns/README-*.md files alongside concern pages so cross-concern links to family ownership tables resolve. The coverage count in validate-website-generated.sh treats every .md under content/concerns/ as a concern, so it spuriously failed (49 sources vs 50 rendered). Exclude README-* explicitly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Brings scripts/helix_validate_artifact_meta.py to green across 47
artifact types.
Renames — required_section now matches the H2 already in template.md:
- opportunity-canvas: go_nogo_checklist -> go_no_go_decision
- product-vision: value_propositions -> key_value_propositions
- compliance-requirements: drop regulatory_landscape_analysis;
data_classification -> data_classification_and_handling
- threat-model: stride_analysis -> stride_threat_analysis
- architecture: system_context/container_diagram ->
level_1_system_context/level_2_container_diagram
- data-architecture: quality_contracts/governance_and_access/
databricks_platform_design -> pipeline_level_quality_contracts/
governance_and_access_control/platform_design
- story-test-plan: acceptance_criteria_mapping ->
acceptance_criteria_test_mapping
- deployment-checklist: go_no_go -> go_or_no_go_decision
Drops — H3-level entries the validator (H2-only) cannot see; prompt
and template still enforce H3 substructure:
- pr-faq: 14 H3 subsections -> the 4 H2 anchors
- feature-specification: FR/NFR H3s -> Requirements H2
- research-plan: drop knowledge_gaps/resource_requirements/
expected_outcomes; rename success_criteria/risk_assessment to
completion_criteria/research_risks
- stakeholder-map: drop stakeholder_identification/engagement_strategy/
escalation_path
- test-plan: test_levels/critical_paths -> testing_strategy/
acceptance_criteria_layer_allocation
- metrics-dashboard: drop review_window
Validator: skip artifacts where output.format != markdown
(metric-definition is YAML; its schema lives in YAML keys).
Q1 — technical-design stops echoing AC (ADR-009):
- Remove ## Acceptance Criteria H2 from template + example
- Drop story_reference/acceptance_criteria_review/definition_of_done;
rename testing_approach -> testing
- Quality check is now acceptance_criteria_realized (AC-IDs, no text)
- Automated check requires US-{n}-AC{m} references
- Example illustrates the pattern in the Testing section
Gates: validator OK (47/47), lint-prose 0/0/0, generator drift OK,
link check 73,351/73,351, redundancy OK.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…chy rename The earlier rename "Authority Order" -> "Artifact Authority Hierarchy" left two e2e expectations stale. Update them to match the current headings: - /why/principles/ principle #3 is now "The artifact authority hierarchy governs reconciliation". - /reference/glossary/concepts/ uses "Artifact Authority Hierarchy". 49/49 Playwright tests now pass. Co-Authored-By: Claude Opus 4.7 (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
Three threads that landed together on this branch over the last few days:
Website content isolation + prose linting. Hand-authored narrative moved to
docs/website/content/(Hugo mounts it fromwebsite/), backed by aHelixVale style (AISlop / EmDash / Tics / Wordiness / Hedges / PassiveVoice / SentenceLength) wired into a CI gate viajust lint-prose. 89 warnings → 0 across 284 files (50 fixes + 36 reviewed false-positive suppressions). New cross-file paragraph redundancy script (scripts/check-prose-redundancy.py) covers what token-level Vale can't.Artifact-types + concerns audit (Phase 1-3 remediation). Worked through ADR-004 through ADR-014 plus mechanical phase-3 edits. Highlights:
meta.relationshipsis the canonical dependency encoding.concern.md(per-concern restatement trimmed).## ADR Referencesheaders dropped.data-prdcollapsed intoprdas akind: datavariant.user-stories;feature-specificationandtechnical-designstop echoing AC text.parking-lot→feature-registryhandoff documented.ux-radixowns the shadcn/Radix prescription.runbookowns incident response;monitoring-setupis detection-only.informsedges are valid when declared.architecture-styleslot shape deferred (separate audit).Artifact-type schema validator goes green. New
scripts/helix_validate_artifact_meta.pychecksmeta.yml validation.required_sectionsagainsttemplate.mdH2s for all 47 artifact types, wired intojust validate-artifact-schemasand the CI workflow. Initial pass surfaced 51 drifts; landed in this branch's final commit:required_sectionswhere the validator (H2-only) can't see them; prompt + template still enforce the H3 substructure (pr-faq 14, feature-spec FR/NFR, research-plan, stakeholder-map, test-plan, metrics-dashboard)output.format != markdownartifacts (metric-definition is YAML)technical-designdrops the## Acceptance Criteriaecho per ADR-009 (template + example + meta + prompt updated; new pattern check requiresUS-{n}-AC{m}references)Term rename "authority order" → "authority hierarchy" across 109+ occurrences also landed earlier on this branch; legacy
#authority-orderanchor preserved for back-compat.Gates (all green locally)
just lint-prose— 0/0/0 across 284 filesjust validate-artifact-schemas— 47/47 artifact typesjust check-prose-redundancy— no paragraph pairs ≥ 0.25 similarityjust test-website-generated— 49 concerns, 47 artifact typesjust check-website-links— 73,351 internal links/images across 352 pagescd website && CI=1 npx playwright test— 49/49 passingdocs/demos/<slug>/session.jsonlPre-existing failures (NOT introduced here)
just test-context-digests— fails onmaintoo (beadhelix-e3c7d0e4lacks a context-digest, ddx hygiene)just test-demo-fixtures— fails onmaintoo (docs/demos/helix-concerns/demo.shremoved in9e7f734dbut test script not updated)Test plan
just-level website checks pass locally