diff --git a/.github/workflows/community-smoke.yml b/.github/workflows/community-smoke.yml index a50296c44f..b5b2f367bf 100644 --- a/.github/workflows/community-smoke.yml +++ b/.github/workflows/community-smoke.yml @@ -99,6 +99,8 @@ jobs: speckit-arch-process-generate \ speckit-arch-development-generate \ speckit-arch-physical-generate \ + speckit-arch-full-generate \ + speckit-arch-full-reverse \ speckit-arch-scenario-reverse \ speckit-arch-logical-reverse \ speckit-arch-process-reverse \ @@ -171,6 +173,8 @@ jobs: case "$extension_id" in arch) test -f .claude/skills/speckit-arch-scenario-generate/SKILL.md + test -f .claude/skills/speckit-arch-full-generate/SKILL.md + test -f .claude/skills/speckit-arch-full-reverse/SKILL.md test -f .claude/skills/speckit-arch-scenario-reverse/SKILL.md grep -q "scenario view" .claude/skills/speckit-arch-scenario-generate/SKILL.md ;; diff --git a/CHANGELOG.md b/CHANGELOG.md index f0f5409afd..672f51c0bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ ### Changed +- Update Architecture Workflow extension to v1.2.2 with full-workflow commands and readiness validators. - Update bundled Repository Governance extension to v2.0.2, including the `/speckit.repository-governance.refresh` command, `.specify/memory/repository-governance.md` internal cache, and default bundled installation behavior. - Update bundled Workflow Preset documentation for v1.3.2 Final Code Review task generation and structured code review receipts. diff --git a/docs/community/extensions.md b/docs/community/extensions.md index bf59e59e86..cb832a3ac5 100644 --- a/docs/community/extensions.md +++ b/docs/community/extensions.md @@ -30,7 +30,7 @@ The following community-contributed extensions are available in [`catalog.commun | API Evolve | Managed API contract evolution — breaking-change detection, semver enforcement, deprecation orchestration, and lifecycle gates across REST, GraphQL, and gRPC | `process` | Read+Write | [spec-kit-api-evolve](https://github.com/Quratulain-bilal/spec-kit-api-evolve) | | Architect Impact Previewer | Predicts architectural impact, complexity, and risks of proposed changes before implementation. | `visibility` | Read-only | [spec-kit-architect-preview](https://github.com/UmmeHabiba1312/spec-kit-architect-preview) | | Architecture Guard | Framework-agnostic architecture review extension for validating implementation against governance and architecture constitutions, detecting architectural drift, and generating non-blocking refactor tasks | `process` | Read+Write | [spec-kit-architecture-guard](https://github.com/DyanGalih/spec-kit-architecture-guard) | -| Architecture Workflow | Generate or reverse project-level 4+1 architecture views as separate commands | `docs` | Read+Write | [spec-kit-arch](https://github.com/bigsmartben/spec-kit-arch) | +| Architecture Workflow | Generate or reverse project-level 4+1 architecture views with per-view and full-workflow commands | `docs` | Read+Write | [spec-kit-arch](https://github.com/bigsmartben/spec-kit-arch) | | Archive Extension | Archive merged features into main project memory. | `docs` | Read+Write | [spec-kit-archive](https://github.com/stn1slv/spec-kit-archive) | | Azure DevOps Integration | Sync user stories and tasks to Azure DevOps work items using OAuth authentication | `integration` | Read+Write | [spec-kit-azure-devops](https://github.com/pragya247/spec-kit-azure-devops) | | Blueprint | Stay code-literate in AI-driven development: review a complete code blueprint for every task from spec artifacts before /speckit.implement runs | `docs` | Read+Write | [spec-kit-blueprint](https://github.com/chordpli/spec-kit-blueprint) | diff --git a/extensions/arch/.extensionignore b/extensions/arch/.extensionignore index 7f9a8828f4..deb9c9e365 100644 --- a/extensions/arch/.extensionignore +++ b/extensions/arch/.extensionignore @@ -6,4 +6,3 @@ __pycache__/ *.py[cod] tests/ CATALOG-SUBMISSION.md -presets/ diff --git a/extensions/arch/AGENTS.md b/extensions/arch/AGENTS.md index b059ed99a1..e0ca82c58b 100644 --- a/extensions/arch/AGENTS.md +++ b/extensions/arch/AGENTS.md @@ -10,11 +10,10 @@ This repository is a Spec Kit community extension source project for `arch`. - `schemas/` contains architecture artifact schemas. - `scripts/` contains setup helpers. - `tests/repository-first-contract.sh` is the main contract test. -- `presets/arch-governance/` is a nested source preset owned by this repository. ## Source Workflow -- Develop extension and nested preset source changes in this repository. +- Develop extension source changes in this repository. - Release versioned source artifacts from this repository. - Keep `README.md`, `CHANGELOG.md`, `CATALOG-SUBMISSION.md`, manifests, and tests aligned. - Run `bash tests/repository-first-contract.sh` after behavior, command, template, schema, or setup-script changes. diff --git a/extensions/arch/CATALOG-SUBMISSION.md b/extensions/arch/CATALOG-SUBMISSION.md index 8674f141ba..51538d0ea3 100644 --- a/extensions/arch/CATALOG-SUBMISSION.md +++ b/extensions/arch/CATALOG-SUBMISSION.md @@ -2,29 +2,32 @@ Extension ID: arch Name: Architecture Workflow -Version: 1.2.1 -Description: Generate or reverse project-level 4+1 architecture views as separate commands +Version: 1.2.2 +Description: Generate or reverse project-level 4+1 architecture views with per-view and full-workflow commands Author: bigsmartben Repository URL: https://github.com/bigsmartben/spec-kit-arch -Download URL: https://github.com/bigsmartben/spec-kit-arch/archive/refs/tags/v1.2.1.zip +Download URL: https://github.com/bigsmartben/spec-kit-arch/archive/refs/tags/v1.2.2.zip Documentation URL: https://github.com/bigsmartben/spec-kit-arch#readme License: MIT Required Spec Kit version: >=0.8.10.dev0 -Commands count: 10 +Commands count: 12 Hooks count: 0 Tags: architecture, 4plus1, workflow, design Key features: - Provides `.arch` namespaced commands for each 4+1 view: scenario, logical, process, development, and physical. +- Provides `/speckit.arch.full-generate` for one-command forward generation of all 4+1 views and synthesis. +- Provides `/speckit.arch.full-reverse` for one-command reverse generation of repo facts, all 4+1 views, and synthesis. - Provides separate forward-generation and reverse-generation commands for every view. - Records reverse workflow evidence in `.specify/memory/architecture-repo-facts.md`. -- Consumes optional repository-first dependency matrices and module invocation specs as reverse workflow evidence. +- Uses optional repository-first evidence in the reverse workflow, with dependency matrix interpretation owned by the development view rather than consumed evenly by every 4+1 view. +- Requires the Development View commands to produce a `Dependency Matrix` section in the development-view artifact. - Allows teams to update one architecture view at a time while preserving the cross-view synthesis boundary. - Defines synthesis readiness, repo-facts merge behavior, and source traceability expectations for repeatable command runs. -- Ships a schema-backed artifact contract for structured validation before Markdown rendering. +- Ships a schema-backed artifact contract plus bash and PowerShell readiness validators that emit `ready_gate` and stable blocker codes. - Restricts writes to documented `.specify/memory/architecture*.md` files, including repo facts for reverse generation. Testing performed: - Local development install with `specify extension add --dev /home/administrator/github/spec-kit-arch`. - Bash setup helper verified with `.specify/extensions/arch/scripts/bash/setup-arch.sh --json`. -- Release ZIP install to verify after publishing `v1.2.1`: `specify extension add arch --from https://github.com/bigsmartben/spec-kit-arch/archive/refs/tags/v1.2.1.zip`. +- Release ZIP install to verify after publishing `v1.2.2`: `specify extension add arch --from https://github.com/bigsmartben/spec-kit-arch/archive/refs/tags/v1.2.2.zip`. diff --git a/extensions/arch/CHANGELOG.md b/extensions/arch/CHANGELOG.md index 6837633cff..ecb897fa50 100644 --- a/extensions/arch/CHANGELOG.md +++ b/extensions/arch/CHANGELOG.md @@ -2,16 +2,21 @@ ## Unreleased +## v1.2.2 - 2026-06-25 + - Use CLI-compatible command names such as `/speckit.arch.scenario-generate` and `/speckit.arch.scenario-reverse`. +- Add `/speckit.arch.full-generate` for one-command forward generation of all 4+1 views and synthesis. +- Add `/speckit.arch.full-reverse` for one-command reverse generation of repo facts, all 4+1 views, and synthesis. - Clarify command bootstrap boundaries, synthesis readiness checks, reverse repo-facts merge behavior, and source traceability expectations. - Replace the two broad architecture commands with ten `.arch`-namespaced commands: forward and reverse generation for scenario, logical, process, development, and physical views. - Keep synthesis refresh optional for per-view commands so each command owns one primary 4+1 artifact. - Add reverse commands for repo-facts-first generation of architecture artifacts from ordinary historical repositories. -- Teach reverse commands to consume optional `.specify/memory/repository-first/` dependency matrices and module invocation specs as evidence for development-view governance. -- Add a schema-backed architecture artifact contract and require commands to validate JSON-compatible working models before Markdown rendering. -- Separate command and template responsibilities: commands now own extraction, classification, validation, merge policy, and write boundaries; templates only define Markdown layout. -- Add the `arch-governance` preset to wrap only the core `/speckit.plan` workflow with architecture SSOT grounding. -- Keep architecture generation commands independent from core workflow commands by removing downstream planning language from architecture artifacts. +- Teach reverse commands to consume optional `.specify/memory/repository-first/` evidence, with dependency matrix interpretation owned by development-view governance rather than treated as an independent view or equal input to every 4+1 view. +- Require the Development View commands to produce a `Dependency Matrix` section as part of the development-view artifact. +- Add a schema-backed architecture artifact contract for JSON-compatible working models before Markdown rendering. +- Add bash and PowerShell readiness validators that emit `ready_gate` and stable architecture blocker codes for synthesis refresh decisions. +- Separate command, schema, validator, and template responsibilities: commands now own extraction, classification, merge policy, and write routing; schemas own working-model structure; validators own rendered-artifact readiness and blocker codes; templates only define Markdown layout. +- Keep this repository scoped to extension-owned architecture commands, templates, schemas, scripts, and contract tests. ## v1.0.0 diff --git a/extensions/arch/README.md b/extensions/arch/README.md index fd610c3334..a5e52d252a 100644 --- a/extensions/arch/README.md +++ b/extensions/arch/README.md @@ -4,7 +4,7 @@ Add a project-level architecture source of truth to Spec Kit. Spec Kit is very good at turning a feature spec into a plan, tasks, and implementation work. In real projects, though, feature specs often do not carry enough stable architecture context: module boundaries, runtime responsibilities, deployment assumptions, cross-team ownership, and the tradeoffs that should not be rediscovered by every agent run. -This extension fills that gap. It creates architecture memory under `.specify/memory/` so future planning can refer to one explicit architecture SSOT instead of guessing from scattered docs, old code, or one feature request. +This extension fills that gap. It creates architecture memory under `.specify/memory/` so architecture decisions can be reviewed from one explicit SSOT instead of guessed from scattered docs, old code, or one feature request. ## When You Need This @@ -12,7 +12,7 @@ Use this extension when you want the AI agent to preserve architecture intent ac - You are starting or reshaping a Spec Kit project and want architecture decisions captured before detailed planning. - You have an existing repository and need architecture memory derived from observable repo facts. -- You want later `/speckit.plan` runs to see stable boundaries, constraints, tradeoffs, and unresolved gaps. +- You want stable boundaries, constraints, tradeoffs, and unresolved gaps captured before downstream work consumes architecture context. - You need a safe place for architecture-level reasoning without editing source code, feature specs, tasks, deployment files, or runbooks. The extension is intentionally about architecture SSOT, not implementation design. It records project-level 4+1 architecture views and a synthesis that downstream work can use as grounding. @@ -29,7 +29,7 @@ specify extension info arch Community catalog entries may be discovery-only. Install the published release directly from GitHub: ```bash -specify extension add arch --from https://github.com/bigsmartben/spec-kit-arch/archive/refs/tags/v1.2.1.zip +specify extension add arch --from https://github.com/bigsmartben/spec-kit-arch/archive/refs/tags/v1.2.2.zip ``` Install from a local development checkout: @@ -46,14 +46,16 @@ After installation, the extension is copied under: ## Commands -The extension id is `arch`, and each command uses `.arch` as the command namespace. The extension provides ten commands: one forward-generation command and one reverse-generation command for each 4+1 architecture view. +The extension id is `arch`, and each command uses `.arch` as the command namespace. The extension provides twelve commands: one full forward-generation command, one full reverse-generation command, plus one forward-generation command and one reverse-generation command for each 4+1 architecture view. ```text +/speckit.arch.full-generate /speckit.arch.scenario-generate /speckit.arch.logical-generate /speckit.arch.process-generate /speckit.arch.development-generate /speckit.arch.physical-generate +/speckit.arch.full-reverse /speckit.arch.scenario-reverse /speckit.arch.logical-reverse /speckit.arch.process-reverse @@ -61,12 +63,14 @@ The extension id is `arch`, and each command uses `.arch` as the command namespa /speckit.arch.physical-reverse ``` -Choose the direction based on where architecture knowledge should come from, then choose the view you want to update. +Choose the direction based on where architecture knowledge should come from, then choose whether to generate the full 4+1 set or update one view. | Direction | Use when | Evidence source | Writes | | --- | --- | --- | --- | -| `generate` | You are working from intended product/use-case context or existing architecture memory | User input, current architecture views, optional `.specify/memory/uc.md` for scenario only | The selected architecture view, with synthesis refreshed only when all views are coherent | -| `reverse` | You are onboarding or documenting an existing repository | Observable repository facts recorded in `.specify/memory/architecture-repo-facts.md` | Repo facts plus the selected architecture view, with synthesis refreshed only when all views are coherent | +| `full-generate` | You want one command to generate the complete forward 4+1 architecture set | User input, current architecture memory, optional `.specify/memory/uc.md` | All five architecture views, with synthesis refreshed only when the readiness validator returns `ready_gate: PASS` | +| `full-reverse` | You want one command to reconstruct the complete 4+1 architecture set from an existing repository | Observable repository facts recorded in `.specify/memory/architecture-repo-facts.md` | Repo facts plus all five architecture views, with synthesis refreshed only when the readiness validator returns `ready_gate: PASS` | +| `generate` | You are working from intended product/use-case context or existing architecture memory | User input, current architecture views, optional `.specify/memory/uc.md` for scenario only | The selected architecture view, with synthesis refreshed only when the readiness validator returns `ready_gate: PASS` | +| `reverse` | You are onboarding or documenting an existing repository | Observable repository facts recorded in `.specify/memory/architecture-repo-facts.md` | Repo facts plus the selected architecture view, with synthesis refreshed only when the readiness validator returns `ready_gate: PASS` | | View | Forward command | Reverse command | Main artifact | | --- | --- | --- | --- | @@ -80,6 +84,14 @@ Choose the direction based on where architecture knowledge should come from, the Run `*.generate` commands when you already know what the project is meant to become, or when Spec Kit use-case context exists and you want to make architecture intent explicit before planning. +Use the full forward command when you want to populate the complete 4+1 set in dependency order: + +```text +/speckit.arch.full-generate +``` + +The full command writes the scenario, logical, process, development, and physical views, then refreshes `.specify/memory/architecture.md` only after all five generated views satisfy the working-model contract and the rendered-artifact readiness validator returns `ready_gate: PASS`. It does not read or update `.specify/memory/architecture-repo-facts.md`. + Recommended order: 1. `/speckit.arch.scenario-generate` @@ -95,14 +107,24 @@ Use it to answer questions like: - Which runtime, development, or deployment constraints are already architecture decisions? - Which architecture gaps must stay explicit until the team supplies more information? -Each forward command populates only its selected view. Its setup bootstrap may create missing placeholder files for the architecture memory set, but the command must not populate non-target views or use `.specify/memory/architecture-repo-facts.md` as input. It may refresh `.specify/memory/architecture.md` only after all five views contain coherent, non-placeholder architecture content. +Each per-view forward command populates only its selected view. Its setup bootstrap may create missing placeholder files for the architecture memory set, but the command must not populate non-target views or use `.specify/memory/architecture-repo-facts.md` as input. It may refresh `.specify/memory/architecture.md` only after the readiness validator reports `ready_gate: PASS`. + +`speckit.arch.development-generate` must produce the Development View `Dependency Matrix` section from logical/process architecture relationships and stated constraints. -Each command also loads `.specify/extensions/arch/schemas/architecture-artifacts.schema.json` as the structural contract for architecture artifacts. Commands own evidence extraction, classification, validation, and write boundaries; templates own only the Markdown rendering layout. +Each command also loads `.specify/extensions/arch/schemas/architecture-artifacts.schema.json` as the working-model contract and uses `.specify/extensions/arch/scripts/bash/validate-arch-artifacts.sh` or `.specify/extensions/arch/scripts/powershell/validate-arch-artifacts.ps1` as the rendered-artifact readiness gate. Commands own evidence extraction, classification, and write routing; schemas own working-model structure; validators own rendered-artifact readiness; templates own only the Markdown rendering layout. ### Reverse Generation Run `*.reverse` commands when the repository already exists but the architecture SSOT does not. +Use the full reverse command when you want to populate repo facts and the complete 4+1 set in dependency order: + +```text +/speckit.arch.full-reverse +``` + +The full reverse command writes `.specify/memory/architecture-repo-facts.md`, the scenario, logical, process, development, and physical views, then refreshes `.specify/memory/architecture.md` only after all five generated views satisfy the working-model contract and the rendered-artifact readiness validator returns `ready_gate: PASS`. + Recommended order: 1. `/speckit.arch.scenario-reverse` @@ -111,7 +133,7 @@ Recommended order: 4. `/speckit.arch.development-reverse` 5. `/speckit.arch.physical-reverse` -Each reverse command inspects repository evidence first, writes or refreshes `.specify/memory/architecture-repo-facts.md`, then derives the selected 4+1 view from those facts. The repo facts file is cumulative: reverse commands preserve existing non-placeholder facts outside their evidence focus unless cited evidence is removed, contradicted, or superseded, and they record the reason for any replacement or downgrade. A reverse command may refresh `.specify/memory/architecture.md` after all five views contain coherent, evidence-backed architecture content. +Each reverse command inspects repository evidence first, writes or refreshes `.specify/memory/architecture-repo-facts.md`, then derives the selected 4+1 view from those facts. The repo facts file is cumulative: reverse commands preserve existing non-placeholder facts outside their evidence focus unless cited evidence is removed, contradicted, or superseded, and they record the reason for any replacement or downgrade. A reverse command may refresh `.specify/memory/architecture.md` only after the readiness validator reports `ready_gate: PASS`. Reverse commands validate both the repo-facts working model and the target-view working model against the same schema contract before rendering Markdown. @@ -121,19 +143,29 @@ It is useful for: - Reconstructing architecture intent from README files, tests, entry points, package layout, routes, workers, CI/CD, configuration, and deployment clues. - Making uncertainty visible when the repository does not prove actors, runtime ownership, deployment topology, or business meaning. -If `.specify/memory/repository-first/` exists, reverse commands also treat those files as evidence inputs. They summarize dependency matrices and module invocation specs into architecture-level constraints, dependency rules, gaps, and review triggers. +If `.specify/memory/repository-first/` exists, reverse commands also treat those files as evidence inputs within each command's view scope. Dependency matrices are primarily owned by the development view: `speckit.arch.development-generate` and `speckit.arch.development-reverse` must produce the Development View `Dependency Matrix` section, and the reverse command summarizes repository-first matrices into architecture-level development constraints, dependency rules, gaps, and review triggers. Other views must not consume dependency matrices directly or treat them as a separate architecture view; they may use development-view dependency conclusions only when the development view is synthesis-ready and relevant to their target view. ### Synthesis Refresh -Commands refresh `.specify/memory/architecture.md` only when every 4+1 view is synthesis-ready: +Commands refresh `.specify/memory/architecture.md` only when the readiness validator reports `ready_gate: PASS` for the rendered architecture memory set. The validator reports `ready_gate: BLOCKED` with these runtime blocker codes when any rendered-artifact readiness rule fails: + +- `ARCH_ARTIFACT_MISSING`: a required architecture artifact is missing. +- `ARCH_PLACEHOLDER_PRESENT`: a rendered artifact still contains placeholder update markers. +- `ARCH_REQUIRED_SECTION_MISSING`: a required section id is absent from a rendered artifact. +- `ARCH_REQUIRED_SECTION_EMPTY`: a required section has no supported content. +- `ARCH_TRACEABILITY_MISSING`: a view has no supported Source Traceability records. +- `ARCH_DEPENDENCY_MATRIX_MISSING` or `ARCH_DEPENDENCY_MATRIX_EMPTY`: the Development View dependency matrix is absent or empty. -- The view file exists. -- It no longer contains `NEEDS ARCH UPDATE`. -- It contains concrete architecture conclusions or explicit gaps in required sections, not only template headings. -- Explicit gaps may remain, but gaps alone do not make a view synthesis-ready. -- Cross-view terminology is coherent enough to synthesize without inventing content. +Commands may also report command-local blocker codes while classifying candidate conclusions: -If any view is missing, placeholder-only, stale, or inconsistent, commands leave `.specify/memory/architecture.md` unchanged and report the missing or not-ready views. +- `ARCH_SOURCE_MISSING`: a conclusion or dependency matrix entry lacks an allowed source. +- `ARCH_USER_INPUT_ONLY`: a reverse-generated conclusion is supported only by user input. +- `ARCH_REPO_FIRST_MATRIX_MISUSED`: repository-first dependency matrices are copied into architecture views, treated as an independent view, or used as direct non-development evidence. +- `ARCH_GIT_HISTORY_ONLY`: Git history is used as the sole support for an architecture conclusion. +- `ARCH_BOUNDARY_NONRESPONSIBILITY_MISSING`: a boundary has responsibilities but no explicit non-responsibility. +- `ARCH_UNSUPPORTED_CONCLUSION`: unsupported content is promoted into conclusion tables instead of gaps. + +If any blocker is present, commands leave `.specify/memory/architecture.md` unchanged and report the blocker codes, affected artifacts, and affected sections. ## Files Written @@ -154,14 +186,16 @@ Reverse commands also write their evidence layer: .specify/memory/architecture-repo-facts.md ``` -Forward `*.generate` commands populate only the selected view. Their setup may create placeholder architecture memory files, including an empty `.specify/memory/architecture-repo-facts.md` for reverse workflow compatibility, but generate commands do not use that file as input. +The full forward command populates the five 4+1 view files and may refresh `.specify/memory/architecture.md` after all generated views are synthesis-ready. Per-view forward `*.generate` commands populate only the selected view. Their setup may create placeholder architecture memory files, including an empty `.specify/memory/architecture-repo-facts.md` for reverse workflow compatibility, but generate commands do not use that file as input. -Reverse `*.reverse` commands populate `.specify/memory/architecture-repo-facts.md` plus the selected view, preserving unrelated existing repo facts unless evidence has changed and the reason is recorded. +The full reverse command populates `.specify/memory/architecture-repo-facts.md` plus all five 4+1 view files, and may refresh `.specify/memory/architecture.md` after all generated views are synthesis-ready. Per-view reverse `*.reverse` commands populate `.specify/memory/architecture-repo-facts.md` plus the selected view, preserving unrelated existing repo facts unless evidence has changed and the reason is recorded. The extension also ships the artifact contract used by the prompts: ```text .specify/extensions/arch/schemas/architecture-artifacts.schema.json +.specify/extensions/arch/scripts/bash/validate-arch-artifacts.sh +.specify/extensions/arch/scripts/powershell/validate-arch-artifacts.ps1 ``` The commands do not edit: @@ -179,18 +213,6 @@ deployment manifests runbooks ``` -## Using The Architecture SSOT In Planning - -The extension commands create the architecture memory. To make the core Spec Kit planning flow read that memory automatically, install the optional preset: - -```bash -specify preset add --dev /home/administrator/github/spec-kit-arch/presets/arch-governance -``` - -The preset wraps only `/speckit.plan`. It injects the architecture SSOT into planning so new feature plans can be checked against existing boundaries, constraints, and gaps. - -The preset does not override `/speckit.tasks` or `/speckit.implement`. - ## What The Extension Is Not This extension does not produce implementation plans, task lists, class designs, API schemas, database schemas, framework choices, deployment manifests, or runbooks. @@ -208,13 +230,4 @@ specify extension add --dev /home/administrator/github/spec-kit-arch .specify/extensions/arch/scripts/bash/setup-arch.sh --json ``` -Validate the preset from a fresh project: - -```bash -specify init /tmp/spec-kit-arch-preset-test --ai codex --ignore-agent-tools --script sh -cd /tmp/spec-kit-arch-preset-test -specify preset add --dev /home/administrator/github/spec-kit-arch/presets/arch-governance -rg -n "Architecture SSOT Injection|Architecture Grounding Summary" .agents/skills/speckit-plan/SKILL.md -``` - The extension intentionally does not provide the legacy `/speckit.arch`, `/speckit.arch.generate`, or `/speckit.arch.reverse` commands. diff --git a/extensions/arch/commands/speckit.arch.development-generate.md b/extensions/arch/commands/speckit.arch.development-generate.md index 19f9e6b721..4364cd775f 100644 --- a/extensions/arch/commands/speckit.arch.development-generate.md +++ b/extensions/arch/commands/speckit.arch.development-generate.md @@ -21,11 +21,11 @@ Generate or refresh the development view: - Primary inputs: `.specify/memory/architecture-logical-view.md`, `.specify/memory/architecture-process-view.md` - Optional synthesis refresh: `.specify/memory/architecture.md` -The development view derives architecture-level components, package boundary intent, contract/artifact semantics, and dependency rules from logical and process views. +The development view derives architecture-level components, package boundary intent, contract/artifact semantics, dependency rules, and the required dependency matrix from logical and process views. ## Operating Boundaries -- Write only `DEVELOPMENT_VIEW`; update `ARCH_FILE` only if the five architecture views are already coherent enough to refresh synthesis without inventing content. +- Write only `DEVELOPMENT_VIEW`; update `ARCH_FILE` only when the architecture readiness validator returns `ready_gate: PASS`. - Do not read, populate, or update `REPO_FACTS_FILE`. - Do not modify logical or process views, source code, specs, plans, tasks, docs, tests, package files, deployment files, or runbooks. - Stay at architecture-level development structure, not concrete implementation design. @@ -39,30 +39,33 @@ If setup creates `REPO_FACTS_FILE`, leave it as-is. Do not read it as input and ## Structured Contract -`ARCH_SCHEMA_FILE` is the authoritative structural contract for architecture artifacts. Build a JSON-compatible working model for every file you update, validate required sections, traceability records, gaps, and `High` / `Medium` / `Low` confidence values against the schema, then render Markdown with the corresponding template. The command owns extraction, classification, validation, and write policy; templates own Markdown layout only. +`ARCH_SCHEMA_FILE` is the authoritative working-model contract for architecture artifacts. Use it to shape JSON-compatible working models for every file you update before rendering Markdown with the corresponding templates. `ARCH_VALIDATOR_FILE` and `ARCH_VALIDATOR_PS_FILE` provide the executable readiness gate for rendered artifacts. After rendering candidate changes, run the readiness validator and use its `ready_gate` and blocker codes as the only synthesis refresh decision. The command owns evidence extraction, classification, merge policy when applicable, and write routing; schemas own working-model structure; validators own rendered-artifact readiness; templates own Markdown layout only. + +For `DEVELOPMENT_VIEW`, the `Dependency Matrix` section is a required output section with section id `dependency-matrix`. Populate it from source-backed logical/process architecture relationships and stated constraints; when evidence is insufficient for a matrix relation, record the missing relation in `Development View Gaps` instead of omitting the section. ## Synthesis Readiness -Parse all five view paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, and `PHYSICAL_VIEW`. +Parse all five view paths and validator paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_VALIDATOR_FILE`, and `ARCH_VALIDATOR_PS_FILE`. -A view is ready for synthesis only when it exists, no longer contains `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion in its required sections. Unsupported or unknown items must be recorded in that view's gaps and do not make the view ready. Refresh `ARCH_FILE` only when all five views are ready and cross-view terminology is coherent. Otherwise leave `ARCH_FILE` unchanged and report the missing or not-ready views. +Synthesis readiness is validator-owned. Run `ARCH_VALIDATOR_FILE --json` (or `ARCH_VALIDATOR_PS_FILE -Json` in PowerShell-only environments) after rendering candidate view updates. Refresh `ARCH_FILE` only when the validator returns `ready_gate: PASS` with no blockers. If the validator returns `ready_gate: BLOCKED`, leave `ARCH_FILE` unchanged and report the blocker codes, affected artifacts, and affected sections. ## Outline -1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `REPO_FACTS_FILE`, and all five view paths. +1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `ARCH_VALIDATOR_FILE`, `ARCH_VALIDATOR_PS_FILE`, `REPO_FACTS_FILE`, and all five view paths. 2. Load `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `ARCH_SCHEMA_FILE`, `architecture-development-template.md`, and `architecture-template.md`. 3. Extract source-backed logical boundaries, process collaborations, contracts, and invariants. 4. Normalize component, package, contract, and dependency terminology. -5. Derive architecture-level development boundaries and dependency rules. +5. Derive architecture-level development boundaries, dependency rules, and the required dependency matrix. 6. Classify each candidate as a supported development conclusion or a development gap under the schema and quality gates. 7. Render the schema-compliant development working model with `architecture-development-template.md`. -8. Apply the synthesis readiness rule. If all five view files are ready, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report the missing or not-ready views. +8. Run the readiness validator. If it returns `ready_gate: PASS`, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report validator blocker codes. 9. Report updated paths and explicit development gaps. ## Quality Gates -- ERROR if the development view contains source file paths, concrete package trees, classes, functions, framework wiring, or implementation tasks. -- ERROR if a target-view conclusion is not grounded in logical/process architecture or a stated constraint. -- Unsupported target-view conclusions MUST appear only in `Development View Gaps`, not in conclusion tables. -- ERROR if a boundary has responsibilities but no explicit non-responsibility. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if the development view contains source file paths, concrete package trees, classes, functions, framework wiring, or implementation tasks. +- BLOCKER `ARCH_DEPENDENCY_MATRIX_MISSING` if the development view omits the required `Dependency Matrix` section. +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks logical/process architecture or a stated constraint. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if unsupported target-view conclusions appear in conclusion tables; place them only in `Development View Gaps`. +- BLOCKER `ARCH_BOUNDARY_NONRESPONSIBILITY_MISSING` if a boundary has responsibilities but no explicit non-responsibility. - Record gaps instead of inventing development structure. diff --git a/extensions/arch/commands/speckit.arch.development-reverse.md b/extensions/arch/commands/speckit.arch.development-reverse.md index 35631c83bc..d6abc398a5 100644 --- a/extensions/arch/commands/speckit.arch.development-reverse.md +++ b/extensions/arch/commands/speckit.arch.development-reverse.md @@ -11,7 +11,7 @@ scripts: $ARGUMENTS ``` -You **MUST** consider the user input before proceeding (if not empty). +You **MUST** consider the user input before proceeding (if not empty). In reverse workflows, user input may scope evidence collection or state explicit external constraints, but user input alone must not prove a reverse-generated architecture conclusion. ## Goal @@ -22,9 +22,11 @@ Reverse-generate or refresh the development view from observable repository evid - Supporting inputs: logical and process views if available under Supporting View Availability - Optional synthesis refresh: `.specify/memory/architecture.md` +The development view must include a `Dependency Matrix` section as a required output of this command. + ## Operating Boundaries -- Write only `REPO_FACTS_FILE` and `DEVELOPMENT_VIEW`; update `ARCH_FILE` only if the five architecture views are already coherent enough to refresh synthesis without inventing content. +- Write only `REPO_FACTS_FILE` and `DEVELOPMENT_VIEW`; update `ARCH_FILE` only when the architecture readiness validator returns `ready_gate: PASS`. - Do not modify logical/process views, source code, README files, docs, package files, configuration, tests, deployment files, specs, plans, tasks, or runbooks. - Stay at architecture-level development structure, not implementation design. - If repository evidence is insufficient, record a specific evidence gap and development gap instead of inventing components, packages, contracts, or dependency rules. @@ -37,11 +39,11 @@ Reverse-generate or refresh the development view from observable repository evid Inspect package directories, module boundaries, imports, manifests, build scripts, configuration ownership, test grouping, examples, and CI structure. -Repository-First Inputs: if `.specify/memory/repository-first/` exists, inspect its markdown artifacts before deriving the view. Summarize build manifest detection, first-party module edges, allowed/forbidden invocation rules, dependency matrix signals, and governance actions in `REPO_FACTS_FILE`. Repository-first content must not be copied verbatim into architecture views. +Repository-First Inputs: if `.specify/memory/repository-first/` exists, inspect its markdown artifacts before deriving the view. Treat dependency matrices as development-owned dependency governance evidence, not as an independent architecture view. Summarize build manifest detection, first-party module edges, allowed/forbidden invocation rules, dependency matrix signals, and governance actions in `REPO_FACTS_FILE`, then project only architecture-level constraints into the required `Dependency Matrix` section and related `DEVELOPMENT_VIEW` dependency rules. Other views may consume only derived development-view constraints, never the matrix itself. Repository-first content must not be copied verbatim into architecture views. ## Supporting View Availability -`LOGICAL_VIEW` and `PROCESS_VIEW` are available only when each file exists, does not contain `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion. Placeholder content and view gaps may identify missing context but must not support new development conclusions. +`LOGICAL_VIEW` and `PROCESS_VIEW` are available only when the readiness validator reports no blockers for those views such as missing artifact, placeholder marker, required-section, or traceability failures. Placeholder content and view gaps may identify missing context but must not support new development conclusions. ## Repo Facts Merge Rule @@ -52,36 +54,39 @@ Treat `REPO_FACTS_FILE` as a cumulative evidence layer. Preserve existing non-pl - Every non-placeholder fact must name an evidence source such as a file, directory, configuration, test, script, manifest, command output, or commit signal. - Confidence values are `High`, `Medium`, or `Low`: `High` means multiple independent sources agree; `Medium` means one strong source is present; `Low` means naming, directory structure, isolated code, or Git history suggests a fact but lacks behavior evidence. - Git history is an auxiliary signal for change axes and boundary risks. It cannot independently prove architecture conclusions. -- Repository-first outputs are fact inputs. Summarize only architecture constraints, governance signals, gaps, or review triggers; do not copy full dependency inventories into architecture views. +- Repository-first outputs are fact inputs for development governance. Summarize only architecture constraints, dependency rules, governance signals, gaps, or review triggers; do not copy full dependency inventories into architecture views. - Concrete classes, functions, fields, endpoints, database tables, and implementation data structures may appear only as evidence sources, not architecture conclusions. -- Architecture conclusions must trace to repo facts, available supporting-view conclusions, user input, or stated external constraints. Unsupported items MUST appear only in `Evidence Gaps` or the target view gaps. +- Architecture conclusions must trace to repo facts, available supporting-view conclusions, or stated external constraints. If a conclusion is supported only by user input, report blocker code `ARCH_USER_INPUT_ONLY` and place it in `Evidence Gaps` or the target view gaps instead of conclusion tables. ## Structured Contract -`ARCH_SCHEMA_FILE` is the authoritative structural contract for architecture artifacts. Build JSON-compatible working models for `REPO_FACTS_FILE` and the target view, validate sections, traceability records, gaps, and `High` / `Medium` / `Low` confidence values against the schema, then render Markdown with the corresponding templates. The command owns evidence collection, classification, merge policy, validation, and write policy; templates own Markdown layout only. +`ARCH_SCHEMA_FILE` is the authoritative working-model contract for architecture artifacts. Use it to shape JSON-compatible working models for every file you update before rendering Markdown with the corresponding templates. `ARCH_VALIDATOR_FILE` and `ARCH_VALIDATOR_PS_FILE` provide the executable readiness gate for rendered artifacts. After rendering candidate changes, run the readiness validator and use its `ready_gate` and blocker codes as the only synthesis refresh decision. The command owns evidence extraction, classification, merge policy when applicable, and write routing; schemas own working-model structure; validators own rendered-artifact readiness; templates own Markdown layout only. + +For `DEVELOPMENT_VIEW`, the `Dependency Matrix` section is a required output section with section id `dependency-matrix`. Populate it from source-backed repository facts, repository-first dependency matrix signals, available logical/process architecture relationships, and stated constraints; when evidence is insufficient for a matrix relation, record the missing relation in `Evidence Gaps` or `Development View Gaps` instead of omitting the section. ## Synthesis Readiness -Parse all five view paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, and `PHYSICAL_VIEW`. +Parse all five view paths and validator paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_VALIDATOR_FILE`, and `ARCH_VALIDATOR_PS_FILE`. -A view is ready for synthesis only when it exists, no longer contains `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion in its required sections. Unsupported or unknown items must be recorded in that view's gaps and do not make the view ready. Refresh `ARCH_FILE` only when all five views are ready and cross-view terminology is coherent. Otherwise leave `ARCH_FILE` unchanged and report the missing or not-ready views. +Synthesis readiness is validator-owned. Run `ARCH_VALIDATOR_FILE --json` (or `ARCH_VALIDATOR_PS_FILE -Json` in PowerShell-only environments) after rendering candidate view updates. Refresh `ARCH_FILE` only when the validator returns `ready_gate: PASS` with no blockers. If the validator returns `ready_gate: BLOCKED`, leave `ARCH_FILE` unchanged and report the blocker codes, affected artifacts, and affected sections. ## Outline -1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `REPO_FACTS_FILE`, and all five view paths. +1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `ARCH_VALIDATOR_FILE`, `ARCH_VALIDATOR_PS_FILE`, `REPO_FACTS_FILE`, and all five view paths. 2. Load `REPO_FACTS_FILE`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `ARCH_SCHEMA_FILE`, `architecture-repo-facts-template.md`, `architecture-development-template.md`, and `architecture-template.md`. 3. Refresh repo facts for this command's evidence focus and classify unsupported observations as evidence gaps. 4. Populate a schema-compliant development working model from eligible repo facts plus `LOGICAL_VIEW` and `PROCESS_VIEW` when they satisfy Supporting View Availability. -5. Summarize repository-first dependency matrices only as architecture constraints, dependency rules, gaps, or review triggers. +5. Populate the required `Dependency Matrix` section and summarize repository-first dependency matrices only as development-view architecture constraints, dependency rules, gaps, or review triggers. 6. Apply the repo facts merge rule before writing `REPO_FACTS_FILE`. -7. Apply the synthesis readiness rule. If all five view files are ready, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report the missing or not-ready views. +7. Run the readiness validator. If it returns `ready_gate: PASS`, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report validator blocker codes. 8. Report updated paths and explicit unresolved gaps. ## Quality Gates -- ERROR if the development view promotes concrete source paths, package trees, classes, functions, framework wiring, or implementation tasks into architecture conclusions. -- ERROR if repository-first dependency matrices are copied wholesale into a 4+1 view instead of summarized as architecture constraints. -- ERROR if a target-view conclusion lacks a repo fact, available `LOGICAL_VIEW` or `PROCESS_VIEW` source, or stated constraint. -- Unsupported target-view conclusions MUST appear only in `Evidence Gaps` or `Development View Gaps`, not in conclusion tables. -- ERROR if Git history is used alone as a development conclusion. -- GAP if development ownership or dependency governance cannot be supported by repository evidence. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if the development view promotes concrete source paths, package trees, classes, functions, framework wiring, or implementation tasks into architecture conclusions. +- BLOCKER `ARCH_DEPENDENCY_MATRIX_MISSING` if the development view omits the required `Dependency Matrix` section. +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks a repo fact, available `LOGICAL_VIEW` or `PROCESS_VIEW` source, or stated constraint. +- BLOCKER `ARCH_REPO_FIRST_MATRIX_MISUSED` if repository-first dependency matrices are copied into architecture views, treated as an independent architecture view, or used as direct non-development evidence. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if unsupported target-view conclusions appear in conclusion tables; place them only in `Evidence Gaps` or `Development View Gaps`. +- BLOCKER `ARCH_GIT_HISTORY_ONLY` if Git history is used alone as a development conclusion. +- BLOCKER `ARCH_SOURCE_MISSING` if development ownership or dependency governance cannot be supported by repository evidence; record the unsupported item in evidence gaps and target-view gaps. diff --git a/extensions/arch/commands/speckit.arch.full-generate.md b/extensions/arch/commands/speckit.arch.full-generate.md new file mode 100644 index 0000000000..4b9b657660 --- /dev/null +++ b/extensions/arch/commands/speckit.arch.full-generate.md @@ -0,0 +1,89 @@ +--- +description: Generate all 4+1 architecture views and the architecture synthesis from intended project context. +scripts: + sh: .specify/extensions/arch/scripts/bash/setup-arch.sh --json + ps: .specify/extensions/arch/scripts/powershell/setup-arch.ps1 -Json +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal + +Generate or refresh the complete forward 4+1 architecture set: + +- Scenario view: `.specify/memory/architecture-scenario-view.md` +- Logical view: `.specify/memory/architecture-logical-view.md` +- Process view: `.specify/memory/architecture-process-view.md` +- Development view: `.specify/memory/architecture-development-view.md` +- Physical view: `.specify/memory/architecture-physical-view.md` +- Synthesis: `.specify/memory/architecture.md` + +This command is the full forward-generation workflow. It derives the `+1` scenario view first, then derives the four supporting views in dependency order, and refreshes the synthesis only from validated view content. + +## Operating Boundaries + +- Write only `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, and `ARCH_FILE`. +- Do not read, populate, or update `REPO_FACTS_FILE`. +- Read `.specify/memory/uc.md` only as optional scenario background. +- Do not modify `.specify/memory/uc.md`, `.specify/memory/constitution.md`, feature specs, plans, tasks, source code, tests, root `docs/`, deployment manifests, package files, infrastructure files, or runbooks. +- Stay at abstract architecture-design level across all views. +- If context is insufficient for any view, record a specific gap in that view instead of inventing architecture facts. + +## Setup Bootstrap + +`{SCRIPT}` may create missing architecture memory files from templates, including `REPO_FACTS_FILE`. Treat that as bootstrap scaffolding only. After setup, this command must populate only the five architecture views and `ARCH_FILE`. + +If setup creates `REPO_FACTS_FILE`, leave it as-is. Do not read it as input and do not add facts to it from this generate command. + +## Structured Contract + +`ARCH_SCHEMA_FILE` is the authoritative working-model contract for architecture artifacts. Use it to shape JSON-compatible working models for every file you update before rendering Markdown with the corresponding templates. `ARCH_VALIDATOR_FILE` and `ARCH_VALIDATOR_PS_FILE` provide the executable readiness gate for rendered artifacts. After rendering candidate changes, run the readiness validator and use its `ready_gate` and blocker codes as the only synthesis refresh decision. The command owns evidence extraction, classification, merge policy when applicable, and write routing; schemas own working-model structure; validators own rendered-artifact readiness; templates own Markdown layout only. + +For `DEVELOPMENT_VIEW`, the `Dependency Matrix` section is a required output section. Populate it from source-backed logical/process architecture relationships and stated constraints; when evidence is insufficient for a matrix relation, record the missing relation in `Development View Gaps` instead of omitting the section. + +## Generation Order + +Generate and validate views in this order: + +1. `SCENARIO_VIEW` from user input, optional `.specify/memory/uc.md`, and existing memory context. +2. `LOGICAL_VIEW` from validated scenario architecture semantics. +3. `PROCESS_VIEW` from validated scenario paths and logical boundaries. +4. `DEVELOPMENT_VIEW` from validated logical/process architecture relationships. +5. `PHYSICAL_VIEW` from validated process/development architecture constraints. +6. `ARCH_FILE` from the five validated views, only after synthesis readiness passes. + +Each later view may use earlier views generated in the same command after their working models pass the schema and quality gates. Do not use a placeholder or gap-only view as proof for downstream architecture conclusions. + +## Synthesis Readiness + +Parse all five view paths and validator paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_VALIDATOR_FILE`, and `ARCH_VALIDATOR_PS_FILE`. + +Synthesis readiness is validator-owned. Run `ARCH_VALIDATOR_FILE --json` (or `ARCH_VALIDATOR_PS_FILE -Json` in PowerShell-only environments) after rendering candidate view updates. Refresh `ARCH_FILE` only when the validator returns `ready_gate: PASS` with no blockers. If the validator returns `ready_gate: BLOCKED`, leave `ARCH_FILE` unchanged and report the blocker codes, affected artifacts, and affected sections. + +## Outline + +1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `ARCH_VALIDATOR_FILE`, `ARCH_VALIDATOR_PS_FILE`, `REPO_FACTS_FILE`, and all five view paths. +2. Load `ARCH_FILE`, all five view files, `ARCH_SCHEMA_FILE`, all six architecture templates, and `.specify/memory/uc.md` if present. +3. Generate the scenario working model from source-backed user, use-case, and memory context. +4. Generate logical, process, development, and physical working models in dependency order, using only validated upstream architecture conclusions and stated constraints. +5. Populate the required development `Dependency Matrix` section from validated logical/process relationships and stated constraints. +6. Classify every candidate conclusion as supported architecture content or a view-specific gap under the schema and quality gates. +7. Render the five schema-compliant view working models with their corresponding templates. +8. Run the readiness validator. If it returns `ready_gate: PASS`, render `ARCH_FILE` with `architecture-template.md`; otherwise leave synthesis untouched and report validator blocker codes. +9. Report updated paths and explicit gaps by view. + +## Quality Gates + +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if any generated view contains concrete implementation design, source paths, classes, functions, endpoints, database fields, deployment manifests, infrastructure configuration, scripts, runbooks, plans, tasks, or test strategy. +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks user input, optional use-case context, validated upstream architecture, existing memory context, or a stated constraint. +- BLOCKER `ARCH_DEPENDENCY_MATRIX_MISSING` if the development view omits the required `Dependency Matrix` section. +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks logical/process architecture or a stated constraint. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if unsupported conclusions appear in conclusion tables; place them only in the corresponding view gaps. +- BLOCKER `ARCH_BOUNDARY_NONRESPONSIBILITY_MISSING` if a boundary has responsibilities but no explicit non-responsibility. +- Record gaps instead of inventing business facts, authority boundaries, runtime behavior, development structure, topology, or operational constraints. diff --git a/extensions/arch/commands/speckit.arch.full-reverse.md b/extensions/arch/commands/speckit.arch.full-reverse.md new file mode 100644 index 0000000000..4341ee8f7a --- /dev/null +++ b/extensions/arch/commands/speckit.arch.full-reverse.md @@ -0,0 +1,109 @@ +--- +description: Reverse-generate all 4+1 architecture views and the architecture synthesis from observable repository facts. +scripts: + sh: .specify/extensions/arch/scripts/bash/setup-arch.sh --json + ps: .specify/extensions/arch/scripts/powershell/setup-arch.ps1 -Json +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). In reverse workflows, user input may scope evidence collection or state explicit external constraints, but user input alone must not prove a reverse-generated architecture conclusion. + +## Goal + +Reverse-generate or refresh the complete 4+1 architecture set from observable repository evidence: + +- Evidence layer: `.specify/memory/architecture-repo-facts.md` +- Scenario view: `.specify/memory/architecture-scenario-view.md` +- Logical view: `.specify/memory/architecture-logical-view.md` +- Process view: `.specify/memory/architecture-process-view.md` +- Development view: `.specify/memory/architecture-development-view.md` +- Physical view: `.specify/memory/architecture-physical-view.md` +- Synthesis: `.specify/memory/architecture.md` + +This command is the full reverse-generation workflow. It records repository facts first, derives the `+1` scenario view and four supporting views from those facts, then refreshes synthesis only from validated view content. + +## Operating Boundaries + +- Write only `REPO_FACTS_FILE`, `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, and `ARCH_FILE`. +- Do not modify source code, README files, project documentation, package files, configuration, tests, deployment files, `.specify/memory/uc.md`, `.specify/memory/constitution.md`, feature specs, plans, tasks, root `docs/`, deployment manifests, infrastructure files, or runbooks. +- Stay at abstract architecture-design level across all views. +- If repository evidence is insufficient for any view, record a specific evidence gap and view gap instead of inventing architecture facts. + +## Setup Bootstrap + +`{SCRIPT}` may create missing architecture memory files from templates. Treat that as bootstrap scaffolding only. After setup, this command must populate only `REPO_FACTS_FILE`, the five architecture views, and `ARCH_FILE`. + +## Evidence Sources + +Inspect README/docs, CLI/API entry points, examples, tests, route declarations, package directories, module boundaries, imports, manifests, build scripts, configuration ownership, CI structure, deployment clues, and user-visible behavior descriptions. Prefer concise inventory over exhaustive source listing. + +Repository-First Inputs: if `.specify/memory/repository-first/` exists, inspect its markdown artifacts before deriving the views. Dependency matrices are owned by the development view: summarize build manifest detection, first-party module edges, allowed/forbidden invocation rules, dependency matrix signals, and governance actions in `REPO_FACTS_FILE`, then project only architecture-level dependency constraints into the required development `Dependency Matrix` section and related development-view rules. A dependency matrix is evidence for development governance, not an independent architecture view or equal input to every 4+1 view. Repository-first content must not be copied verbatim into architecture views. + +## Repo Facts Merge Rule + +Treat `REPO_FACTS_FILE` as a cumulative evidence layer. Preserve existing non-placeholder facts unless the cited evidence no longer exists or is contradicted by stronger evidence. When replacing, removing, or downgrading an existing fact, record the reason in `Evidence Gaps` or a review trigger instead of silently dropping it. + +## Repo Facts Evidence Rules + +- Every non-placeholder fact must name an evidence source such as a file, directory, configuration, test, script, manifest, command output, or commit signal. +- Confidence values are `High`, `Medium`, or `Low`: `High` means multiple independent sources agree; `Medium` means one strong source is present; `Low` means naming, directory structure, isolated code, or Git history suggests a fact but lacks behavior evidence. +- Git history is an auxiliary signal for change axes and boundary risks. It cannot independently prove architecture conclusions. +- Repository-first outputs are fact inputs only when summarized into architecture constraints, dependency rules, governance signals, gaps, or review triggers; do not copy full dependency inventories into architecture views. +- Concrete classes, functions, fields, endpoints, database tables, and implementation data structures may appear only as evidence sources, not architecture conclusions. +- Architecture conclusions must trace to repo facts or stated external constraints. If a conclusion is supported only by user input, report blocker code `ARCH_USER_INPUT_ONLY` and place it in `Evidence Gaps` or the target view gaps instead of conclusion tables. + +## Structured Contract + +`ARCH_SCHEMA_FILE` is the authoritative working-model contract for architecture artifacts. Use it to shape JSON-compatible working models for every file you update before rendering Markdown with the corresponding templates. `ARCH_VALIDATOR_FILE` and `ARCH_VALIDATOR_PS_FILE` provide the executable readiness gate for rendered artifacts. After rendering candidate changes, run the readiness validator and use its `ready_gate` and blocker codes as the only synthesis refresh decision. The command owns evidence extraction, classification, merge policy when applicable, and write routing; schemas own working-model structure; validators own rendered-artifact readiness; templates own Markdown layout only. + +For `DEVELOPMENT_VIEW`, the `Dependency Matrix` section is a required output section with section id `dependency-matrix`. Populate it from source-backed repository facts, repository-first dependency matrix signals, available logical/process architecture relationships generated in this command, and stated constraints; when evidence is insufficient for a matrix relation, record the missing relation in `Evidence Gaps` or `Development View Gaps` instead of omitting the section. + +## Reverse Generation Order + +Generate and validate artifacts in this order: + +1. `REPO_FACTS_FILE` from observable repository evidence and optional repository-first evidence. +2. `SCENARIO_VIEW` from high- or medium-confidence facts about user-visible behavior, actors, goals, paths, and acceptance semantics. +3. `LOGICAL_VIEW` from repo facts plus validated scenario architecture semantics. +4. `PROCESS_VIEW` from repo facts plus validated scenario paths and logical boundaries. +5. `DEVELOPMENT_VIEW` from repo facts plus validated logical/process architecture relationships, including the required `Dependency Matrix` section. +6. `PHYSICAL_VIEW` from repo facts plus validated process/development architecture constraints. +7. `ARCH_FILE` from the five validated views, only after synthesis readiness passes. + +Each later view may use earlier views generated in the same command after their working models pass the schema and quality gates. Do not use a placeholder or gap-only view as proof for downstream architecture conclusions. + +## Synthesis Readiness + +Parse all five view paths and validator paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_VALIDATOR_FILE`, and `ARCH_VALIDATOR_PS_FILE`. + +Synthesis readiness is validator-owned. Run `ARCH_VALIDATOR_FILE --json` (or `ARCH_VALIDATOR_PS_FILE -Json` in PowerShell-only environments) after rendering candidate view updates. Refresh `ARCH_FILE` only when the validator returns `ready_gate: PASS` with no blockers. If the validator returns `ready_gate: BLOCKED`, leave `ARCH_FILE` unchanged and report the blocker codes, affected artifacts, and affected sections. + +## Outline + +1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `ARCH_VALIDATOR_FILE`, `ARCH_VALIDATOR_PS_FILE`, `REPO_FACTS_FILE`, and all five view paths. +2. Load `REPO_FACTS_FILE`, `ARCH_FILE`, all five view files, `ARCH_SCHEMA_FILE`, all seven architecture templates, and optional `.specify/memory/repository-first/` markdown artifacts. +3. Refresh repo facts across scenario, logical, process, development, and physical evidence focuses; classify unsupported observations as evidence gaps. +4. Generate scenario, logical, process, development, and physical working models in reverse-generation order, using only eligible repo facts, validated upstream architecture conclusions, and stated constraints. +5. Populate the required development `Dependency Matrix` section and summarize repository-first dependency matrices only as development-view architecture constraints, dependency rules, gaps, or review triggers. +6. Apply the repo facts merge rule before writing `REPO_FACTS_FILE`. +7. Classify every candidate conclusion as supported architecture content or a view-specific gap under the schema and quality gates. +8. Render the repo facts file and five schema-compliant view working models with their corresponding templates. +9. Run the readiness validator. If it returns `ready_gate: PASS`, render `ARCH_FILE` with `architecture-template.md`; otherwise leave synthesis untouched and report validator blocker codes. +10. Report updated paths and explicit unresolved gaps by evidence focus and view. + +## Quality Gates + +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks a repo fact source or stated external constraint source. +- BLOCKER `ARCH_SOURCE_MISSING` if the repo facts file contains generic claims without file paths, directories, configuration, tests, commands, or commit signals. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if any generated view promotes concrete source paths, package trees, classes, functions, fields, endpoints, database structure, framework wiring, deployment manifests, infrastructure configuration, scripts, runbooks, plans, tasks, or test strategy into architecture conclusions. +- BLOCKER `ARCH_DEPENDENCY_MATRIX_MISSING` if the development view omits the required `Dependency Matrix` section. +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks a repo fact, generated `LOGICAL_VIEW` or `PROCESS_VIEW` source, repository-first dependency matrix signal, or stated constraint. +- BLOCKER `ARCH_REPO_FIRST_MATRIX_MISUSED` if repository-first dependency matrices are copied into architecture views, treated as an independent architecture view, or used as direct non-development evidence. +- BLOCKER `ARCH_GIT_HISTORY_ONLY` if Git history is used alone as an architecture conclusion. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if unsupported conclusions appear in conclusion tables; place them only in `Evidence Gaps` or the corresponding view gaps. +- Record gaps instead of inventing actors, business meaning, authority boundaries, runtime behavior, development structure, topology, or operational constraints. diff --git a/extensions/arch/commands/speckit.arch.logical-generate.md b/extensions/arch/commands/speckit.arch.logical-generate.md index 5eb6037474..35c1d14c9e 100644 --- a/extensions/arch/commands/speckit.arch.logical-generate.md +++ b/extensions/arch/commands/speckit.arch.logical-generate.md @@ -25,7 +25,7 @@ The logical view derives capability boundaries, domain objects, states, relation ## Operating Boundaries -- Write only `LOGICAL_VIEW`; update `ARCH_FILE` only if the five architecture views are already coherent enough to refresh synthesis without inventing content. +- Write only `LOGICAL_VIEW`; update `ARCH_FILE` only when the architecture readiness validator returns `ready_gate: PASS`. - Do not read, populate, or update `REPO_FACTS_FILE`. - Do not modify scenario view, source code, specs, plans, tasks, docs, tests, deployment files, or runbooks. - Stay at abstract logical architecture level. @@ -39,30 +39,30 @@ If setup creates `REPO_FACTS_FILE`, leave it as-is. Do not read it as input and ## Structured Contract -`ARCH_SCHEMA_FILE` is the authoritative structural contract for architecture artifacts. Build a JSON-compatible working model for every file you update, validate required sections, traceability records, gaps, and `High` / `Medium` / `Low` confidence values against the schema, then render Markdown with the corresponding template. The command owns extraction, classification, validation, and write policy; templates own Markdown layout only. +`ARCH_SCHEMA_FILE` is the authoritative working-model contract for architecture artifacts. Use it to shape JSON-compatible working models for every file you update before rendering Markdown with the corresponding templates. `ARCH_VALIDATOR_FILE` and `ARCH_VALIDATOR_PS_FILE` provide the executable readiness gate for rendered artifacts. After rendering candidate changes, run the readiness validator and use its `ready_gate` and blocker codes as the only synthesis refresh decision. The command owns evidence extraction, classification, merge policy when applicable, and write routing; schemas own working-model structure; validators own rendered-artifact readiness; templates own Markdown layout only. ## Synthesis Readiness -Parse all five view paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, and `PHYSICAL_VIEW`. +Parse all five view paths and validator paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_VALIDATOR_FILE`, and `ARCH_VALIDATOR_PS_FILE`. -A view is ready for synthesis only when it exists, no longer contains `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion in its required sections. Unsupported or unknown items must be recorded in that view's gaps and do not make the view ready. Refresh `ARCH_FILE` only when all five views are ready and cross-view terminology is coherent. Otherwise leave `ARCH_FILE` unchanged and report the missing or not-ready views. +Synthesis readiness is validator-owned. Run `ARCH_VALIDATOR_FILE --json` (or `ARCH_VALIDATOR_PS_FILE -Json` in PowerShell-only environments) after rendering candidate view updates. Refresh `ARCH_FILE` only when the validator returns `ready_gate: PASS` with no blockers. If the validator returns `ready_gate: BLOCKED`, leave `ARCH_FILE` unchanged and report the blocker codes, affected artifacts, and affected sections. ## Outline -1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `REPO_FACTS_FILE`, and all five view paths. +1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `ARCH_VALIDATOR_FILE`, `ARCH_VALIDATOR_PS_FILE`, `REPO_FACTS_FILE`, and all five view paths. 2. Load `SCENARIO_VIEW`, `LOGICAL_VIEW`, `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `architecture-logical-template.md`, and `architecture-template.md`. 3. Extract source-backed scenario conclusions and scenario terminology. 4. Normalize capability, object, state, and boundary names. 5. Derive logical authority boundaries, domain relationships, and lifecycle constraints. 6. Classify each candidate as a supported logical conclusion or a logical gap under the schema and quality gates. 7. Render the schema-compliant logical working model with `architecture-logical-template.md`. -8. Apply the synthesis readiness rule. If all five view files are ready, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report the missing or not-ready views. +8. Run the readiness validator. If it returns `ready_gate: PASS`, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report validator blocker codes. 9. Report updated paths and explicit logical gaps. ## Quality Gates -- ERROR if the logical view introduces classes, DTOs, database tables, fields, endpoints, schemas, or implementation data structures. -- ERROR if a target-view conclusion is not grounded in a scenario, boundary, lifecycle constraint, or stated user constraint. -- Unsupported target-view conclusions MUST appear only in `Logical Gaps`, not in conclusion tables. -- ERROR if a boundary has responsibilities but no explicit non-responsibility. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if the logical view introduces classes, DTOs, database tables, fields, endpoints, schemas, or implementation data structures. +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks a scenario, boundary, lifecycle constraint, or stated user constraint. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if unsupported target-view conclusions appear in conclusion tables; place them only in `Logical Gaps`. +- BLOCKER `ARCH_BOUNDARY_NONRESPONSIBILITY_MISSING` if a boundary has responsibilities but no explicit non-responsibility. - Record gaps instead of inventing authority, lifecycle, or object facts. diff --git a/extensions/arch/commands/speckit.arch.logical-reverse.md b/extensions/arch/commands/speckit.arch.logical-reverse.md index 4d6012ed13..978b1c9132 100644 --- a/extensions/arch/commands/speckit.arch.logical-reverse.md +++ b/extensions/arch/commands/speckit.arch.logical-reverse.md @@ -11,7 +11,7 @@ scripts: $ARGUMENTS ``` -You **MUST** consider the user input before proceeding (if not empty). +You **MUST** consider the user input before proceeding (if not empty). In reverse workflows, user input may scope evidence collection or state explicit external constraints, but user input alone must not prove a reverse-generated architecture conclusion. ## Goal @@ -24,7 +24,7 @@ Reverse-generate or refresh the logical view from observable repository evidence ## Operating Boundaries -- Write only `REPO_FACTS_FILE` and `LOGICAL_VIEW`; update `ARCH_FILE` only if the five architecture views are already coherent enough to refresh synthesis without inventing content. +- Write only `REPO_FACTS_FILE` and `LOGICAL_VIEW`; update `ARCH_FILE` only when the architecture readiness validator returns `ready_gate: PASS`. - Do not modify scenario view, source code, README files, docs, package files, configuration, tests, deployment files, specs, plans, tasks, or runbooks. - Stay at abstract logical architecture level. - If repository evidence is insufficient, record a specific evidence gap and logical gap instead of inventing capabilities, objects, states, or invariants. @@ -37,11 +37,11 @@ Reverse-generate or refresh the logical view from observable repository evidence Inspect README/docs, entry points, tests, examples, route declarations, state clues, persistence clues, domain naming, and configuration ownership. -Repository-First Inputs: if `.specify/memory/repository-first/` exists, inspect its markdown artifacts and summarize build manifest detection, first-party module edges, invocation governance, and dependency governance signals that affect logical boundaries in `REPO_FACTS_FILE`. Repository-first content must not be copied verbatim into architecture views. +Repository-First Inputs: if `.specify/memory/repository-first/` exists, inspect only non-matrix markdown evidence that affects logical boundaries, such as domain naming, source-backed module roles, or stated invocation constraints, and summarize those signals in `REPO_FACTS_FILE`. Dependency matrices are owned by the development view; this command must not consume dependency matrices directly or treat them as a separate architecture view. Repository-first content must not be copied verbatim into architecture views. ## Supporting View Availability -`SCENARIO_VIEW` is available only when it exists, does not contain `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion. Placeholder content and scenario gaps may identify missing context but must not support new logical conclusions. +`SCENARIO_VIEW` is available only when the readiness validator reports no blockers for `SCENARIO_VIEW` such as missing artifact, placeholder marker, required-section, or traceability failures. Placeholder content and scenario gaps may identify missing context but must not support new logical conclusions. ## Repo Facts Merge Rule @@ -52,35 +52,36 @@ Treat `REPO_FACTS_FILE` as a cumulative evidence layer. Preserve existing non-pl - Every non-placeholder fact must name an evidence source such as a file, directory, configuration, test, script, manifest, command output, or commit signal. - Confidence values are `High`, `Medium`, or `Low`: `High` means multiple independent sources agree; `Medium` means one strong source is present; `Low` means naming, directory structure, isolated code, or Git history suggests a fact but lacks behavior evidence. - Git history is an auxiliary signal for change axes and boundary risks. It cannot independently prove architecture conclusions. -- Repository-first outputs are fact inputs. Summarize only architecture constraints, governance signals, gaps, or review triggers; do not copy full dependency inventories into architecture views. +- Repository-first outputs are fact inputs only when they match this command's logical evidence focus. Do not consume repository-first dependency matrices directly; use development-view dependency conclusions only after `DEVELOPMENT_VIEW` is synthesis-ready and relevant to logical boundaries. - Concrete classes, functions, fields, endpoints, database tables, and implementation data structures may appear only as evidence sources, not architecture conclusions. -- Architecture conclusions must trace to repo facts, available supporting-view conclusions, user input, or stated external constraints. Unsupported items MUST appear only in `Evidence Gaps` or the target view gaps. +- Architecture conclusions must trace to repo facts, available supporting-view conclusions, or stated external constraints. If a conclusion is supported only by user input, report blocker code `ARCH_USER_INPUT_ONLY` and place it in `Evidence Gaps` or the target view gaps instead of conclusion tables. ## Structured Contract -`ARCH_SCHEMA_FILE` is the authoritative structural contract for architecture artifacts. Build JSON-compatible working models for `REPO_FACTS_FILE` and the target view, validate sections, traceability records, gaps, and `High` / `Medium` / `Low` confidence values against the schema, then render Markdown with the corresponding templates. The command owns evidence collection, classification, merge policy, validation, and write policy; templates own Markdown layout only. +`ARCH_SCHEMA_FILE` is the authoritative working-model contract for architecture artifacts. Use it to shape JSON-compatible working models for every file you update before rendering Markdown with the corresponding templates. `ARCH_VALIDATOR_FILE` and `ARCH_VALIDATOR_PS_FILE` provide the executable readiness gate for rendered artifacts. After rendering candidate changes, run the readiness validator and use its `ready_gate` and blocker codes as the only synthesis refresh decision. The command owns evidence extraction, classification, merge policy when applicable, and write routing; schemas own working-model structure; validators own rendered-artifact readiness; templates own Markdown layout only. ## Synthesis Readiness -Parse all five view paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, and `PHYSICAL_VIEW`. +Parse all five view paths and validator paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_VALIDATOR_FILE`, and `ARCH_VALIDATOR_PS_FILE`. -A view is ready for synthesis only when it exists, no longer contains `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion in its required sections. Unsupported or unknown items must be recorded in that view's gaps and do not make the view ready. Refresh `ARCH_FILE` only when all five views are ready and cross-view terminology is coherent. Otherwise leave `ARCH_FILE` unchanged and report the missing or not-ready views. +Synthesis readiness is validator-owned. Run `ARCH_VALIDATOR_FILE --json` (or `ARCH_VALIDATOR_PS_FILE -Json` in PowerShell-only environments) after rendering candidate view updates. Refresh `ARCH_FILE` only when the validator returns `ready_gate: PASS` with no blockers. If the validator returns `ready_gate: BLOCKED`, leave `ARCH_FILE` unchanged and report the blocker codes, affected artifacts, and affected sections. ## Outline -1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `REPO_FACTS_FILE`, and all five view paths. +1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `ARCH_VALIDATOR_FILE`, `ARCH_VALIDATOR_PS_FILE`, `REPO_FACTS_FILE`, and all five view paths. 2. Load `REPO_FACTS_FILE`, `SCENARIO_VIEW`, `LOGICAL_VIEW`, `ARCH_SCHEMA_FILE`, `architecture-repo-facts-template.md`, `architecture-logical-template.md`, and `architecture-template.md`. 3. Refresh repo facts for this command's evidence focus and classify unsupported observations as evidence gaps. 4. Populate a schema-compliant logical working model from eligible repo facts and `SCENARIO_VIEW` when it satisfies Supporting View Availability. 5. Put low-confidence facts in gaps rather than promoting them into architecture conclusions. 6. Apply the repo facts merge rule before writing `REPO_FACTS_FILE`. -7. Apply the synthesis readiness rule. If all five view files are ready, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report the missing or not-ready views. +7. Run the readiness validator. If it returns `ready_gate: PASS`, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report validator blocker codes. 8. Report updated paths and explicit unresolved gaps. ## Quality Gates -- ERROR if the logical view promotes classes, functions, fields, endpoints, database structures, or implementation data structures into architecture conclusions. -- ERROR if a target-view conclusion lacks a repo fact, available `SCENARIO_VIEW` source, or stated constraint. -- Unsupported target-view conclusions MUST appear only in `Evidence Gaps` or `Logical Gaps`, not in conclusion tables. -- ERROR if Git history is used alone as a logical conclusion. -- GAP if authority boundaries or domain lifecycle cannot be supported by repository evidence. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if the logical view promotes classes, functions, fields, endpoints, database structures, or implementation data structures into architecture conclusions. +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks a repo fact, available `SCENARIO_VIEW` source, or stated constraint. +- BLOCKER `ARCH_REPO_FIRST_MATRIX_MISUSED` if repository-first dependency matrices are copied into architecture views, treated as an independent architecture view, or used as direct non-development evidence. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if unsupported target-view conclusions appear in conclusion tables; place them only in `Evidence Gaps` or `Logical Gaps`. +- BLOCKER `ARCH_GIT_HISTORY_ONLY` if Git history is used alone as a logical conclusion. +- BLOCKER `ARCH_SOURCE_MISSING` if authority boundaries or domain lifecycle cannot be supported by repository evidence; record the unsupported item in evidence gaps and target-view gaps. diff --git a/extensions/arch/commands/speckit.arch.physical-generate.md b/extensions/arch/commands/speckit.arch.physical-generate.md index 4b321ccbef..e7716237a9 100644 --- a/extensions/arch/commands/speckit.arch.physical-generate.md +++ b/extensions/arch/commands/speckit.arch.physical-generate.md @@ -25,7 +25,7 @@ The physical view derives deployment, hosting, external system, fact-source, obs ## Operating Boundaries -- Write only `PHYSICAL_VIEW`; update `ARCH_FILE` only if the five architecture views are already coherent enough to refresh synthesis without inventing content. +- Write only `PHYSICAL_VIEW`; update `ARCH_FILE` only when the architecture readiness validator returns `ready_gate: PASS`. - Do not read, populate, or update `REPO_FACTS_FILE`. - Do not modify process or development views, source code, specs, plans, tasks, docs, tests, deployment manifests, infrastructure files, or runbooks. - Stay at abstract physical architecture level. @@ -39,30 +39,30 @@ If setup creates `REPO_FACTS_FILE`, leave it as-is. Do not read it as input and ## Structured Contract -`ARCH_SCHEMA_FILE` is the authoritative structural contract for architecture artifacts. Build a JSON-compatible working model for every file you update, validate required sections, traceability records, gaps, and `High` / `Medium` / `Low` confidence values against the schema, then render Markdown with the corresponding template. The command owns extraction, classification, validation, and write policy; templates own Markdown layout only. +`ARCH_SCHEMA_FILE` is the authoritative working-model contract for architecture artifacts. Use it to shape JSON-compatible working models for every file you update before rendering Markdown with the corresponding templates. `ARCH_VALIDATOR_FILE` and `ARCH_VALIDATOR_PS_FILE` provide the executable readiness gate for rendered artifacts. After rendering candidate changes, run the readiness validator and use its `ready_gate` and blocker codes as the only synthesis refresh decision. The command owns evidence extraction, classification, merge policy when applicable, and write routing; schemas own working-model structure; validators own rendered-artifact readiness; templates own Markdown layout only. ## Synthesis Readiness -Parse all five view paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, and `PHYSICAL_VIEW`. +Parse all five view paths and validator paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_VALIDATOR_FILE`, and `ARCH_VALIDATOR_PS_FILE`. -A view is ready for synthesis only when it exists, no longer contains `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion in its required sections. Unsupported or unknown items must be recorded in that view's gaps and do not make the view ready. Refresh `ARCH_FILE` only when all five views are ready and cross-view terminology is coherent. Otherwise leave `ARCH_FILE` unchanged and report the missing or not-ready views. +Synthesis readiness is validator-owned. Run `ARCH_VALIDATOR_FILE --json` (or `ARCH_VALIDATOR_PS_FILE -Json` in PowerShell-only environments) after rendering candidate view updates. Refresh `ARCH_FILE` only when the validator returns `ready_gate: PASS` with no blockers. If the validator returns `ready_gate: BLOCKED`, leave `ARCH_FILE` unchanged and report the blocker codes, affected artifacts, and affected sections. ## Outline -1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `REPO_FACTS_FILE`, and all five view paths. +1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `ARCH_VALIDATOR_FILE`, `ARCH_VALIDATOR_PS_FILE`, `REPO_FACTS_FILE`, and all five view paths. 2. Load `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_SCHEMA_FILE`, `architecture-physical-template.md`, and `architecture-template.md`. 3. Extract source-backed process collaborations, development boundaries, release constraints, and operational constraints. 4. Normalize deployment, external-system, fact-source, observability, and operations terminology. 5. Derive physical architecture boundaries and ownership constraints. 6. Classify each candidate as a supported physical conclusion or a physical gap under the schema and quality gates. 7. Render the schema-compliant physical working model with `architecture-physical-template.md`. -8. Apply the synthesis readiness rule. If all five view files are ready, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report the missing or not-ready views. +8. Run the readiness validator. If it returns `ready_gate: PASS`, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report validator blocker codes. 9. Report updated paths and explicit physical gaps. ## Quality Gates -- ERROR if the physical view contains Kubernetes YAML, cloud resource manifests, machine sizes, service SKUs, deployment scripts, runbooks, or concrete infrastructure configuration. -- ERROR if a target-view conclusion is not grounded in `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, or a stated constraint. -- Unsupported target-view conclusions MUST appear only in `Physical View Gaps`, not in conclusion tables. -- ERROR if a boundary has responsibilities but no explicit non-responsibility. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if the physical view contains Kubernetes YAML, cloud resource manifests, machine sizes, service SKUs, deployment scripts, runbooks, or concrete infrastructure configuration. +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, or a stated constraint. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if unsupported target-view conclusions appear in conclusion tables; place them only in `Physical View Gaps`. +- BLOCKER `ARCH_BOUNDARY_NONRESPONSIBILITY_MISSING` if a boundary has responsibilities but no explicit non-responsibility. - Record gaps instead of inventing topology or operations facts. diff --git a/extensions/arch/commands/speckit.arch.physical-reverse.md b/extensions/arch/commands/speckit.arch.physical-reverse.md index d7824b3fac..62e70e2190 100644 --- a/extensions/arch/commands/speckit.arch.physical-reverse.md +++ b/extensions/arch/commands/speckit.arch.physical-reverse.md @@ -11,7 +11,7 @@ scripts: $ARGUMENTS ``` -You **MUST** consider the user input before proceeding (if not empty). +You **MUST** consider the user input before proceeding (if not empty). In reverse workflows, user input may scope evidence collection or state explicit external constraints, but user input alone must not prove a reverse-generated architecture conclusion. ## Goal @@ -24,7 +24,7 @@ Reverse-generate or refresh the physical view from observable repository evidenc ## Operating Boundaries -- Write only `REPO_FACTS_FILE` and `PHYSICAL_VIEW`; update `ARCH_FILE` only if the five architecture views are already coherent enough to refresh synthesis without inventing content. +- Write only `REPO_FACTS_FILE` and `PHYSICAL_VIEW`; update `ARCH_FILE` only when the architecture readiness validator returns `ready_gate: PASS`. - Do not modify process/development views, source code, README files, docs, package files, configuration, tests, deployment files, specs, plans, tasks, infrastructure files, or runbooks. - Stay at abstract physical architecture level. - If repository evidence is insufficient, record a specific evidence gap and physical gap instead of inventing deployment units, external systems, fact sources, or operational constraints. @@ -37,11 +37,11 @@ Reverse-generate or refresh the physical view from observable repository evidenc Inspect Dockerfiles, Compose files, Kubernetes manifests, Terraform, CI/CD, environment examples, service configuration, deployment documentation, scripts, and observable external-system configuration. -Repository-First Inputs: if `.specify/memory/repository-first/` exists, inspect its markdown artifacts and summarize build manifest detection, first-party module edges, invocation governance, and dependency governance signals that affect deployment or external boundaries in `REPO_FACTS_FILE`. Repository-first content must not be copied verbatim into architecture views. +Repository-First Inputs: if `.specify/memory/repository-first/` exists, inspect only non-matrix markdown evidence that affects deployment or external boundaries, such as observable deployment entry points, external-system configuration, or runtime ownership signals, and summarize those signals in `REPO_FACTS_FILE`. Dependency matrices are owned by the development view; this command must not consume dependency matrices directly or treat them as a separate architecture view. Repository-first content must not be copied verbatim into architecture views. ## Supporting View Availability -`PROCESS_VIEW` and `DEVELOPMENT_VIEW` are available only when each file exists, does not contain `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion. Placeholder content and view gaps may identify missing context but must not support new physical conclusions. +`PROCESS_VIEW` and `DEVELOPMENT_VIEW` are available only when the readiness validator reports no blockers for those views such as missing artifact, placeholder marker, required-section, or traceability failures. Placeholder content and view gaps may identify missing context but must not support new physical conclusions. ## Repo Facts Merge Rule @@ -52,35 +52,36 @@ Treat `REPO_FACTS_FILE` as a cumulative evidence layer. Preserve existing non-pl - Every non-placeholder fact must name an evidence source such as a file, directory, configuration, test, script, manifest, command output, or commit signal. - Confidence values are `High`, `Medium`, or `Low`: `High` means multiple independent sources agree; `Medium` means one strong source is present; `Low` means naming, directory structure, isolated code, or Git history suggests a fact but lacks behavior evidence. - Git history is an auxiliary signal for change axes and boundary risks. It cannot independently prove architecture conclusions. -- Repository-first outputs are fact inputs. Summarize only architecture constraints, governance signals, gaps, or review triggers; do not copy full dependency inventories into architecture views. +- Repository-first outputs are fact inputs only when they match this command's physical evidence focus. Do not consume repository-first dependency matrices directly; use development-view dependency conclusions only after `DEVELOPMENT_VIEW` is synthesis-ready and relevant to deployment or external boundaries. - Concrete classes, functions, fields, endpoints, database tables, and implementation data structures may appear only as evidence sources, not architecture conclusions. -- Architecture conclusions must trace to repo facts, available supporting-view conclusions, user input, or stated external constraints. Unsupported items MUST appear only in `Evidence Gaps` or the target view gaps. +- Architecture conclusions must trace to repo facts, available supporting-view conclusions, or stated external constraints. If a conclusion is supported only by user input, report blocker code `ARCH_USER_INPUT_ONLY` and place it in `Evidence Gaps` or the target view gaps instead of conclusion tables. ## Structured Contract -`ARCH_SCHEMA_FILE` is the authoritative structural contract for architecture artifacts. Build JSON-compatible working models for `REPO_FACTS_FILE` and the target view, validate sections, traceability records, gaps, and `High` / `Medium` / `Low` confidence values against the schema, then render Markdown with the corresponding templates. The command owns evidence collection, classification, merge policy, validation, and write policy; templates own Markdown layout only. +`ARCH_SCHEMA_FILE` is the authoritative working-model contract for architecture artifacts. Use it to shape JSON-compatible working models for every file you update before rendering Markdown with the corresponding templates. `ARCH_VALIDATOR_FILE` and `ARCH_VALIDATOR_PS_FILE` provide the executable readiness gate for rendered artifacts. After rendering candidate changes, run the readiness validator and use its `ready_gate` and blocker codes as the only synthesis refresh decision. The command owns evidence extraction, classification, merge policy when applicable, and write routing; schemas own working-model structure; validators own rendered-artifact readiness; templates own Markdown layout only. ## Synthesis Readiness -Parse all five view paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, and `PHYSICAL_VIEW`. +Parse all five view paths and validator paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_VALIDATOR_FILE`, and `ARCH_VALIDATOR_PS_FILE`. -A view is ready for synthesis only when it exists, no longer contains `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion in its required sections. Unsupported or unknown items must be recorded in that view's gaps and do not make the view ready. Refresh `ARCH_FILE` only when all five views are ready and cross-view terminology is coherent. Otherwise leave `ARCH_FILE` unchanged and report the missing or not-ready views. +Synthesis readiness is validator-owned. Run `ARCH_VALIDATOR_FILE --json` (or `ARCH_VALIDATOR_PS_FILE -Json` in PowerShell-only environments) after rendering candidate view updates. Refresh `ARCH_FILE` only when the validator returns `ready_gate: PASS` with no blockers. If the validator returns `ready_gate: BLOCKED`, leave `ARCH_FILE` unchanged and report the blocker codes, affected artifacts, and affected sections. ## Outline -1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `REPO_FACTS_FILE`, and all five view paths. +1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `ARCH_VALIDATOR_FILE`, `ARCH_VALIDATOR_PS_FILE`, `REPO_FACTS_FILE`, and all five view paths. 2. Load `REPO_FACTS_FILE`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_SCHEMA_FILE`, `architecture-repo-facts-template.md`, `architecture-physical-template.md`, and `architecture-template.md`. 3. Refresh repo facts for this command's evidence focus and classify unsupported observations as evidence gaps. 4. Populate a schema-compliant physical working model from eligible repo facts plus `PROCESS_VIEW` and `DEVELOPMENT_VIEW` when they satisfy Supporting View Availability. 5. Put low-confidence facts in gaps rather than promoting them into physical conclusions. 6. Apply the repo facts merge rule before writing `REPO_FACTS_FILE`. -7. Apply the synthesis readiness rule. If all five view files are ready, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report the missing or not-ready views. +7. Run the readiness validator. If it returns `ready_gate: PASS`, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report validator blocker codes. 8. Report updated paths and explicit unresolved gaps. ## Quality Gates -- ERROR if the physical view promotes Kubernetes YAML, cloud resource manifests, machine sizes, service SKUs, deployment scripts, runbooks, or concrete infrastructure configuration into architecture conclusions. -- ERROR if a target-view conclusion lacks repo facts, available `PROCESS_VIEW`, available `DEVELOPMENT_VIEW`, or stated constraints. -- Unsupported target-view conclusions MUST appear only in `Evidence Gaps` or `Physical View Gaps`, not in conclusion tables. -- ERROR if Git history is used alone as a physical conclusion. -- GAP if deployment topology, external ownership, or operations cannot be supported by repository evidence. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if the physical view promotes Kubernetes YAML, cloud resource manifests, machine sizes, service SKUs, deployment scripts, runbooks, or concrete infrastructure configuration into architecture conclusions. +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks repo facts, available `PROCESS_VIEW`, available `DEVELOPMENT_VIEW`, or stated constraints. +- BLOCKER `ARCH_REPO_FIRST_MATRIX_MISUSED` if repository-first dependency matrices are copied into architecture views, treated as an independent architecture view, or used as direct non-development evidence. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if unsupported target-view conclusions appear in conclusion tables; place them only in `Evidence Gaps` or `Physical View Gaps`. +- BLOCKER `ARCH_GIT_HISTORY_ONLY` if Git history is used alone as a physical conclusion. +- BLOCKER `ARCH_SOURCE_MISSING` if deployment topology, external ownership, or operations cannot be supported by repository evidence; record the unsupported item in evidence gaps and target-view gaps. diff --git a/extensions/arch/commands/speckit.arch.process-generate.md b/extensions/arch/commands/speckit.arch.process-generate.md index e2819dd314..7a4472a35c 100644 --- a/extensions/arch/commands/speckit.arch.process-generate.md +++ b/extensions/arch/commands/speckit.arch.process-generate.md @@ -25,7 +25,7 @@ The process view derives runtime collaboration, handoffs, approvals, receipts, s ## Operating Boundaries -- Write only `PROCESS_VIEW`; update `ARCH_FILE` only if the five architecture views are already coherent enough to refresh synthesis without inventing content. +- Write only `PROCESS_VIEW`; update `ARCH_FILE` only when the architecture readiness validator returns `ready_gate: PASS`. - Do not read, populate, or update `REPO_FACTS_FILE`. - Do not modify scenario or logical views, source code, specs, plans, tasks, docs, tests, deployment files, or runbooks. - Stay at abstract runtime-collaboration architecture level. @@ -39,30 +39,30 @@ If setup creates `REPO_FACTS_FILE`, leave it as-is. Do not read it as input and ## Structured Contract -`ARCH_SCHEMA_FILE` is the authoritative structural contract for architecture artifacts. Build a JSON-compatible working model for every file you update, validate required sections, traceability records, gaps, and `High` / `Medium` / `Low` confidence values against the schema, then render Markdown with the corresponding template. The command owns extraction, classification, validation, and write policy; templates own Markdown layout only. +`ARCH_SCHEMA_FILE` is the authoritative working-model contract for architecture artifacts. Use it to shape JSON-compatible working models for every file you update before rendering Markdown with the corresponding templates. `ARCH_VALIDATOR_FILE` and `ARCH_VALIDATOR_PS_FILE` provide the executable readiness gate for rendered artifacts. After rendering candidate changes, run the readiness validator and use its `ready_gate` and blocker codes as the only synthesis refresh decision. The command owns evidence extraction, classification, merge policy when applicable, and write routing; schemas own working-model structure; validators own rendered-artifact readiness; templates own Markdown layout only. ## Synthesis Readiness -Parse all five view paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, and `PHYSICAL_VIEW`. +Parse all five view paths and validator paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_VALIDATOR_FILE`, and `ARCH_VALIDATOR_PS_FILE`. -A view is ready for synthesis only when it exists, no longer contains `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion in its required sections. Unsupported or unknown items must be recorded in that view's gaps and do not make the view ready. Refresh `ARCH_FILE` only when all five views are ready and cross-view terminology is coherent. Otherwise leave `ARCH_FILE` unchanged and report the missing or not-ready views. +Synthesis readiness is validator-owned. Run `ARCH_VALIDATOR_FILE --json` (or `ARCH_VALIDATOR_PS_FILE -Json` in PowerShell-only environments) after rendering candidate view updates. Refresh `ARCH_FILE` only when the validator returns `ready_gate: PASS` with no blockers. If the validator returns `ready_gate: BLOCKED`, leave `ARCH_FILE` unchanged and report the blocker codes, affected artifacts, and affected sections. ## Outline -1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `REPO_FACTS_FILE`, and all five view paths. +1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `ARCH_VALIDATOR_FILE`, `ARCH_VALIDATOR_PS_FILE`, `REPO_FACTS_FILE`, and all five view paths. 2. Load `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `ARCH_SCHEMA_FILE`, `architecture-process-template.md`, and `architecture-template.md`. 3. Extract source-backed scenario paths, logical boundaries, states, and invariants. 4. Normalize runtime participant, handoff, receipt, and failure-closure terminology. 5. Derive runtime collaboration boundaries and completion conditions. 6. Classify each candidate as a supported process conclusion or a process gap under the schema and quality gates. 7. Render the schema-compliant process working model with `architecture-process-template.md`. -8. Apply the synthesis readiness rule. If all five view files are ready, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report the missing or not-ready views. +8. Run the readiness validator. If it returns `ready_gate: PASS`, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report validator blocker codes. 9. Report updated paths and explicit process gaps. ## Quality Gates -- ERROR if the process view contains call stacks, queue names, retry counts, endpoint sequences, workflow engine configuration, or orchestration code. -- ERROR if a target-view conclusion is not grounded in a scenario path, logical boundary, or stated constraint. -- Unsupported target-view conclusions MUST appear only in `Process Gaps`, not in conclusion tables. -- ERROR if a boundary has responsibilities but no explicit non-responsibility. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if the process view contains call stacks, queue names, retry counts, endpoint sequences, workflow engine configuration, or orchestration code. +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks a scenario path, logical boundary, or stated constraint. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if unsupported target-view conclusions appear in conclusion tables; place them only in `Process Gaps`. +- BLOCKER `ARCH_BOUNDARY_NONRESPONSIBILITY_MISSING` if a boundary has responsibilities but no explicit non-responsibility. - Record gaps instead of inventing runtime ownership or operational behavior. diff --git a/extensions/arch/commands/speckit.arch.process-reverse.md b/extensions/arch/commands/speckit.arch.process-reverse.md index ecd04e64d2..4b6140aa24 100644 --- a/extensions/arch/commands/speckit.arch.process-reverse.md +++ b/extensions/arch/commands/speckit.arch.process-reverse.md @@ -11,7 +11,7 @@ scripts: $ARGUMENTS ``` -You **MUST** consider the user input before proceeding (if not empty). +You **MUST** consider the user input before proceeding (if not empty). In reverse workflows, user input may scope evidence collection or state explicit external constraints, but user input alone must not prove a reverse-generated architecture conclusion. ## Goal @@ -24,7 +24,7 @@ Reverse-generate or refresh the process view from observable repository evidence ## Operating Boundaries -- Write only `REPO_FACTS_FILE` and `PROCESS_VIEW`; update `ARCH_FILE` only if the five architecture views are already coherent enough to refresh synthesis without inventing content. +- Write only `REPO_FACTS_FILE` and `PROCESS_VIEW`; update `ARCH_FILE` only when the architecture readiness validator returns `ready_gate: PASS`. - Do not modify scenario/logical views, source code, README files, docs, package files, configuration, tests, deployment files, specs, plans, tasks, or runbooks. - Stay at abstract runtime-collaboration architecture level. - If repository evidence is insufficient, record a specific evidence gap and process gap instead of inventing runtime links, handoffs, retries, or failure closure. @@ -37,11 +37,11 @@ Reverse-generate or refresh the process view from observable repository evidence Inspect workers, schedulers, middleware, async jobs, event handlers, transactions, retries, locks, route behavior, tests, examples, configuration, and CI/runtime scripts. -Repository-First Inputs: if `.specify/memory/repository-first/` exists, inspect its markdown artifacts and summarize build manifest detection, first-party module edges, invocation governance, and dependency governance signals that affect runtime boundaries in `REPO_FACTS_FILE`. Repository-first content must not be copied verbatim into architecture views. +Repository-First Inputs: if `.specify/memory/repository-first/` exists, inspect only non-matrix markdown evidence that affects runtime boundaries, such as observable invocation constraints, worker entry points, or runtime ownership signals, and summarize those signals in `REPO_FACTS_FILE`. Dependency matrices are owned by the development view; this command must not consume dependency matrices directly or treat them as a separate architecture view. Repository-first content must not be copied verbatim into architecture views. ## Supporting View Availability -`SCENARIO_VIEW` and `LOGICAL_VIEW` are available only when each file exists, does not contain `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion. Placeholder content and view gaps may identify missing context but must not support new process conclusions. +`SCENARIO_VIEW` and `LOGICAL_VIEW` are available only when the readiness validator reports no blockers for those views such as missing artifact, placeholder marker, required-section, or traceability failures. Placeholder content and view gaps may identify missing context but must not support new process conclusions. ## Repo Facts Merge Rule @@ -52,35 +52,36 @@ Treat `REPO_FACTS_FILE` as a cumulative evidence layer. Preserve existing non-pl - Every non-placeholder fact must name an evidence source such as a file, directory, configuration, test, script, manifest, command output, or commit signal. - Confidence values are `High`, `Medium`, or `Low`: `High` means multiple independent sources agree; `Medium` means one strong source is present; `Low` means naming, directory structure, isolated code, or Git history suggests a fact but lacks behavior evidence. - Git history is an auxiliary signal for change axes and boundary risks. It cannot independently prove architecture conclusions. -- Repository-first outputs are fact inputs. Summarize only architecture constraints, governance signals, gaps, or review triggers; do not copy full dependency inventories into architecture views. +- Repository-first outputs are fact inputs only when they match this command's process evidence focus. Do not consume repository-first dependency matrices directly; use development-view dependency conclusions only after `DEVELOPMENT_VIEW` is synthesis-ready and relevant to runtime boundaries. - Concrete classes, functions, fields, endpoints, database tables, and implementation data structures may appear only as evidence sources, not architecture conclusions. -- Architecture conclusions must trace to repo facts, available supporting-view conclusions, user input, or stated external constraints. Unsupported items MUST appear only in `Evidence Gaps` or the target view gaps. +- Architecture conclusions must trace to repo facts, available supporting-view conclusions, or stated external constraints. If a conclusion is supported only by user input, report blocker code `ARCH_USER_INPUT_ONLY` and place it in `Evidence Gaps` or the target view gaps instead of conclusion tables. ## Structured Contract -`ARCH_SCHEMA_FILE` is the authoritative structural contract for architecture artifacts. Build JSON-compatible working models for `REPO_FACTS_FILE` and the target view, validate sections, traceability records, gaps, and `High` / `Medium` / `Low` confidence values against the schema, then render Markdown with the corresponding templates. The command owns evidence collection, classification, merge policy, validation, and write policy; templates own Markdown layout only. +`ARCH_SCHEMA_FILE` is the authoritative working-model contract for architecture artifacts. Use it to shape JSON-compatible working models for every file you update before rendering Markdown with the corresponding templates. `ARCH_VALIDATOR_FILE` and `ARCH_VALIDATOR_PS_FILE` provide the executable readiness gate for rendered artifacts. After rendering candidate changes, run the readiness validator and use its `ready_gate` and blocker codes as the only synthesis refresh decision. The command owns evidence extraction, classification, merge policy when applicable, and write routing; schemas own working-model structure; validators own rendered-artifact readiness; templates own Markdown layout only. ## Synthesis Readiness -Parse all five view paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, and `PHYSICAL_VIEW`. +Parse all five view paths and validator paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_VALIDATOR_FILE`, and `ARCH_VALIDATOR_PS_FILE`. -A view is ready for synthesis only when it exists, no longer contains `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion in its required sections. Unsupported or unknown items must be recorded in that view's gaps and do not make the view ready. Refresh `ARCH_FILE` only when all five views are ready and cross-view terminology is coherent. Otherwise leave `ARCH_FILE` unchanged and report the missing or not-ready views. +Synthesis readiness is validator-owned. Run `ARCH_VALIDATOR_FILE --json` (or `ARCH_VALIDATOR_PS_FILE -Json` in PowerShell-only environments) after rendering candidate view updates. Refresh `ARCH_FILE` only when the validator returns `ready_gate: PASS` with no blockers. If the validator returns `ready_gate: BLOCKED`, leave `ARCH_FILE` unchanged and report the blocker codes, affected artifacts, and affected sections. ## Outline -1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `REPO_FACTS_FILE`, and all five view paths. +1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `ARCH_VALIDATOR_FILE`, `ARCH_VALIDATOR_PS_FILE`, `REPO_FACTS_FILE`, and all five view paths. 2. Load `REPO_FACTS_FILE`, `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `ARCH_SCHEMA_FILE`, `architecture-repo-facts-template.md`, `architecture-process-template.md`, and `architecture-template.md`. 3. Refresh repo facts for this command's evidence focus and classify unsupported observations as evidence gaps. 4. Populate a schema-compliant process working model from eligible repo facts plus `SCENARIO_VIEW` and `LOGICAL_VIEW` when they satisfy Supporting View Availability. 5. Put low-confidence facts in gaps rather than promoting them into process conclusions. 6. Apply the repo facts merge rule before writing `REPO_FACTS_FILE`. -7. Apply the synthesis readiness rule. If all five view files are ready, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report the missing or not-ready views. +7. Run the readiness validator. If it returns `ready_gate: PASS`, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report validator blocker codes. 8. Report updated paths and explicit unresolved gaps. ## Quality Gates -- ERROR if the process view promotes call stacks, queue names, retry counts, thread/process details, endpoint sequences, workflow engine config, or orchestration code into architecture conclusions. -- ERROR if a target-view conclusion lacks a repo fact, available `SCENARIO_VIEW` or `LOGICAL_VIEW` source, or stated constraint. -- Unsupported target-view conclusions MUST appear only in `Evidence Gaps` or `Process Gaps`, not in conclusion tables. -- ERROR if Git history is used alone as a process conclusion. -- GAP if runtime ownership, handoffs, or failure closure cannot be supported by repository evidence. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if the process view promotes call stacks, queue names, retry counts, thread/process details, endpoint sequences, workflow engine config, or orchestration code into architecture conclusions. +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks a repo fact, available `SCENARIO_VIEW` or `LOGICAL_VIEW` source, or stated constraint. +- BLOCKER `ARCH_REPO_FIRST_MATRIX_MISUSED` if repository-first dependency matrices are copied into architecture views, treated as an independent architecture view, or used as direct non-development evidence. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if unsupported target-view conclusions appear in conclusion tables; place them only in `Evidence Gaps` or `Process Gaps`. +- BLOCKER `ARCH_GIT_HISTORY_ONLY` if Git history is used alone as a process conclusion. +- BLOCKER `ARCH_SOURCE_MISSING` if runtime ownership, handoffs, or failure closure cannot be supported by repository evidence; record the unsupported item in evidence gaps and target-view gaps. diff --git a/extensions/arch/commands/speckit.arch.scenario-generate.md b/extensions/arch/commands/speckit.arch.scenario-generate.md index 4a28eee4db..cfeb341cfd 100644 --- a/extensions/arch/commands/speckit.arch.scenario-generate.md +++ b/extensions/arch/commands/speckit.arch.scenario-generate.md @@ -24,7 +24,7 @@ This is the `+1` view in 4+1 architecture. It produces actor, goal, use-case, pa ## Operating Boundaries -- Write only `SCENARIO_VIEW`; update `ARCH_FILE` only if the five architecture views are already coherent enough to refresh synthesis without inventing content. +- Write only `SCENARIO_VIEW`; update `ARCH_FILE` only when the architecture readiness validator returns `ready_gate: PASS`. - Do not read, populate, or update `REPO_FACTS_FILE`. - Read `.specify/memory/uc.md` only as optional scenario background. - Do not modify `.specify/memory/uc.md`, `.specify/memory/constitution.md`, feature specs, plans, tasks, source code, tests, root `docs/`, deployment manifests, or runbooks. @@ -39,30 +39,30 @@ If setup creates `REPO_FACTS_FILE`, leave it as-is. Do not read it as input and ## Structured Contract -`ARCH_SCHEMA_FILE` is the authoritative structural contract for architecture artifacts. Build a JSON-compatible working model for every file you update, validate required sections, traceability records, gaps, and `High` / `Medium` / `Low` confidence values against the schema, then render Markdown with the corresponding template. The command owns extraction, classification, validation, and write policy; templates own Markdown layout only. +`ARCH_SCHEMA_FILE` is the authoritative working-model contract for architecture artifacts. Use it to shape JSON-compatible working models for every file you update before rendering Markdown with the corresponding templates. `ARCH_VALIDATOR_FILE` and `ARCH_VALIDATOR_PS_FILE` provide the executable readiness gate for rendered artifacts. After rendering candidate changes, run the readiness validator and use its `ready_gate` and blocker codes as the only synthesis refresh decision. The command owns evidence extraction, classification, merge policy when applicable, and write routing; schemas own working-model structure; validators own rendered-artifact readiness; templates own Markdown layout only. ## Synthesis Readiness -Parse all five view paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, and `PHYSICAL_VIEW`. +Parse all five view paths and validator paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_VALIDATOR_FILE`, and `ARCH_VALIDATOR_PS_FILE`. -A view is ready for synthesis only when it exists, no longer contains `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion in its required sections. Unsupported or unknown items must be recorded in that view's gaps and do not make the view ready. Refresh `ARCH_FILE` only when all five views are ready and cross-view terminology is coherent. Otherwise leave `ARCH_FILE` unchanged and report the missing or not-ready views. +Synthesis readiness is validator-owned. Run `ARCH_VALIDATOR_FILE --json` (or `ARCH_VALIDATOR_PS_FILE -Json` in PowerShell-only environments) after rendering candidate view updates. Refresh `ARCH_FILE` only when the validator returns `ready_gate: PASS` with no blockers. If the validator returns `ready_gate: BLOCKED`, leave `ARCH_FILE` unchanged and report the blocker codes, affected artifacts, and affected sections. ## Outline -1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `REPO_FACTS_FILE`, and all five view paths. +1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `ARCH_VALIDATOR_FILE`, `ARCH_VALIDATOR_PS_FILE`, `REPO_FACTS_FILE`, and all five view paths. 2. Load `SCENARIO_VIEW`, `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `architecture-scenario-template.md`, and `architecture-template.md`. 3. Load `.specify/memory/uc.md` if present as supporting context. 4. Extract source-backed actors, goals, triggers, paths, branches, and acceptance semantics. 5. Normalize scenario terminology and derive scenario-level boundaries. 6. Classify each candidate as a supported scenario conclusion or a scenario gap under the schema and quality gates. 7. Render the schema-compliant scenario working model with `architecture-scenario-template.md`. -8. Apply the synthesis readiness rule. If all five view files are ready, refresh `ARCH_FILE` using `architecture-template.md`; otherwise leave synthesis untouched and report the missing or not-ready views. +8. Run the readiness validator. If it returns `ready_gate: PASS`, refresh `ARCH_FILE` using `architecture-template.md`; otherwise leave synthesis untouched and report validator blocker codes. 9. Report updated paths and explicit scenario gaps. ## Quality Gates -- ERROR if the scenario view contains implementation details, components, APIs, database tables, deployment scripts, or task plans. -- ERROR if a target-view conclusion has no stated scenario source, user input source, or existing memory source. -- Unsupported target-view conclusions MUST appear only in `Scenario Gaps`, not in conclusion tables. -- ERROR if a boundary has responsibilities but no explicit non-responsibility. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if the scenario view contains implementation details, components, APIs, database tables, deployment scripts, or task plans. +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks stated scenario source, user input source, or existing memory source. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if unsupported target-view conclusions appear in conclusion tables; place them only in `Scenario Gaps`. +- BLOCKER `ARCH_BOUNDARY_NONRESPONSIBILITY_MISSING` if a boundary has responsibilities but no explicit non-responsibility. - Record gaps instead of inventing business facts. diff --git a/extensions/arch/commands/speckit.arch.scenario-reverse.md b/extensions/arch/commands/speckit.arch.scenario-reverse.md index ca378951e3..18d316cdbb 100644 --- a/extensions/arch/commands/speckit.arch.scenario-reverse.md +++ b/extensions/arch/commands/speckit.arch.scenario-reverse.md @@ -11,7 +11,7 @@ scripts: $ARGUMENTS ``` -You **MUST** consider the user input before proceeding (if not empty). +You **MUST** consider the user input before proceeding (if not empty). In reverse workflows, user input may scope evidence collection or state explicit external constraints, but user input alone must not prove a reverse-generated architecture conclusion. ## Goal @@ -23,7 +23,7 @@ Reverse-generate or refresh the scenario view from observable repository evidenc ## Operating Boundaries -- Write only `REPO_FACTS_FILE` and `SCENARIO_VIEW`; update `ARCH_FILE` only if the five architecture views are already coherent enough to refresh synthesis without inventing content. +- Write only `REPO_FACTS_FILE` and `SCENARIO_VIEW`; update `ARCH_FILE` only when the architecture readiness validator returns `ready_gate: PASS`. - Do not modify source code, README files, project documentation, package files, configuration, tests, deployment files, `.specify/memory/uc.md`, `.specify/memory/constitution.md`, feature specs, plans, tasks, root `docs/`, deployment manifests, or runbooks. - Stay at abstract architecture-design level. - If repository evidence is insufficient, record a specific evidence gap and scenario gap instead of inventing actors, use cases, business meaning, or acceptance semantics. @@ -36,7 +36,7 @@ Reverse-generate or refresh the scenario view from observable repository evidenc Inspect README/docs, CLI/API entry points, examples, tests, route declarations, configuration, package manifests, and user-visible behavior descriptions. Infer target-view conclusions only from user-visible behavior, explicit documentation, or stated external constraints. Prefer concise inventory over exhaustive source listing. -Repository-First Inputs: if `.specify/memory/repository-first/` exists, inspect its markdown artifacts and summarize build manifest detection, first-party module edges, invocation governance, and dependency governance signals that affect scenario meaning in `REPO_FACTS_FILE`. Repository-first content must not be copied verbatim into architecture views. +Repository-First Inputs: if `.specify/memory/repository-first/` exists, inspect only non-matrix markdown evidence that affects scenario meaning, such as user-visible entry points, examples, or stated invocation constraints, and summarize those signals in `REPO_FACTS_FILE`. Dependency matrices are owned by the development view; this command must not consume dependency matrices directly or treat them as a separate architecture view. Repository-first content must not be copied verbatim into architecture views. ## Repo Facts Merge Rule @@ -47,34 +47,36 @@ Treat `REPO_FACTS_FILE` as a cumulative evidence layer. Preserve existing non-pl - Every non-placeholder fact must name an evidence source such as a file, directory, configuration, test, script, manifest, command output, or commit signal. - Confidence values are `High`, `Medium`, or `Low`: `High` means multiple independent sources agree; `Medium` means one strong source is present; `Low` means naming, directory structure, isolated code, or Git history suggests a fact but lacks behavior evidence. - Git history is an auxiliary signal for change axes and boundary risks. It cannot independently prove architecture conclusions. -- Repository-first outputs are fact inputs. Summarize only architecture constraints, governance signals, gaps, or review triggers; do not copy full dependency inventories into architecture views. +- Repository-first outputs are fact inputs only when they match this command's scenario evidence focus. Do not consume repository-first dependency matrices directly; use development-view dependency conclusions only after `DEVELOPMENT_VIEW` is synthesis-ready and relevant to scenario meaning. - Concrete classes, functions, fields, endpoints, database tables, and implementation data structures may appear only as evidence sources, not architecture conclusions. -- Architecture conclusions must trace to repo facts, user input, or stated external constraints. Unsupported items MUST appear only in `Evidence Gaps` or the target view gaps. +- Architecture conclusions must trace to repo facts or stated external constraints. If a conclusion is supported only by user input, report blocker code `ARCH_USER_INPUT_ONLY` and place it in `Evidence Gaps` or the target view gaps instead of conclusion tables. ## Structured Contract -`ARCH_SCHEMA_FILE` is the authoritative structural contract for architecture artifacts. Build JSON-compatible working models for `REPO_FACTS_FILE` and the target view, validate sections, traceability records, gaps, and `High` / `Medium` / `Low` confidence values against the schema, then render Markdown with the corresponding templates. The command owns evidence collection, classification, merge policy, validation, and write policy; templates own Markdown layout only. +`ARCH_SCHEMA_FILE` is the authoritative working-model contract for architecture artifacts. Use it to shape JSON-compatible working models for every file you update before rendering Markdown with the corresponding templates. `ARCH_VALIDATOR_FILE` and `ARCH_VALIDATOR_PS_FILE` provide the executable readiness gate for rendered artifacts. After rendering candidate changes, run the readiness validator and use its `ready_gate` and blocker codes as the only synthesis refresh decision. The command owns evidence extraction, classification, merge policy when applicable, and write routing; schemas own working-model structure; validators own rendered-artifact readiness; templates own Markdown layout only. ## Synthesis Readiness -Parse all five view paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, and `PHYSICAL_VIEW`. +Parse all five view paths and validator paths from setup JSON: `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, `ARCH_VALIDATOR_FILE`, and `ARCH_VALIDATOR_PS_FILE`. -A view is ready for synthesis only when it exists, no longer contains `NEEDS ARCH UPDATE`, and contains at least one source-backed non-gap architecture conclusion in its required sections. Unsupported or unknown items must be recorded in that view's gaps and do not make the view ready. Refresh `ARCH_FILE` only when all five views are ready and cross-view terminology is coherent. Otherwise leave `ARCH_FILE` unchanged and report the missing or not-ready views. +Synthesis readiness is validator-owned. Run `ARCH_VALIDATOR_FILE --json` (or `ARCH_VALIDATOR_PS_FILE -Json` in PowerShell-only environments) after rendering candidate view updates. Refresh `ARCH_FILE` only when the validator returns `ready_gate: PASS` with no blockers. If the validator returns `ready_gate: BLOCKED`, leave `ARCH_FILE` unchanged and report the blocker codes, affected artifacts, and affected sections. ## Outline -1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `REPO_FACTS_FILE`, and all five view paths. +1. Run `{SCRIPT}` from repo root and parse JSON for `ARCH_FILE`, `ARCH_SCHEMA_FILE`, `ARCH_VALIDATOR_FILE`, `ARCH_VALIDATOR_PS_FILE`, `REPO_FACTS_FILE`, and all five view paths. 2. Load `REPO_FACTS_FILE`, `SCENARIO_VIEW`, `ARCH_SCHEMA_FILE`, `architecture-repo-facts-template.md`, `architecture-scenario-template.md`, and `architecture-template.md`. 3. Refresh repo facts for this command's evidence focus and classify unsupported observations as evidence gaps. 4. Populate a schema-compliant scenario working model from high- or medium-confidence facts. 5. Put low-confidence or missing business meaning in evidence gaps and scenario gaps. 6. Apply the repo facts merge rule before writing `REPO_FACTS_FILE`. -7. Apply the synthesis readiness rule. If all five view files are ready, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report the missing or not-ready views. +7. Run the readiness validator. If it returns `ready_gate: PASS`, refresh `ARCH_FILE`; otherwise leave synthesis untouched and report validator blocker codes. 8. Report updated paths and explicit unresolved gaps. ## Quality Gates -- ERROR if a target-view conclusion has no repo fact source or stated external constraint source. -- ERROR if the repo facts file contains generic claims without file paths, directories, configuration, tests, commands, or commit signals. -- ERROR if Git history is used alone as a scenario conclusion. -- GAP if actors, goals, or business meaning cannot be supported by repository evidence. +- BLOCKER `ARCH_SOURCE_MISSING` if a conclusion or dependency matrix entry lacks a repo fact source or stated external constraint source. +- BLOCKER `ARCH_SOURCE_MISSING` if the repo facts file contains generic claims without file paths, directories, configuration, tests, commands, or commit signals. +- BLOCKER `ARCH_REPO_FIRST_MATRIX_MISUSED` if repository-first dependency matrices are copied into architecture views, treated as an independent architecture view, or used as direct non-development evidence. +- BLOCKER `ARCH_UNSUPPORTED_CONCLUSION` if unsupported target-view conclusions appear in conclusion tables; place them only in `Evidence Gaps` or `Scenario Gaps`. +- BLOCKER `ARCH_GIT_HISTORY_ONLY` if Git history is used alone as a scenario conclusion. +- BLOCKER `ARCH_SOURCE_MISSING` if actors, goals, or business meaning cannot be supported by repository evidence; record the unsupported item in evidence gaps and target-view gaps. diff --git a/extensions/arch/extension.yml b/extensions/arch/extension.yml index 2a1bfdb0fd..79f4c03cd2 100644 --- a/extensions/arch/extension.yml +++ b/extensions/arch/extension.yml @@ -3,8 +3,8 @@ schema_version: "1.0" extension: id: arch name: "Architecture Workflow" - version: "1.2.1" - description: "Generate or reverse project-level 4+1 architecture views as separate commands" + version: "1.2.2" + description: "Generate or reverse project-level 4+1 architecture views with per-view and full-workflow commands" author: bigsmartben repository: https://github.com/bigsmartben/spec-kit-arch homepage: https://github.com/bigsmartben/spec-kit-arch @@ -26,10 +26,16 @@ provides: description: "Generate the 4+1 process view from scenario and logical architecture views" - name: speckit.arch.development-generate file: commands/speckit.arch.development-generate.md - description: "Generate the 4+1 development view from logical and process architecture views" + description: "Generate the 4+1 development view and required dependency matrix from logical and process architecture views" - name: speckit.arch.physical-generate file: commands/speckit.arch.physical-generate.md description: "Generate the 4+1 physical view from process and development architecture views" + - name: speckit.arch.full-generate + file: commands/speckit.arch.full-generate.md + description: "Generate all 4+1 architecture views and the architecture synthesis from intended project context" + - name: speckit.arch.full-reverse + file: commands/speckit.arch.full-reverse.md + description: "Reverse-generate all 4+1 architecture views and the architecture synthesis from observable repository facts" - name: speckit.arch.scenario-reverse file: commands/speckit.arch.scenario-reverse.md description: "Reverse-generate the 4+1 scenario view from observable repository facts" @@ -41,7 +47,7 @@ provides: description: "Reverse-generate the 4+1 process view from observable repository facts" - name: speckit.arch.development-reverse file: commands/speckit.arch.development-reverse.md - description: "Reverse-generate the 4+1 development view from observable repository facts" + description: "Reverse-generate the 4+1 development view and required dependency matrix from observable repository facts" - name: speckit.arch.physical-reverse file: commands/speckit.arch.physical-reverse.md description: "Reverse-generate the 4+1 physical view from observable repository facts" diff --git a/extensions/arch/presets/arch-governance/README.md b/extensions/arch/presets/arch-governance/README.md deleted file mode 100644 index ce59670585..0000000000 --- a/extensions/arch/presets/arch-governance/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Architecture Governance Preset - -Wraps the core `/speckit.plan` workflow with architecture SSOT grounding. - -Install from this repository: - -```bash -specify preset add --dev /home/administrator/github/spec-kit-arch/presets/arch-governance -``` - -The preset does not override `/speckit.tasks` or `/speckit.implement`. diff --git a/extensions/arch/presets/arch-governance/commands/speckit.plan.md b/extensions/arch/presets/arch-governance/commands/speckit.plan.md deleted file mode 100644 index 425e1a4d14..0000000000 --- a/extensions/arch/presets/arch-governance/commands/speckit.plan.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -description: Wrap the core planning workflow with architecture SSOT grounding. -strategy: wrap ---- - -## Architecture SSOT Injection - -Before running the core planning workflow, inspect these project-level architecture files if they exist: - -- `.specify/memory/architecture.md` -- `.specify/memory/architecture-scenario-view.md` -- `.specify/memory/architecture-logical-view.md` -- `.specify/memory/architecture-process-view.md` -- `.specify/memory/architecture-development-view.md` -- `.specify/memory/architecture-physical-view.md` - -This wrapper is a non-invasive context injection. The core planning workflow remains responsible for setup, feature analysis, technical research, design artifacts, contracts, agent-context updates, and plan reporting. - -Do not change the core planning phases, required artifacts, scripts, constitution checks, research process, or output paths. Do not introduce new `ERROR` gates beyond the core planning gates. - -If none of these files exist, continue with the core planning workflow without adding an architecture grounding section solely for the missing files. - -If one or more files exist: - -- Treat them as the architecture grounding for this planning pass: the plan must reason within the SSOT's architecture intent, boundaries, constraints, anti-patterns, and unresolved gaps. -- Extract only architecture-level conclusions: intent, stable boundaries, forbidden crossings, change axes, anti-patterns, invariants, open risks, and review triggers. -- Do not invent architecture facts when files still contain `NEEDS ARCH UPDATE`; carry the unresolved item into the plan. -- If the feature direction conflicts with the architecture SSOT, make the conflict explicit in the plan and identify the resolution path: refresh the architecture SSOT or adjust the feature plan. -- Do not run `/speckit.arch.generate` automatically. - -The plan output MUST include an `Architecture Grounding` section when architecture files are present. That section is not an audit report; it records how the plan reasoning is bounded by the architecture SSOT: - -- Architecture files read -- Applicable stable boundaries and forbidden crossings -- Architecture constraints or unresolved gaps that bound the plan -- Conflicts, if any, that prevent valid planning inside the current architecture SSOT, plus the required resolution path -- Architecture drift risks to watch during implementation - -{CORE_TEMPLATE} - -## Architecture Grounding Summary - -Before finishing, summarize how architecture SSOT grounded the generated plan: - -- If no architecture files were present, state that the core plan continued without architecture SSOT input. -- If architecture files were present, summarize the boundaries, forbidden crossings, unresolved architecture gaps, conflicts, and drift risks that bounded the plan reasoning. -- Do not modify architecture files from this command. diff --git a/extensions/arch/presets/arch-governance/preset.yml b/extensions/arch/presets/arch-governance/preset.yml deleted file mode 100644 index 82bf605fbf..0000000000 --- a/extensions/arch/presets/arch-governance/preset.yml +++ /dev/null @@ -1,28 +0,0 @@ -schema_version: "1.0" - -preset: - id: "arch-governance" - name: "Architecture Governance" - version: "1.0.0" - description: "Inject project architecture SSOT into the core planning workflow" - author: "bigsmartben" - repository: "https://github.com/bigsmartben/spec-kit-arch" - license: "MIT" - -requires: - speckit_version: ">=0.8.9.dev0" - -provides: - templates: - - type: "command" - name: "speckit.plan" - file: "commands/speckit.plan.md" - description: "Wrap core planning with architecture SSOT grounding" - replaces: "speckit.plan" - strategy: "wrap" - -tags: - - "architecture" - - "governance" - - "planning" - - "ssot" diff --git a/extensions/arch/schemas/architecture-artifacts.schema.json b/extensions/arch/schemas/architecture-artifacts.schema.json index e970065047..92e5fa15d3 100644 --- a/extensions/arch/schemas/architecture-artifacts.schema.json +++ b/extensions/arch/schemas/architecture-artifacts.schema.json @@ -9,7 +9,8 @@ "project", "sections", "traceability", - "gaps" + "gaps", + "readiness" ], "properties": { "artifactType": { @@ -54,8 +55,327 @@ "items": { "$ref": "#/$defs/gap" } + }, + "readiness": { + "$ref": "#/$defs/readiness" } }, + "allOf": [ + { + "if": { + "properties": { + "artifactType": { + "const": "architecture-synthesis" + } + }, + "required": [ + "artifactType" + ] + }, + "then": { + "properties": { + "sections": { + "allOf": [ + { + "$ref": "#/$defs/section-view-index" + }, + { + "$ref": "#/$defs/section-architecture-intent" + }, + { + "$ref": "#/$defs/section-central-design-forces" + }, + { + "$ref": "#/$defs/section-primary-tradeoffs" + }, + { + "$ref": "#/$defs/section-stable-boundaries" + }, + { + "$ref": "#/$defs/section-change-axes" + }, + { + "$ref": "#/$defs/section-anti-patterns" + }, + { + "$ref": "#/$defs/section-cross-view-architecture-model" + }, + { + "$ref": "#/$defs/section-key-architecture-conclusions" + }, + { + "$ref": "#/$defs/section-cross-cutting-constraints" + }, + { + "$ref": "#/$defs/section-open-risks-and-review-triggers" + } + ] + } + } + } + }, + { + "if": { + "properties": { + "artifactType": { + "const": "repo-facts" + } + }, + "required": [ + "artifactType" + ] + }, + "then": { + "properties": { + "sections": { + "allOf": [ + { + "$ref": "#/$defs/section-repository-identity" + }, + { + "$ref": "#/$defs/section-entry-points" + }, + { + "$ref": "#/$defs/section-user-visible-behaviors" + }, + { + "$ref": "#/$defs/section-system-boundaries" + }, + { + "$ref": "#/$defs/section-data-and-state-clues" + }, + { + "$ref": "#/$defs/section-runtime-and-process-clues" + }, + { + "$ref": "#/$defs/section-development-structure-clues" + }, + { + "$ref": "#/$defs/section-repository-first-projection" + }, + { + "$ref": "#/$defs/section-physical-deployment-clues" + }, + { + "$ref": "#/$defs/section-git-history-signals" + }, + { + "$ref": "#/$defs/section-evidence-gaps" + } + ] + } + } + } + }, + { + "if": { + "properties": { + "artifactType": { + "const": "scenario-view" + } + }, + "required": [ + "artifactType" + ] + }, + "then": { + "properties": { + "sections": { + "allOf": [ + { + "$ref": "#/$defs/view-common-sections" + }, + { + "$ref": "#/$defs/section-actors-and-participants" + }, + { + "$ref": "#/$defs/section-use-cases" + }, + { + "$ref": "#/$defs/section-scenario-paths" + }, + { + "$ref": "#/$defs/section-acceptance-semantics" + }, + { + "$ref": "#/$defs/section-source-traceability" + }, + { + "$ref": "#/$defs/section-scenario-gaps" + } + ] + } + } + } + }, + { + "if": { + "properties": { + "artifactType": { + "const": "logical-view" + } + }, + "required": [ + "artifactType" + ] + }, + "then": { + "properties": { + "sections": { + "allOf": [ + { + "$ref": "#/$defs/view-common-sections" + }, + { + "$ref": "#/$defs/section-capability-boundaries" + }, + { + "$ref": "#/$defs/section-domain-objects-and-relationships" + }, + { + "$ref": "#/$defs/section-state-and-lifecycle" + }, + { + "$ref": "#/$defs/section-logical-decisions" + }, + { + "$ref": "#/$defs/section-source-traceability" + }, + { + "$ref": "#/$defs/section-logical-gaps" + } + ] + } + } + } + }, + { + "if": { + "properties": { + "artifactType": { + "const": "process-view" + } + }, + "required": [ + "artifactType" + ] + }, + "then": { + "properties": { + "sections": { + "allOf": [ + { + "$ref": "#/$defs/view-common-sections" + }, + { + "$ref": "#/$defs/section-main-runtime-links" + }, + { + "$ref": "#/$defs/section-handoffs-and-approvals" + }, + { + "$ref": "#/$defs/section-receipts-and-user-participation" + }, + { + "$ref": "#/$defs/section-failure-degradation-and-closure" + }, + { + "$ref": "#/$defs/section-source-traceability" + }, + { + "$ref": "#/$defs/section-process-gaps" + } + ] + } + } + } + }, + { + "if": { + "properties": { + "artifactType": { + "const": "development-view" + } + }, + "required": [ + "artifactType" + ] + }, + "then": { + "properties": { + "sections": { + "allOf": [ + { + "$ref": "#/$defs/view-common-sections" + }, + { + "$ref": "#/$defs/section-architecture-level-components" + }, + { + "$ref": "#/$defs/section-package-boundary-intent" + }, + { + "$ref": "#/$defs/section-contracts-and-artifacts" + }, + { + "$ref": "#/$defs/section-dependency-rules" + }, + { + "$ref": "#/$defs/section-dependency-matrix" + }, + { + "$ref": "#/$defs/section-source-traceability" + }, + { + "$ref": "#/$defs/section-development-view-gaps" + } + ] + } + } + } + }, + { + "if": { + "properties": { + "artifactType": { + "const": "physical-view" + } + }, + "required": [ + "artifactType" + ] + }, + "then": { + "properties": { + "sections": { + "allOf": [ + { + "$ref": "#/$defs/view-common-sections" + }, + { + "$ref": "#/$defs/section-deployment-and-hosting-boundaries" + }, + { + "$ref": "#/$defs/section-external-system-collaboration" + }, + { + "$ref": "#/$defs/section-fact-sources-and-observability" + }, + { + "$ref": "#/$defs/section-operations-and-release-boundaries" + }, + { + "$ref": "#/$defs/section-source-traceability" + }, + { + "$ref": "#/$defs/section-physical-view-gaps" + } + ] + } + } + } + } + ], "$defs": { "section": { "type": "object", @@ -79,24 +399,25 @@ "items": { "type": "object", "additionalProperties": { - "type": [ - "string", - "number", - "boolean", - "array", - "object", - "null" - ] - }, - "not": { - "required": [ - "NEEDS ARCH UPDATE" - ] + "$ref": "#/$defs/recordValue" } } } } }, + "recordValue": { + "type": [ + "string", + "number", + "boolean", + "array", + "object", + "null" + ], + "not": { + "const": "NEEDS ARCH UPDATE" + } + }, "trace": { "type": "object", "additionalProperties": false, @@ -147,6 +468,112 @@ } } }, + "readiness": { + "type": "object", + "additionalProperties": false, + "required": [ + "readyGate", + "blockers" + ], + "properties": { + "readyGate": { + "type": "string", + "enum": [ + "PASS", + "BLOCKED" + ] + }, + "blockers": { + "type": "array", + "items": { + "$ref": "#/$defs/blocker" + } + } + }, + "allOf": [ + { + "if": { + "properties": { + "readyGate": { + "const": "PASS" + } + }, + "required": [ + "readyGate" + ] + }, + "then": { + "properties": { + "blockers": { + "maxItems": 0 + } + } + } + }, + { + "if": { + "properties": { + "readyGate": { + "const": "BLOCKED" + } + }, + "required": [ + "readyGate" + ] + }, + "then": { + "properties": { + "blockers": { + "minItems": 1 + } + } + } + } + ] + }, + "blocker": { + "type": "object", + "additionalProperties": false, + "required": [ + "code", + "message" + ], + "properties": { + "code": { + "$ref": "#/$defs/blockerCode" + }, + "message": { + "type": "string", + "minLength": 1 + }, + "artifact": { + "type": "string", + "minLength": 1 + }, + "sectionId": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]*$" + } + } + }, + "blockerCode": { + "type": "string", + "enum": [ + "ARCH_ARTIFACT_MISSING", + "ARCH_PLACEHOLDER_PRESENT", + "ARCH_REQUIRED_SECTION_MISSING", + "ARCH_REQUIRED_SECTION_EMPTY", + "ARCH_TRACEABILITY_MISSING", + "ARCH_DEPENDENCY_MATRIX_MISSING", + "ARCH_DEPENDENCY_MATRIX_EMPTY", + "ARCH_SOURCE_MISSING", + "ARCH_USER_INPUT_ONLY", + "ARCH_REPO_FIRST_MATRIX_MISUSED", + "ARCH_GIT_HISTORY_ONLY", + "ARCH_BOUNDARY_NONRESPONSIBILITY_MISSING", + "ARCH_UNSUPPORTED_CONCLUSION" + ] + }, "confidence": { "type": "string", "enum": [ @@ -154,6 +581,878 @@ "Medium", "Low" ] + }, + "contains-section": { + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string" + } + } + }, + "view-common-sections": { + "allOf": [ + { + "$ref": "#/$defs/section-architecture-intent" + }, + { + "$ref": "#/$defs/section-core-tensions" + }, + { + "$ref": "#/$defs/section-stable-boundaries" + }, + { + "$ref": "#/$defs/section-change-axes" + }, + { + "$ref": "#/$defs/section-invariants" + }, + { + "$ref": "#/$defs/section-non-goals-anti-patterns" + } + ] + }, + "section-view-index": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "view-index" + } + } + } + ] + } + }, + "section-architecture-intent": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "architecture-intent" + } + } + } + ] + } + }, + "section-central-design-forces": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "central-design-forces" + } + } + } + ] + } + }, + "section-primary-tradeoffs": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "primary-tradeoffs" + } + } + } + ] + } + }, + "section-stable-boundaries": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "stable-boundaries" + } + } + } + ] + } + }, + "section-change-axes": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "change-axes" + } + } + } + ] + } + }, + "section-anti-patterns": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "anti-patterns" + } + } + } + ] + } + }, + "section-core-tensions": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "core-tensions" + } + } + } + ] + } + }, + "section-invariants": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "invariants" + } + } + } + ] + } + }, + "section-non-goals-anti-patterns": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "non-goals-anti-patterns" + } + } + } + ] + } + }, + "section-cross-view-architecture-model": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "cross-view-architecture-model" + } + } + } + ] + } + }, + "section-key-architecture-conclusions": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "key-architecture-conclusions" + } + } + } + ] + } + }, + "section-cross-cutting-constraints": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "cross-cutting-constraints" + } + } + } + ] + } + }, + "section-open-risks-and-review-triggers": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "open-risks-and-review-triggers" + } + } + } + ] + } + }, + "section-source-traceability": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "source-traceability" + } + } + } + ] + } + }, + "section-repository-identity": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "repository-identity" + } + } + } + ] + } + }, + "section-entry-points": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "entry-points" + } + } + } + ] + } + }, + "section-user-visible-behaviors": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "user-visible-behaviors" + } + } + } + ] + } + }, + "section-system-boundaries": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "system-boundaries" + } + } + } + ] + } + }, + "section-data-and-state-clues": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "data-and-state-clues" + } + } + } + ] + } + }, + "section-runtime-and-process-clues": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "runtime-and-process-clues" + } + } + } + ] + } + }, + "section-development-structure-clues": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "development-structure-clues" + } + } + } + ] + } + }, + "section-repository-first-projection": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "repository-first-projection" + } + } + } + ] + } + }, + "section-physical-deployment-clues": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "physical-deployment-clues" + } + } + } + ] + } + }, + "section-git-history-signals": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "git-history-signals" + } + } + } + ] + } + }, + "section-evidence-gaps": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "evidence-gaps" + } + } + } + ] + } + }, + "section-actors-and-participants": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "actors-and-participants" + } + } + } + ] + } + }, + "section-use-cases": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "use-cases" + } + } + } + ] + } + }, + "section-scenario-paths": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "scenario-paths" + } + } + } + ] + } + }, + "section-acceptance-semantics": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "acceptance-semantics" + } + } + } + ] + } + }, + "section-scenario-gaps": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "scenario-gaps" + } + } + } + ] + } + }, + "section-capability-boundaries": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "capability-boundaries" + } + } + } + ] + } + }, + "section-domain-objects-and-relationships": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "domain-objects-and-relationships" + } + } + } + ] + } + }, + "section-state-and-lifecycle": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "state-and-lifecycle" + } + } + } + ] + } + }, + "section-logical-decisions": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "logical-decisions" + } + } + } + ] + } + }, + "section-logical-gaps": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "logical-gaps" + } + } + } + ] + } + }, + "section-main-runtime-links": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "main-runtime-links" + } + } + } + ] + } + }, + "section-handoffs-and-approvals": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "handoffs-and-approvals" + } + } + } + ] + } + }, + "section-receipts-and-user-participation": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "receipts-and-user-participation" + } + } + } + ] + } + }, + "section-failure-degradation-and-closure": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "failure-degradation-and-closure" + } + } + } + ] + } + }, + "section-process-gaps": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "process-gaps" + } + } + } + ] + } + }, + "section-architecture-level-components": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "architecture-level-components" + } + } + } + ] + } + }, + "section-package-boundary-intent": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "package-boundary-intent" + } + } + } + ] + } + }, + "section-contracts-and-artifacts": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "contracts-and-artifacts" + } + } + } + ] + } + }, + "section-dependency-rules": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "dependency-rules" + } + } + } + ] + } + }, + "section-dependency-matrix": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "required": [ + "records" + ], + "properties": { + "id": { + "const": "dependency-matrix" + }, + "records": { + "type": "array", + "minItems": 1 + } + } + } + ] + } + }, + "section-development-view-gaps": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "development-view-gaps" + } + } + } + ] + } + }, + "section-deployment-and-hosting-boundaries": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "deployment-and-hosting-boundaries" + } + } + } + ] + } + }, + "section-external-system-collaboration": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "external-system-collaboration" + } + } + } + ] + } + }, + "section-fact-sources-and-observability": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "fact-sources-and-observability" + } + } + } + ] + } + }, + "section-operations-and-release-boundaries": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "operations-and-release-boundaries" + } + } + } + ] + } + }, + "section-physical-view-gaps": { + "contains": { + "allOf": [ + { + "$ref": "#/$defs/contains-section" + }, + { + "properties": { + "id": { + "const": "physical-view-gaps" + } + } + } + ] + } } } } diff --git a/extensions/arch/scripts/bash/setup-arch.sh b/extensions/arch/scripts/bash/setup-arch.sh index 1058c5b4d6..e5201b73d5 100755 --- a/extensions/arch/scripts/bash/setup-arch.sh +++ b/extensions/arch/scripts/bash/setup-arch.sh @@ -97,7 +97,10 @@ resolve_architecture_template() { REPO_ROOT=$(get_repo_root) ARCH_DIR="$REPO_ROOT/.specify/memory" SCHEMA_DIR="$REPO_ROOT/.specify/extensions/arch/schemas" +SCRIPT_DIR="$REPO_ROOT/.specify/extensions/arch/scripts" ARCH_SCHEMA_FILE="$SCHEMA_DIR/architecture-artifacts.schema.json" +ARCH_VALIDATOR_FILE="$SCRIPT_DIR/bash/validate-arch-artifacts.sh" +ARCH_VALIDATOR_PS_FILE="$SCRIPT_DIR/powershell/validate-arch-artifacts.ps1" ARCH_FILE="$ARCH_DIR/architecture.md" REPO_FACTS_FILE="$ARCH_DIR/architecture-repo-facts.md" SCENARIO_VIEW="$ARCH_DIR/architecture-scenario-view.md" @@ -146,19 +149,23 @@ if $JSON_MODE; then --arg arch_dir "$ARCH_DIR" \ --arg schema_dir "$SCHEMA_DIR" \ --arg arch_schema_file "$ARCH_SCHEMA_FILE" \ + --arg arch_validator_file "$ARCH_VALIDATOR_FILE" \ + --arg arch_validator_ps_file "$ARCH_VALIDATOR_PS_FILE" \ --arg repo_facts_file "$REPO_FACTS_FILE" \ --arg scenario_view "$SCENARIO_VIEW" \ --arg logical_view "$LOGICAL_VIEW" \ --arg process_view "$PROCESS_VIEW" \ --arg development_view "$DEVELOPMENT_VIEW" \ --arg physical_view "$PHYSICAL_VIEW" \ - '{ARCH_FILE:$arch_file,ARCH_DIR:$arch_dir,SCHEMA_DIR:$schema_dir,ARCH_SCHEMA_FILE:$arch_schema_file,REPO_FACTS_FILE:$repo_facts_file,SCENARIO_VIEW:$scenario_view,LOGICAL_VIEW:$logical_view,PROCESS_VIEW:$process_view,DEVELOPMENT_VIEW:$development_view,PHYSICAL_VIEW:$physical_view}' + '{ARCH_FILE:$arch_file,ARCH_DIR:$arch_dir,SCHEMA_DIR:$schema_dir,ARCH_SCHEMA_FILE:$arch_schema_file,ARCH_VALIDATOR_FILE:$arch_validator_file,ARCH_VALIDATOR_PS_FILE:$arch_validator_ps_file,REPO_FACTS_FILE:$repo_facts_file,SCENARIO_VIEW:$scenario_view,LOGICAL_VIEW:$logical_view,PROCESS_VIEW:$process_view,DEVELOPMENT_VIEW:$development_view,PHYSICAL_VIEW:$physical_view}' else - printf '{"ARCH_FILE":"%s","ARCH_DIR":"%s","SCHEMA_DIR":"%s","ARCH_SCHEMA_FILE":"%s","REPO_FACTS_FILE":"%s","SCENARIO_VIEW":"%s","LOGICAL_VIEW":"%s","PROCESS_VIEW":"%s","DEVELOPMENT_VIEW":"%s","PHYSICAL_VIEW":"%s"}\n' \ + printf '{"ARCH_FILE":"%s","ARCH_DIR":"%s","SCHEMA_DIR":"%s","ARCH_SCHEMA_FILE":"%s","ARCH_VALIDATOR_FILE":"%s","ARCH_VALIDATOR_PS_FILE":"%s","REPO_FACTS_FILE":"%s","SCENARIO_VIEW":"%s","LOGICAL_VIEW":"%s","PROCESS_VIEW":"%s","DEVELOPMENT_VIEW":"%s","PHYSICAL_VIEW":"%s"}\n' \ "$(json_escape "$ARCH_FILE")" \ "$(json_escape "$ARCH_DIR")" \ "$(json_escape "$SCHEMA_DIR")" \ "$(json_escape "$ARCH_SCHEMA_FILE")" \ + "$(json_escape "$ARCH_VALIDATOR_FILE")" \ + "$(json_escape "$ARCH_VALIDATOR_PS_FILE")" \ "$(json_escape "$REPO_FACTS_FILE")" \ "$(json_escape "$SCENARIO_VIEW")" \ "$(json_escape "$LOGICAL_VIEW")" \ @@ -171,6 +178,8 @@ else echo "ARCH_DIR: $ARCH_DIR" echo "SCHEMA_DIR: $SCHEMA_DIR" echo "ARCH_SCHEMA_FILE: $ARCH_SCHEMA_FILE" + echo "ARCH_VALIDATOR_FILE: $ARCH_VALIDATOR_FILE" + echo "ARCH_VALIDATOR_PS_FILE: $ARCH_VALIDATOR_PS_FILE" echo "REPO_FACTS_FILE: $REPO_FACTS_FILE" echo "SCENARIO_VIEW: $SCENARIO_VIEW" echo "LOGICAL_VIEW: $LOGICAL_VIEW" diff --git a/extensions/arch/scripts/bash/validate-arch-artifacts.sh b/extensions/arch/scripts/bash/validate-arch-artifacts.sh new file mode 100755 index 0000000000..e3b23b8258 --- /dev/null +++ b/extensions/arch/scripts/bash/validate-arch-artifacts.sh @@ -0,0 +1,214 @@ +#!/usr/bin/env bash + +set -euo pipefail + +JSON_MODE=false + +for arg in "$@"; do + case "$arg" in + --json) + JSON_MODE=true + ;; + --help|-h) + echo "Usage: $0 [--json]" + echo " --json Output readiness result as JSON" + echo " --help Show this help message" + exit 0 + ;; + *) + ;; + esac +done + +find_specify_root() { + local dir="${1:-$(pwd)}" + dir="$(cd -- "$dir" 2>/dev/null && pwd)" || return 1 + local prev_dir="" + while true; do + if [ -d "$dir/.specify" ]; then + echo "$dir" + return 0 + fi + if [ "$dir" = "/" ] || [ "$dir" = "$prev_dir" ]; then + break + fi + prev_dir="$dir" + dir="$(dirname "$dir")" + done + return 1 +} + +get_repo_root() { + local specify_root + if specify_root=$(find_specify_root); then + echo "$specify_root" + return + fi + + if git rev-parse --show-toplevel >/dev/null 2>&1; then + git rev-parse --show-toplevel + return + fi + + local script_dir + script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + (cd "$script_dir/../../../../.." && pwd) +} + +json_escape() { + local s="$1" + s="${s//\\/\\\\}" + s="${s//\"/\\\"}" + s="${s//$'\n'/\\n}" + s="${s//$'\t'/\\t}" + s="${s//$'\r'/\\r}" + printf '%s' "$s" +} + +blockers=() + +add_blocker() { + local code="$1" + local artifact="$2" + local section="$3" + local message="$4" + blockers+=("$(printf '{"code":"%s","artifact":"%s","sectionId":"%s","message":"%s"}' \ + "$(json_escape "$code")" \ + "$(json_escape "$artifact")" \ + "$(json_escape "$section")" \ + "$(json_escape "$message")")") +} + +section_heading() { + local section_id="$1" + case "$section_id" in + non-goals-anti-patterns) echo "Non-goals / Anti-patterns"; return ;; + architecture-level-components) echo "Architecture-Level Components"; return ;; + physical-deployment-clues) echo "Physical / Deployment Clues"; return ;; + development-view-gaps) echo "Development View Gaps"; return ;; + physical-view-gaps) echo "Physical View Gaps"; return ;; + esac + printf '%s\n' "$section_id" | sed 's/-/ /g' | awk '{ + for (i = 1; i <= NF; i++) { + $i = toupper(substr($i, 1, 1)) substr($i, 2) + } + print + }' +} + +section_exists() { + local file="$1" + local section_id="$2" + local heading + heading="$(section_heading "$section_id")" + grep -Eq "^##[[:space:]]+$heading[[:space:]]*$" "$file" +} + +section_has_content() { + local file="$1" + local section_id="$2" + local heading + heading="$(section_heading "$section_id")" + awk -v heading="$heading" ' + $0 ~ "^##[[:space:]]+" heading "[[:space:]]*$" { in_section = 1; next } + in_section && /^##[[:space:]]+/ { exit } + in_section { + line = $0 + gsub(/^[[:space:]]+|[[:space:]]+$/, "", line) + if (line == "") next + if (line ~ /^[-|:[:space:]]+$/) next + if (line ~ /NEEDS ARCH UPDATE|NEEDS REPO FACTS UPDATE/) next + if (line ~ /^\|[[:space:]]*[-:]/) next + if (line ~ /^\|.*\|$/ && line !~ /NEEDS ARCH UPDATE|NEEDS REPO FACTS UPDATE/) { + found = 1 + exit + } + if (line !~ /^\|/) { + found = 1 + exit + } + } + END { exit(found ? 0 : 1) } + ' "$file" +} + +REPO_ROOT="$(get_repo_root)" +ARCH_DIR="$REPO_ROOT/.specify/memory" + +declare -A FILES=( + [architecture-synthesis]="$ARCH_DIR/architecture.md" + [scenario-view]="$ARCH_DIR/architecture-scenario-view.md" + [logical-view]="$ARCH_DIR/architecture-logical-view.md" + [process-view]="$ARCH_DIR/architecture-process-view.md" + [development-view]="$ARCH_DIR/architecture-development-view.md" + [physical-view]="$ARCH_DIR/architecture-physical-view.md" +) + +declare -A REQUIRED_SECTIONS=( + [architecture-synthesis]="view-index|architecture-intent|central-design-forces|primary-tradeoffs|stable-boundaries|change-axes|anti-patterns|cross-view-architecture-model|key-architecture-conclusions|cross-cutting-constraints|open-risks-and-review-triggers" + [scenario-view]="architecture-intent|core-tensions|stable-boundaries|change-axes|invariants|non-goals-anti-patterns|actors-and-participants|use-cases|scenario-paths|acceptance-semantics|source-traceability|scenario-gaps" + [logical-view]="architecture-intent|core-tensions|stable-boundaries|change-axes|invariants|non-goals-anti-patterns|capability-boundaries|domain-objects-and-relationships|state-and-lifecycle|logical-decisions|source-traceability|logical-gaps" + [process-view]="architecture-intent|core-tensions|stable-boundaries|change-axes|invariants|non-goals-anti-patterns|main-runtime-links|handoffs-and-approvals|receipts-and-user-participation|failure-degradation-and-closure|source-traceability|process-gaps" + [development-view]="architecture-intent|core-tensions|stable-boundaries|change-axes|invariants|non-goals-anti-patterns|architecture-level-components|package-boundary-intent|contracts-and-artifacts|dependency-rules|dependency-matrix|source-traceability|development-view-gaps" + [physical-view]="architecture-intent|core-tensions|stable-boundaries|change-axes|invariants|non-goals-anti-patterns|deployment-and-hosting-boundaries|external-system-collaboration|fact-sources-and-observability|operations-and-release-boundaries|source-traceability|physical-view-gaps" +) + +for artifact in architecture-synthesis scenario-view logical-view process-view development-view physical-view; do + file="${FILES[$artifact]}" + + if [ ! -f "$file" ]; then + add_blocker "ARCH_ARTIFACT_MISSING" "$artifact" "" "Required architecture artifact is missing: $file" + continue + fi + + if grep -Eq "NEEDS ARCH UPDATE|NEEDS REPO FACTS UPDATE" "$file"; then + add_blocker "ARCH_PLACEHOLDER_PRESENT" "$artifact" "" "Artifact still contains placeholder update markers." + fi + + IFS='|' read -r -a sections <<< "${REQUIRED_SECTIONS[$artifact]}" + for section in "${sections[@]}"; do + if ! section_exists "$file" "$section"; then + if [ "$section" = "dependency-matrix" ]; then + add_blocker "ARCH_DEPENDENCY_MATRIX_MISSING" "$artifact" "$section" "Development View must include Dependency Matrix." + else + add_blocker "ARCH_REQUIRED_SECTION_MISSING" "$artifact" "$section" "Required section is missing." + fi + continue + fi + if ! section_has_content "$file" "$section"; then + if [ "$section" = "dependency-matrix" ]; then + add_blocker "ARCH_DEPENDENCY_MATRIX_EMPTY" "$artifact" "$section" "Dependency Matrix has no supported records." + elif [ "$section" = "source-traceability" ]; then + add_blocker "ARCH_TRACEABILITY_MISSING" "$artifact" "$section" "Source Traceability has no supported records." + else + add_blocker "ARCH_REQUIRED_SECTION_EMPTY" "$artifact" "$section" "Required section has no supported records." + fi + fi + done +done + +if [ "${#blockers[@]}" -eq 0 ]; then + if $JSON_MODE; then + printf '{"ready_gate":"PASS","blockers":[]}\n' + else + echo "ready_gate: PASS" + fi + exit 0 +fi + +if $JSON_MODE; then + printf '{"ready_gate":"BLOCKED","blockers":[' + local_prefix="" + for blocker in "${blockers[@]}"; do + printf '%s%s' "$local_prefix" "$blocker" + local_prefix="," + done + printf ']}\n' +else + echo "ready_gate: BLOCKED" + for blocker in "${blockers[@]}"; do + echo "$blocker" + done +fi + +exit 1 diff --git a/extensions/arch/scripts/powershell/setup-arch.ps1 b/extensions/arch/scripts/powershell/setup-arch.ps1 index 70e5c94d5e..68816f75dd 100644 --- a/extensions/arch/scripts/powershell/setup-arch.ps1 +++ b/extensions/arch/scripts/powershell/setup-arch.ps1 @@ -83,7 +83,10 @@ function Convert-ToPlainPath { $repoRoot = Convert-ToPlainPath (Get-RepoRoot) $archDir = Join-Path $repoRoot ".specify/memory" $schemaDir = Join-Path $repoRoot ".specify/extensions/arch/schemas" +$scriptDir = Join-Path $repoRoot ".specify/extensions/arch/scripts" $archSchemaFile = Join-Path $schemaDir "architecture-artifacts.schema.json" +$archValidatorFile = Join-Path $scriptDir "bash/validate-arch-artifacts.sh" +$archValidatorPsFile = Join-Path $scriptDir "powershell/validate-arch-artifacts.ps1" $archFile = Join-Path $archDir "architecture.md" $repoFactsFile = Join-Path $archDir "architecture-repo-facts.md" $scenarioView = Join-Path $archDir "architecture-scenario-view.md" @@ -132,6 +135,8 @@ if ($Json) { ARCH_DIR = $archDir SCHEMA_DIR = $schemaDir ARCH_SCHEMA_FILE = $archSchemaFile + ARCH_VALIDATOR_FILE = $archValidatorFile + ARCH_VALIDATOR_PS_FILE = $archValidatorPsFile REPO_FACTS_FILE = $repoFactsFile SCENARIO_VIEW = $scenarioView LOGICAL_VIEW = $logicalView @@ -144,6 +149,8 @@ if ($Json) { Write-Output "ARCH_DIR: $archDir" Write-Output "SCHEMA_DIR: $schemaDir" Write-Output "ARCH_SCHEMA_FILE: $archSchemaFile" + Write-Output "ARCH_VALIDATOR_FILE: $archValidatorFile" + Write-Output "ARCH_VALIDATOR_PS_FILE: $archValidatorPsFile" Write-Output "REPO_FACTS_FILE: $repoFactsFile" Write-Output "SCENARIO_VIEW: $scenarioView" Write-Output "LOGICAL_VIEW: $logicalView" diff --git a/extensions/arch/scripts/powershell/validate-arch-artifacts.ps1 b/extensions/arch/scripts/powershell/validate-arch-artifacts.ps1 new file mode 100644 index 0000000000..923e45c63f --- /dev/null +++ b/extensions/arch/scripts/powershell/validate-arch-artifacts.ps1 @@ -0,0 +1,238 @@ +#!/usr/bin/env pwsh + +[CmdletBinding()] +param( + [switch]$Json, + [switch]$Help +) + +$ErrorActionPreference = 'Stop' + +if ($Help) { + Write-Output "Usage: ./validate-arch-artifacts.ps1 [-Json] [-Help]" + Write-Output " -Json Output readiness result as JSON" + Write-Output " -Help Show this help message" + exit 0 +} + +function Find-SpecifyRoot { + param([string]$StartDir = (Get-Location).Path) + + $resolved = Resolve-Path -LiteralPath $StartDir -ErrorAction SilentlyContinue + $current = if ($resolved) { $resolved.Path } else { $null } + if (-not $current) { return $null } + + while ($true) { + if (Test-Path -LiteralPath (Join-Path $current ".specify") -PathType Container) { + return $current + } + $parent = Split-Path $current -Parent + if ([string]::IsNullOrEmpty($parent) -or $parent -eq $current) { + return $null + } + $current = $parent + } +} + +function Get-RepoRoot { + $specifyRoot = Find-SpecifyRoot + if ($specifyRoot) { + return $specifyRoot + } + + try { + $result = git rev-parse --show-toplevel 2>$null + if ($LASTEXITCODE -eq 0) { + return $result + } + } catch { + } + + return (Resolve-Path -LiteralPath (Join-Path $PSScriptRoot "../../../../..")).Path +} + +function Convert-ToPlainPath { + param([Parameter(Mandatory = $true)][string]$Path) + + if ($Path -like 'Microsoft.PowerShell.Core\FileSystem::*') { + return $Path.Substring('Microsoft.PowerShell.Core\FileSystem::'.Length) + } + return $Path +} + +function Add-Blocker { + param( + [Parameter(Mandatory = $true)][string]$Code, + [Parameter(Mandatory = $true)][string]$Artifact, + [string]$SectionId = "", + [Parameter(Mandatory = $true)][string]$Message + ) + + $script:blockers += [PSCustomObject]@{ + code = $Code + artifact = $Artifact + sectionId = $SectionId + message = $Message + } +} + +function Test-SectionExists { + param( + [AllowEmptyCollection()][AllowEmptyString()][string[]]$Lines, + [Parameter(Mandatory = $true)][string]$Heading + ) + + $pattern = '^##\s+' + [regex]::Escape($Heading) + '\s*$' + return [bool]($Lines | Where-Object { $_ -match $pattern } | Select-Object -First 1) +} + +function Test-SectionHasContent { + param( + [AllowEmptyCollection()][AllowEmptyString()][string[]]$Lines, + [Parameter(Mandatory = $true)][string]$Heading + ) + + $pattern = '^##\s+' + [regex]::Escape($Heading) + '\s*$' + $inSection = $false + foreach ($line in $Lines) { + if ($line -match $pattern) { + $inSection = $true + continue + } + if ($inSection -and $line -match '^##\s+') { + break + } + if (-not $inSection) { + continue + } + + $trimmed = $line.Trim() + if (-not $trimmed) { continue } + if ($trimmed -match 'NEEDS ARCH UPDATE|NEEDS REPO FACTS UPDATE') { continue } + if ($trimmed -match '^[-|:\s]+$') { continue } + if ($trimmed -match '^\|\s*[-:]') { continue } + return $true + } + + return $false +} + +$repoRoot = Convert-ToPlainPath (Get-RepoRoot) +$archDir = Join-Path $repoRoot ".specify/memory" +$blockers = @() + +$files = [ordered]@{ + "architecture-synthesis" = Join-Path $archDir "architecture.md" + "scenario-view" = Join-Path $archDir "architecture-scenario-view.md" + "logical-view" = Join-Path $archDir "architecture-logical-view.md" + "process-view" = Join-Path $archDir "architecture-process-view.md" + "development-view" = Join-Path $archDir "architecture-development-view.md" + "physical-view" = Join-Path $archDir "architecture-physical-view.md" +} + +$sectionHeadings = @{ + "view-index" = "View Index" + "architecture-intent" = "Architecture Intent" + "central-design-forces" = "Central Design Forces" + "primary-tradeoffs" = "Primary Tradeoffs" + "stable-boundaries" = "Stable Boundaries" + "change-axes" = "Change Axes" + "anti-patterns" = "Anti-patterns" + "cross-view-architecture-model" = "Cross-View Architecture Model" + "key-architecture-conclusions" = "Key Architecture Conclusions" + "cross-cutting-constraints" = "Cross-Cutting Constraints" + "open-risks-and-review-triggers" = "Open Risks and Review Triggers" + "core-tensions" = "Core Tensions" + "invariants" = "Invariants" + "non-goals-anti-patterns" = "Non-goals / Anti-patterns" + "actors-and-participants" = "Actors and Participants" + "use-cases" = "Use Cases" + "scenario-paths" = "Scenario Paths" + "acceptance-semantics" = "Acceptance Semantics" + "source-traceability" = "Source Traceability" + "scenario-gaps" = "Scenario Gaps" + "capability-boundaries" = "Capability Boundaries" + "domain-objects-and-relationships" = "Domain Objects and Relationships" + "state-and-lifecycle" = "State and Lifecycle" + "logical-decisions" = "Logical Decisions" + "logical-gaps" = "Logical Gaps" + "main-runtime-links" = "Main Runtime Links" + "handoffs-and-approvals" = "Handoffs and Approvals" + "receipts-and-user-participation" = "Receipts and User Participation" + "failure-degradation-and-closure" = "Failure, Degradation, and Closure" + "process-gaps" = "Process Gaps" + "architecture-level-components" = "Architecture-Level Components" + "package-boundary-intent" = "Package Boundary Intent" + "contracts-and-artifacts" = "Contracts and Artifacts" + "dependency-rules" = "Dependency Rules" + "dependency-matrix" = "Dependency Matrix" + "development-view-gaps" = "Development View Gaps" + "deployment-and-hosting-boundaries" = "Deployment and Hosting Boundaries" + "external-system-collaboration" = "External System Collaboration" + "fact-sources-and-observability" = "Fact Sources and Observability" + "operations-and-release-boundaries" = "Operations and Release Boundaries" + "physical-view-gaps" = "Physical View Gaps" +} + +$requiredSections = @{ + "architecture-synthesis" = @("view-index", "architecture-intent", "central-design-forces", "primary-tradeoffs", "stable-boundaries", "change-axes", "anti-patterns", "cross-view-architecture-model", "key-architecture-conclusions", "cross-cutting-constraints", "open-risks-and-review-triggers") + "scenario-view" = @("architecture-intent", "core-tensions", "stable-boundaries", "change-axes", "invariants", "non-goals-anti-patterns", "actors-and-participants", "use-cases", "scenario-paths", "acceptance-semantics", "source-traceability", "scenario-gaps") + "logical-view" = @("architecture-intent", "core-tensions", "stable-boundaries", "change-axes", "invariants", "non-goals-anti-patterns", "capability-boundaries", "domain-objects-and-relationships", "state-and-lifecycle", "logical-decisions", "source-traceability", "logical-gaps") + "process-view" = @("architecture-intent", "core-tensions", "stable-boundaries", "change-axes", "invariants", "non-goals-anti-patterns", "main-runtime-links", "handoffs-and-approvals", "receipts-and-user-participation", "failure-degradation-and-closure", "source-traceability", "process-gaps") + "development-view" = @("architecture-intent", "core-tensions", "stable-boundaries", "change-axes", "invariants", "non-goals-anti-patterns", "architecture-level-components", "package-boundary-intent", "contracts-and-artifacts", "dependency-rules", "dependency-matrix", "source-traceability", "development-view-gaps") + "physical-view" = @("architecture-intent", "core-tensions", "stable-boundaries", "change-axes", "invariants", "non-goals-anti-patterns", "deployment-and-hosting-boundaries", "external-system-collaboration", "fact-sources-and-observability", "operations-and-release-boundaries", "source-traceability", "physical-view-gaps") +} + +foreach ($artifact in $files.Keys) { + $file = $files[$artifact] + if (-not (Test-Path -LiteralPath $file -PathType Leaf)) { + Add-Blocker -Code "ARCH_ARTIFACT_MISSING" -Artifact $artifact -Message "Required architecture artifact is missing: $file" + continue + } + + $lines = Get-Content -LiteralPath $file + $content = $lines -join "`n" + if ($content -match 'NEEDS ARCH UPDATE|NEEDS REPO FACTS UPDATE') { + Add-Blocker -Code "ARCH_PLACEHOLDER_PRESENT" -Artifact $artifact -Message "Artifact still contains placeholder update markers." + } + + foreach ($section in $requiredSections[$artifact]) { + $heading = $sectionHeadings[$section] + if (-not (Test-SectionExists -Lines $lines -Heading $heading)) { + if ($section -eq "dependency-matrix") { + Add-Blocker -Code "ARCH_DEPENDENCY_MATRIX_MISSING" -Artifact $artifact -SectionId $section -Message "Development View must include Dependency Matrix." + } else { + Add-Blocker -Code "ARCH_REQUIRED_SECTION_MISSING" -Artifact $artifact -SectionId $section -Message "Required section is missing." + } + continue + } + if (-not (Test-SectionHasContent -Lines $lines -Heading $heading)) { + if ($section -eq "dependency-matrix") { + Add-Blocker -Code "ARCH_DEPENDENCY_MATRIX_EMPTY" -Artifact $artifact -SectionId $section -Message "Dependency Matrix has no supported records." + } elseif ($section -eq "source-traceability") { + Add-Blocker -Code "ARCH_TRACEABILITY_MISSING" -Artifact $artifact -SectionId $section -Message "Source Traceability has no supported records." + } else { + Add-Blocker -Code "ARCH_REQUIRED_SECTION_EMPTY" -Artifact $artifact -SectionId $section -Message "Required section has no supported records." + } + } + } +} + +$readyGate = if ($blockers.Count -eq 0) { "PASS" } else { "BLOCKED" } +$result = [PSCustomObject]@{ + ready_gate = $readyGate + blockers = $blockers +} + +if ($Json) { + $result | ConvertTo-Json -Compress -Depth 5 +} else { + Write-Output "ready_gate: $readyGate" + foreach ($blocker in $blockers) { + Write-Output ($blocker | ConvertTo-Json -Compress) + } +} + +if ($blockers.Count -gt 0) { + exit 1 +} diff --git a/extensions/arch/templates/architecture-development-template.md b/extensions/arch/templates/architecture-development-template.md index f4786aa4f2..4761d77a29 100644 --- a/extensions/arch/templates/architecture-development-template.md +++ b/extensions/arch/templates/architecture-development-template.md @@ -1,8 +1,8 @@ # Development View -**Input**: `.specify/memory/architecture-logical-view.md`, `.specify/memory/architecture-process-view.md` +**Input**: `.specify/memory/architecture-logical-view.md`, `.specify/memory/architecture-process-view.md`; reverse generation may also use development-owned repository-first dependency matrix summaries -**Purpose**: Architecture-level components, package boundary intent, contract/artifact semantics, and dependency rules from logical and process views. +**Purpose**: Architecture-level components, package boundary intent, contract/artifact semantics, dependency rules, and a required dependency matrix from logical and process views. Dependency matrix signals belong here as development governance evidence; they are not an independent architecture view. ## Architecture Intent @@ -62,6 +62,12 @@ |------|-------------------|---------------------|--------|------------------| | NEEDS ARCH UPDATE | NEEDS ARCH UPDATE | NEEDS ARCH UPDATE | NEEDS ARCH UPDATE | NEEDS ARCH UPDATE | +## Dependency Matrix + +| From Boundary / Component | To Boundary / Component | Allowed? | Constraint / Rule Source | Architecture Consequence | +|---------------------------|-------------------------|----------|--------------------------|--------------------------| +| NEEDS ARCH UPDATE | NEEDS ARCH UPDATE | NEEDS ARCH UPDATE | NEEDS ARCH UPDATE | NEEDS ARCH UPDATE | + ## Source Traceability | Architecture Conclusion | Source Type | Source Reference | Confidence | diff --git a/extensions/arch/templates/architecture-repo-facts-template.md b/extensions/arch/templates/architecture-repo-facts-template.md index 888f6660ad..03f61df769 100644 --- a/extensions/arch/templates/architecture-repo-facts-template.md +++ b/extensions/arch/templates/architecture-repo-facts-template.md @@ -68,10 +68,10 @@ Repository-first signals relevant to architecture evidence. |-------------|-------------------|---------------------|-------------------------|------------------| | NEEDS REPO FACTS UPDATE | NEEDS REPO FACTS UPDATE | NEEDS REPO FACTS UPDATE | NEEDS REPO FACTS UPDATE | NEEDS REPO FACTS UPDATE | -### Dependency Governance Signals +### Development-Owned Dependency Governance Signals -| Signal Source | Dependency / Concern | Signal Type | Affected Boundary | Architecture Review Trigger | -|---------------|----------------------|-------------|-------------------|-----------------------------| +| Signal Source | Dependency / Concern | Signal Type | Development Boundary / Architecture Boundary Meaning | Architecture Review Trigger | +|---------------|----------------------|-------------|------------------------------------------------------|-----------------------------| | NEEDS REPO FACTS UPDATE | NEEDS REPO FACTS UPDATE | NEEDS REPO FACTS UPDATE | NEEDS REPO FACTS UPDATE | NEEDS REPO FACTS UPDATE | ## Physical / Deployment Clues diff --git a/extensions/arch/templates/architecture-template.md b/extensions/arch/templates/architecture-template.md index a0572d2eb1..048eef30ee 100644 --- a/extensions/arch/templates/architecture-template.md +++ b/extensions/arch/templates/architecture-template.md @@ -14,7 +14,7 @@ | Scenario | `.specify/memory/architecture-scenario-view.md` | Use-case actor, path, branch, and acceptance semantics | NEEDS ARCH UPDATE | | Logical | `.specify/memory/architecture-logical-view.md` | Capability boundaries, domain objects, states, and invariants | NEEDS ARCH UPDATE | | Process | `.specify/memory/architecture-process-view.md` | Runtime links, handoffs, approvals, receipts, failure closure | NEEDS ARCH UPDATE | -| Development | `.specify/memory/architecture-development-view.md` | Architecture-level components, package boundaries, contracts, dependencies | NEEDS ARCH UPDATE | +| Development | `.specify/memory/architecture-development-view.md` | Architecture-level components, package boundaries, contracts, dependencies, dependency matrix | NEEDS ARCH UPDATE | | Physical | `.specify/memory/architecture-physical-view.md` | Deployment, external systems, fact sources, observability, operations | NEEDS ARCH UPDATE | ## Architecture Intent diff --git a/extensions/arch/tests/repository-first-contract.sh b/extensions/arch/tests/repository-first-contract.sh index 87dd14dc76..6a45f06282 100755 --- a/extensions/arch/tests/repository-first-contract.sh +++ b/extensions/arch/tests/repository-first-contract.sh @@ -16,6 +16,34 @@ fi views=(scenario logical process development physical) +search "name: speckit\\.arch\\.full-generate" extension.yml >/dev/null +search "file: commands/speckit\\.arch\\.full-generate\\.md" extension.yml >/dev/null +test -f "commands/speckit.arch.full-generate.md" +search 'Generate all 4\+1 architecture views|Write only `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, and `ARCH_FILE`|Do not read, populate, or update `REPO_FACTS_FILE`|Generation Order|Synthesis Readiness|all five view paths' "commands/speckit.arch.full-generate.md" >/dev/null +search "Generation Order" "commands/speckit.arch.full-generate.md" >/dev/null +search "Synthesis Readiness" "commands/speckit.arch.full-generate.md" >/dev/null +search "all five view paths" "commands/speckit.arch.full-generate.md" >/dev/null +search "ready_gate: PASS" "commands/speckit.arch.full-generate.md" >/dev/null +search "Structured Contract" "commands/speckit.arch.full-generate.md" >/dev/null +search "ARCH_SCHEMA_FILE" "commands/speckit.arch.full-generate.md" >/dev/null +search 'required `Dependency Matrix` section' "commands/speckit.arch.full-generate.md" >/dev/null + +search "name: speckit\\.arch\\.full-reverse" extension.yml >/dev/null +search "file: commands/speckit\\.arch\\.full-reverse\\.md" extension.yml >/dev/null +test -f "commands/speckit.arch.full-reverse.md" +search 'Reverse-generate all 4\+1 architecture views|Write only `REPO_FACTS_FILE`, `SCENARIO_VIEW`, `LOGICAL_VIEW`, `PROCESS_VIEW`, `DEVELOPMENT_VIEW`, `PHYSICAL_VIEW`, and `ARCH_FILE`|Repository-First Inputs|Repo Facts Merge Rule|Reverse Generation Order|Synthesis Readiness|all five view paths' "commands/speckit.arch.full-reverse.md" >/dev/null +search "Reverse Generation Order" "commands/speckit.arch.full-reverse.md" >/dev/null +search "Repo Facts Merge Rule" "commands/speckit.arch.full-reverse.md" >/dev/null +search "Repo Facts Evidence Rules" "commands/speckit.arch.full-reverse.md" >/dev/null +search "Synthesis Readiness" "commands/speckit.arch.full-reverse.md" >/dev/null +search "all five view paths" "commands/speckit.arch.full-reverse.md" >/dev/null +search "ready_gate: PASS" "commands/speckit.arch.full-reverse.md" >/dev/null +search "Structured Contract" "commands/speckit.arch.full-reverse.md" >/dev/null +search "ARCH_SCHEMA_FILE" "commands/speckit.arch.full-reverse.md" >/dev/null +search 'required `Dependency Matrix` section' "commands/speckit.arch.full-reverse.md" >/dev/null +search "ARCH_GIT_HISTORY_ONLY" "commands/speckit.arch.full-reverse.md" >/dev/null +search "ARCH_UNSUPPORTED_CONCLUSION" "commands/speckit.arch.full-reverse.md" >/dev/null + for view in "${views[@]}"; do search "name: speckit\\.arch\\.${view}-generate" extension.yml >/dev/null search "file: commands/speckit\\.arch\\.${view}-generate\\.md" extension.yml >/dev/null @@ -24,7 +52,7 @@ for view in "${views[@]}"; do search "Setup Bootstrap" "commands/speckit.arch.${view}-generate.md" >/dev/null search "Synthesis Readiness" "commands/speckit.arch.${view}-generate.md" >/dev/null search "all five view paths" "commands/speckit.arch.${view}-generate.md" >/dev/null - search "source-backed non-gap architecture conclusion" "commands/speckit.arch.${view}-generate.md" >/dev/null + search "ready_gate: PASS" "commands/speckit.arch.${view}-generate.md" >/dev/null search "Structured Contract" "commands/speckit.arch.${view}-generate.md" >/dev/null search "ARCH_SCHEMA_FILE" "commands/speckit.arch.${view}-generate.md" >/dev/null @@ -36,11 +64,29 @@ for view in "${views[@]}"; do search "Repo Facts Evidence Rules" "commands/speckit.arch.${view}-reverse.md" >/dev/null search "Synthesis Readiness" "commands/speckit.arch.${view}-reverse.md" >/dev/null search "all five view paths" "commands/speckit.arch.${view}-reverse.md" >/dev/null - search "Git history is used alone" "commands/speckit.arch.${view}-reverse.md" >/dev/null - search "Unsupported .*MUST appear only" "commands/speckit.arch.${view}-reverse.md" >/dev/null + search "ARCH_GIT_HISTORY_ONLY" "commands/speckit.arch.${view}-reverse.md" >/dev/null + search "ARCH_UNSUPPORTED_CONCLUSION" "commands/speckit.arch.${view}-reverse.md" >/dev/null search "Structured Contract" "commands/speckit.arch.${view}-reverse.md" >/dev/null search "ARCH_SCHEMA_FILE" "commands/speckit.arch.${view}-reverse.md" >/dev/null + if [[ "$view" == "development" ]]; then + search 'required dependency matrix' "commands/speckit.arch.${view}-generate.md" >/dev/null + search 'required `Dependency Matrix` section' "commands/speckit.arch.${view}-generate.md" >/dev/null + search 'section id `dependency-matrix`' "commands/speckit.arch.${view}-generate.md" >/dev/null + search "omits the required .*Dependency Matrix" "commands/speckit.arch.${view}-generate.md" >/dev/null + search "required dependency matrix" extension.yml >/dev/null + search "development-owned dependency governance evidence" "commands/speckit.arch.${view}-reverse.md" >/dev/null + search 'required `Dependency Matrix` section' "commands/speckit.arch.${view}-reverse.md" >/dev/null + search 'section id `dependency-matrix`' "commands/speckit.arch.${view}-reverse.md" >/dev/null + search "architecture-level constraints" "commands/speckit.arch.${view}-reverse.md" >/dev/null + search "not as an independent architecture view" "commands/speckit.arch.${view}-reverse.md" >/dev/null + search "ARCH_REPO_FIRST_MATRIX_MISUSED" "commands/speckit.arch.${view}-reverse.md" >/dev/null + else + search "must not consume dependency matrices directly" "commands/speckit.arch.${view}-reverse.md" >/dev/null + search 'use development-view dependency conclusions only after `DEVELOPMENT_VIEW` is synthesis-ready' "commands/speckit.arch.${view}-reverse.md" >/dev/null + search "ARCH_REPO_FIRST_MATRIX_MISUSED" "commands/speckit.arch.${view}-reverse.md" >/dev/null + fi + search "Source Traceability" "templates/architecture-${view}-template.md" >/dev/null done @@ -49,21 +95,46 @@ if search "name: speckit\\.arch\\.(generate|reverse)$|name: speckit\\.arch\\.[a- exit 1 fi -search "Commands count: 10" CATALOG-SUBMISSION.md >/dev/null +search "Commands count: 12" CATALOG-SUBMISSION.md >/dev/null +search "speckit.arch.full-generate" README.md >/dev/null +search "speckit.arch.full-reverse" README.md >/dev/null search "speckit.arch.scenario-generate" README.md >/dev/null search "speckit.arch.physical-reverse" README.md >/dev/null search "legacy .*speckit\\.arch\\.generate.*speckit\\.arch\\.reverse" README.md >/dev/null +search "Dependency matrices are primarily owned by the development view" README.md >/dev/null +search 'development-generate.*development-reverse.*Dependency Matrix' README.md >/dev/null +search "must not consume dependency matrices directly" README.md >/dev/null +search "dependency matrix interpretation owned by development-view governance" CHANGELOG.md >/dev/null +search "full-reverse" CHANGELOG.md >/dev/null +search 'Require the Development View commands to produce a `Dependency Matrix` section' CHANGELOG.md >/dev/null +search "dependency matrix interpretation owned by the development view" CATALOG-SUBMISSION.md >/dev/null +search "full-reverse" CATALOG-SUBMISSION.md >/dev/null +search 'Requires the Development View commands to produce a `Dependency Matrix` section' CATALOG-SUBMISSION.md >/dev/null search "Repository-First Projection" templates/architecture-repo-facts-template.md >/dev/null search "Module Invocation Governance" templates/architecture-repo-facts-template.md >/dev/null -search "Dependency Governance Signals" templates/architecture-repo-facts-template.md >/dev/null +search "Development-Owned Dependency Governance Signals" templates/architecture-repo-facts-template.md >/dev/null +search "Development Boundary / Architecture Boundary Meaning" templates/architecture-repo-facts-template.md >/dev/null +search "## Dependency Matrix" templates/architecture-development-template.md >/dev/null +search "From Boundary / Component" templates/architecture-development-template.md >/dev/null test -f schemas/architecture-artifacts.schema.json search '"artifactType"' schemas/architecture-artifacts.schema.json >/dev/null search '"traceability"' schemas/architecture-artifacts.schema.json >/dev/null +search '"readiness"' schemas/architecture-artifacts.schema.json >/dev/null +search '"readyGate"' schemas/architecture-artifacts.schema.json >/dev/null +search '"blockers"' schemas/architecture-artifacts.schema.json >/dev/null +search '"ARCH_REQUIRED_SECTION_MISSING"' schemas/architecture-artifacts.schema.json >/dev/null +search '"ARCH_PLACEHOLDER_PRESENT"' schemas/architecture-artifacts.schema.json >/dev/null search '"confidence"' schemas/architecture-artifacts.schema.json >/dev/null search '"High"|\"Medium\"|\"Low\"' schemas/architecture-artifacts.schema.json >/dev/null +search '"const": "development-view"' schemas/architecture-artifacts.schema.json >/dev/null +search '"const": "dependency-matrix"' schemas/architecture-artifacts.schema.json >/dev/null +search '"minItems": 1' schemas/architecture-artifacts.schema.json >/dev/null +test -f scripts/bash/validate-arch-artifacts.sh +test -x scripts/bash/validate-arch-artifacts.sh +test -f scripts/powershell/validate-arch-artifacts.ps1 search "Preserve existing non-placeholder facts" commands/speckit.arch.development-reverse.md >/dev/null search "must not be copied verbatim into 4\\+1 views|must not be copied verbatim into architecture views" commands/speckit.arch.development-reverse.md >/dev/null -search "Git history is used alone as a development conclusion" commands/speckit.arch.development-reverse.md >/dev/null +search "ARCH_GIT_HISTORY_ONLY" commands/speckit.arch.development-reverse.md >/dev/null if search "Evidence Rules|Prohibited Content|Move unsupported|One sentence|Identify the|List the|Record how|Do not treat|Record observable|projected into" templates >/dev/null; then echo "templates must not carry command execution rules" >&2 @@ -79,14 +150,27 @@ cp -R commands scripts templates schemas "$tmpdir/.specify/extensions/arch/" cd "$tmpdir" setup_json=$(.specify/extensions/arch/scripts/bash/setup-arch.sh --json) printf '%s\n' "$setup_json" | search '"ARCH_SCHEMA_FILE"' - >/dev/null + printf '%s\n' "$setup_json" | search '"ARCH_VALIDATOR_FILE"' - >/dev/null + printf '%s\n' "$setup_json" | search '"ARCH_VALIDATOR_PS_FILE"' - >/dev/null test -f .specify/memory/architecture.md test -f .specify/memory/architecture-repo-facts.md test -f .specify/memory/architecture-scenario-view.md test -f .specify/memory/architecture-logical-view.md test -f .specify/memory/architecture-process-view.md test -f .specify/memory/architecture-development-view.md + search "## Dependency Matrix" .specify/memory/architecture-development-view.md >/dev/null test -f .specify/memory/architecture-physical-view.md test -f .specify/extensions/arch/schemas/architecture-artifacts.schema.json + test -f .specify/extensions/arch/scripts/bash/validate-arch-artifacts.sh + test -x .specify/extensions/arch/scripts/bash/validate-arch-artifacts.sh + test -f .specify/extensions/arch/scripts/powershell/validate-arch-artifacts.ps1 + + if validator_json=$(.specify/extensions/arch/scripts/bash/validate-arch-artifacts.sh --json); then + echo "placeholder architecture memory must block synthesis readiness" >&2 + exit 1 + fi + printf '%s\n' "$validator_json" | search '"ready_gate":"BLOCKED"' - >/dev/null + printf '%s\n' "$validator_json" | search '"ARCH_PLACEHOLDER_PRESENT"' - >/dev/null printf 'custom sentinel\n' > .specify/memory/architecture-scenario-view.md .specify/extensions/arch/scripts/bash/setup-arch.sh --json >/dev/null diff --git a/extensions/catalog.community.json b/extensions/catalog.community.json index f9e5b6f540..ab5996c1b7 100644 --- a/extensions/catalog.community.json +++ b/extensions/catalog.community.json @@ -1,6 +1,6 @@ { "schema_version": "1.0", - "updated_at": "2026-06-24T00:00:00Z", + "updated_at": "2026-06-25T00:00:00Z", "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json", "extensions": { "agent-assign": { @@ -148,10 +148,10 @@ "arch": { "name": "Architecture Workflow", "id": "arch", - "description": "Generate or reverse project-level 4+1 architecture views as separate commands", + "description": "Generate or reverse project-level 4+1 architecture views with per-view and full-workflow commands", "author": "bigsmartben", - "version": "1.2.1", - "download_url": "https://github.com/bigsmartben/spec-kit-arch/archive/refs/tags/v1.2.1.zip", + "version": "1.2.2", + "download_url": "https://github.com/bigsmartben/spec-kit-arch/archive/refs/tags/v1.2.2.zip", "repository": "https://github.com/bigsmartben/spec-kit-arch", "homepage": "https://github.com/bigsmartben/spec-kit-arch", "documentation": "https://github.com/bigsmartben/spec-kit-arch/blob/main/README.md", @@ -163,7 +163,7 @@ "speckit_version": ">=0.8.10.dev0" }, "provides": { - "commands": 10, + "commands": 12, "hooks": 0 }, "tags": [ @@ -176,7 +176,7 @@ "downloads": 0, "stars": 0, "created_at": "2026-05-14T00:00:00Z", - "updated_at": "2026-06-23T00:00:00Z" + "updated_at": "2026-06-25T00:00:00Z" }, "architect-preview": { "name": "Architect Impact Previewer", diff --git a/extensions/catalog.json b/extensions/catalog.json index e80493f8f4..d864bc5342 100644 --- a/extensions/catalog.json +++ b/extensions/catalog.json @@ -1,6 +1,6 @@ { "schema_version": "1.0", - "updated_at": "2026-06-23T00:00:00Z", + "updated_at": "2026-06-25T00:00:00Z", "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json", "extensions": { "agent-context": { @@ -20,8 +20,8 @@ "arch": { "name": "Architecture Workflow", "id": "arch", - "version": "1.2.1", - "description": "Generate or reverse project-level 4+1 architecture views as separate commands", + "version": "1.2.2", + "description": "Generate or reverse project-level 4+1 architecture views with per-view and full-workflow commands", "author": "bigsmartben", "repository": "https://github.com/bigsmartben/spec-kit-arch", "license": "MIT", @@ -30,7 +30,7 @@ "speckit_version": ">=0.8.10.dev0" }, "provides": { - "commands": 10 + "commands": 12 }, "tags": [ "architecture", diff --git a/tests/integrations/community_defaults.py b/tests/integrations/community_defaults.py index 2053727b1b..1695557bb3 100644 --- a/tests/integrations/community_defaults.py +++ b/tests/integrations/community_defaults.py @@ -16,6 +16,8 @@ "speckit.arch.process-generate", "speckit.arch.development-generate", "speckit.arch.physical-generate", + "speckit.arch.full-generate", + "speckit.arch.full-reverse", "speckit.arch.scenario-reverse", "speckit.arch.logical-reverse", "speckit.arch.process-reverse", diff --git a/tests/test_arch_templates.py b/tests/test_arch_templates.py index 58ffd6d5ab..76d95d6676 100644 --- a/tests/test_arch_templates.py +++ b/tests/test_arch_templates.py @@ -18,6 +18,8 @@ def test_arch_commands_are_split_by_view_and_bootstrap_setup(): assert [path.name for path in command_files] == [ "speckit.arch.development-generate.md", "speckit.arch.development-reverse.md", + "speckit.arch.full-generate.md", + "speckit.arch.full-reverse.md", "speckit.arch.logical-generate.md", "speckit.arch.logical-reverse.md", "speckit.arch.physical-generate.md", @@ -34,8 +36,10 @@ def test_arch_commands_are_split_by_view_and_bootstrap_setup(): assert ".specify/extensions/arch/scripts/bash/setup-arch.sh --json" in content assert ".specify/extensions/arch/scripts/powershell/setup-arch.ps1 -Json" in content assert "ARCH_SCHEMA_FILE" in content + assert "ARCH_VALIDATOR_FILE" in content assert "Synthesis Readiness" in content - assert "NEEDS ARCH UPDATE" in content + assert "ready_gate" in content + assert "BLOCKER" in content assert ".specify/memory/architecture/" not in content assert "__SPECKIT_COMMAND_UC__" not in content diff --git a/tests/test_extensions.py b/tests/test_extensions.py index 1b893d1ec9..ae3fb0217d 100644 --- a/tests/test_extensions.py +++ b/tests/test_extensions.py @@ -227,24 +227,27 @@ def test_core_command_names_match_bundled_templates(self): assert CORE_COMMAND_NAMES == expected - def test_bundled_preview_catalogs_match_manifest(self): - """Preview's bundled package, catalogs, and default command list stay aligned.""" + @pytest.mark.parametrize("extension_id", ("arch", "preview")) + def test_bundled_default_catalogs_match_manifest(self, extension_id): + """Bundled default extension packages, catalogs, and command lists stay aligned.""" from tests.integrations.community_defaults import DEFAULT_EXTENSION_COMMANDS repo_root = Path(__file__).resolve().parent.parent - manifest = ExtensionManifest(repo_root / "extensions" / "preview" / "extension.yml") + manifest = ExtensionManifest(repo_root / "extensions" / extension_id / "extension.yml") bundled_catalog = json.loads( (repo_root / "extensions" / "catalog.json").read_text(encoding="utf-8") ) community_catalog = json.loads( (repo_root / "extensions" / "catalog.community.json").read_text(encoding="utf-8") ) - bundled_entry = bundled_catalog["extensions"]["preview"] - community_entry = community_catalog["extensions"]["preview"] + bundled_entry = bundled_catalog["extensions"][extension_id] + community_entry = community_catalog["extensions"][extension_id] manifest_repository = manifest.data["extension"]["repository"] manifest_commands = tuple(command["name"] for command in manifest.commands) - preview_default_commands = tuple( - command for command in DEFAULT_EXTENSION_COMMANDS if command.startswith("speckit.preview.") + default_commands = tuple( + command + for command in DEFAULT_EXTENSION_COMMANDS + if command.startswith(f"speckit.{extension_id}.") ) for entry in (bundled_entry, community_entry): @@ -255,7 +258,7 @@ def test_bundled_preview_catalogs_match_manifest(self): assert entry["provides"]["commands"] == len(manifest.commands) assert community_entry["download_url"].endswith(f"/refs/tags/v{manifest.version}.zip") - assert preview_default_commands == manifest_commands + assert default_commands == manifest_commands def test_missing_required_field(self, temp_dir): """Test manifest missing required field.""" diff --git a/tests/test_setup_arch.py b/tests/test_setup_arch.py index 3d71b33228..bbd7b93284 100644 --- a/tests/test_setup_arch.py +++ b/tests/test_setup_arch.py @@ -15,9 +15,12 @@ PROJECT_ROOT = Path(__file__).resolve().parent.parent ARCHITECTURE_EXTENSION = PROJECT_ROOT / "extensions" / "arch" SETUP_ARCH_SH = ARCHITECTURE_EXTENSION / "scripts" / "bash" / "setup-arch.sh" +VALIDATE_ARCH_SH = ARCHITECTURE_EXTENSION / "scripts" / "bash" / "validate-arch-artifacts.sh" SETUP_ARCH_PS = ARCHITECTURE_EXTENSION / "scripts" / "powershell" / "setup-arch.ps1" +VALIDATE_ARCH_PS = ARCHITECTURE_EXTENSION / "scripts" / "powershell" / "validate-arch-artifacts.ps1" ARCH_TEMPLATES = [ "architecture-template.md", + "architecture-repo-facts-template.md", "architecture-scenario-template.md", "architecture-logical-template.md", "architecture-process-template.md", @@ -36,12 +39,14 @@ def _install_bash_scripts(repo: Path) -> None: d = repo / ".specify" / "extensions" / "arch" / "scripts" / "bash" d.mkdir(parents=True, exist_ok=True) shutil.copy(SETUP_ARCH_SH, d / "setup-arch.sh") + shutil.copy(VALIDATE_ARCH_SH, d / "validate-arch-artifacts.sh") def _install_ps_scripts(repo: Path) -> None: d = repo / ".specify" / "extensions" / "arch" / "scripts" / "powershell" d.mkdir(parents=True, exist_ok=True) shutil.copy(SETUP_ARCH_PS, d / "setup-arch.ps1") + shutil.copy(VALIDATE_ARCH_PS, d / "validate-arch-artifacts.ps1") def _install_templates(repo: Path) -> None: @@ -122,6 +127,8 @@ def _assert_arch_json(repo: Path, data: dict[str, str], *, exact_paths: bool = T "ARCH_DIR": repo / ".specify" / "memory", "SCHEMA_DIR": repo / ".specify" / "extensions" / "arch" / "schemas", "ARCH_SCHEMA_FILE": repo / ".specify" / "extensions" / "arch" / "schemas" / "architecture-artifacts.schema.json", + "ARCH_VALIDATOR_FILE": repo / ".specify" / "extensions" / "arch" / "scripts" / "bash" / "validate-arch-artifacts.sh", + "ARCH_VALIDATOR_PS_FILE": repo / ".specify" / "extensions" / "arch" / "scripts" / "powershell" / "validate-arch-artifacts.ps1", "REPO_FACTS_FILE": repo / ".specify" / "memory" / "architecture-repo-facts.md", "SCENARIO_VIEW": repo / ".specify" / "memory" / "architecture-scenario-view.md", "LOGICAL_VIEW": repo / ".specify" / "memory" / "architecture-logical-view.md",