feat(architect): technology neutrality and view parity checks (v2.1.0)

Author: kanfil

FORK.md

@@ -39,6 +39,7 @@ Use `agentic-sdlc-v<version>` with plus:
 
 | Version | Date | Base Upstream | Changes |
 |---------|------|---------------|---------|
+| 0.8.12+adlc15 | 2026-05-20 | 0.8.12 | Architect extension v2.1.0: Technology neutrality in Functional View, Functional-Development view parity, analyze Pass E.6/E.7 |
 | 0.8.12+adlc14 | 2026-05-19 | 0.8.12 | Product extension v1.5.6: In-section diagrams, remove Visual Summary, sections renumbered 1-12, delete visual templates, no .specify/product/visuals/ |
 | 0.8.12+adlc13 | 2026-05-19 | 0.8.12 | Product extension v1.5.5: PDR lifecycle enforcement - mandatory memory promotion, state schema lifecycle fields, 9-check final gate |
 | 0.8.12+adlc12 | 2026-05-19 | 0.8.12 | Product extension v1.5.4: Fix self-contained PRD enforcement - Step 3.3 structure, embedding rules, prd-template .specify/ references |

extensions/architect/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to the Architect extension will be documented in this file.
 
+## [2.1.0] - 2026-05-20
+
+### Added
+
+- **Functional View template**: Technology Abstraction Rule and validation checklist
+  - Added explicit instruction to use architectural roles (Database, Object Storage) not product names
+  - Added forward cross-reference to Development View §3.5.2
+  - Added 5-point validation checklist for technology neutrality
+- **Development View template**: Enhanced structure for technology mapping
+  - Added §3.5.2 Technology Stack Mapping table (role → technology → ADR)
+  - Added §3.5.3 Technology Architecture diagram with concrete technology labels
+  - Added backward cross-reference to Functional View §3.2
+  - Added 5-point validation checklist for view parity
+- **Analyze Pass E.6**: Technology Neutrality check
+  - Scans Functional View for product/vendor names in elements and diagrams
+  - Distinguishes architectural roles (acceptable) from product names (flagged)
+  - Severity: MEDIUM (reported, not blocking)
+- **Analyze Pass E.7**: Functional-Development Mapping check
+  - Verifies Technology Stack Mapping table exists in Development View
+  - Checks that Functional View elements have corresponding mapping entries
+  - Supports N:1 mappings (multiple elements → one technology)
+  - Severity: MEDIUM if elements missing, LOW if table absent
+- **Config options**: `technology_neutrality` and `view_parity` toggles in `analysis:` section
+
+### Changed
+
+- Development View section renumbering:
+  - §3.5.2 → §3.5.4 (Module Dependencies)
+  - §3.5.3 → §3.5.5 (Build & CI/CD)
+  - §3.5.4 → §3.5.6 (Development Standards)
+- Functional View template example: `[e.g., REST /auth/*]` → `[e.g., API /auth/*]` (technology-neutral)
+
 ## [2.0.8] - 2026-05-17
 
 ### Fixed

extensions/architect/commands/analyze.md

@@ -235,21 +235,35 @@ For each ADR:
    - Consistent styling across diagrams
 
 5. **View File Consistency** (DAG State Validation):
-   - Check if `.specify/architect/state.json` exists and reports views as "completed"
-   - Check if `.specify/architect/views/` directory exists
-   - Verify that for each "completed" view in state.json, a corresponding file exists on disk
-   - **Flag as HIGH severity if**:
-     - state.json reports views "completed" but views/ directory is empty
-     - View files exist but are under 20 lines (placeholder/skeleton content)
-     - View files cannot be read (corrupted/missing permissions)
-   - **Report format**:
-     ```
-     DAG State Inconsistency Detected:
-     - State reports: [N] views completed
-     - Files on disk: [M] view files found
-     - Missing files: [list of missing views]
-     - Recommendation: Regenerate views or reset state.json
-     ```
+    - Check if `.specify/architect/state.json` exists and reports views as "completed"
+    - Check if `.specify/architect/views/` directory exists
+    - Verify that for each "completed" view in state.json, a corresponding file exists on disk
+    - **Flag as HIGH severity if**:
+      - state.json reports views "completed" but views/ directory is empty
+      - View files exist but are under 20 lines (placeholder/skeleton content)
+      - View files cannot be read (corrupted/missing permissions)
+    - **Report format**:
+      ```
+      DAG State Inconsistency Detected:
+      - State reports: [N] views completed
+      - Files on disk: [M] view files found
+      - Missing files: [list of missing views]
+      - Recommendation: Regenerate views or reset state.json
+      ```
+
+6. **Technology Neutrality** (Functional View):
+    - Scan Functional View (§3.2) for product/vendor names in element descriptions and Mermaid diagrams
+    - **Architectural roles** (acceptable): Database, Object Storage, Cache, Message Queue, AI Gateway, Workflow Runtime, App Shell, API Gateway, Authentication Service, etc.
+    - **Product names** (flag as MEDIUM): PostgreSQL, Neon, Vercel, Next.js, Redis, MongoDB, AWS, Azure, S3, etc.
+    - **Severity**: MEDIUM - Not blocking but indicates abstraction violation
+    - **Note**: ADR Traceability sections may reference products (that's acceptable); only flag element descriptions and diagram labels
+
+7. **Functional-Development Mapping**:
+    - Verify Development View (§3.5) contains a Technology Stack Mapping table (§3.5.2)
+    - Check that every element in Functional View's element table (§3.2.1) has at least one corresponding entry in the mapping table
+    - N:1 mappings (multiple functional elements → one technology) are acceptable
+    - **Severity**: MEDIUM if elements are missing; LOW if mapping table is absent
+    - **Cross-check**: Technology Architecture diagram (§3.5.3) should mirror Functional View diagram (§3.2.2) structure
 
 #### Pass F: Staleness Detection
 

extensions/architect/config-template.yml

@@ -32,3 +32,7 @@ analysis:
   # Severity thresholds for blocking
   block_on_critical: true
   block_on_high: false
+  
+  # View consistency checks (Pass E)
+  technology_neutrality: true    # E.6: Check functional view uses architectural roles, not product names
+  view_parity: true              # E.7: Check functional elements map to development technologies

extensions/architect/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "architect"
   name: "Architect - ADR & Architecture Description"
-  version: "2.0.8"
+  version: "2.1.0"
   description: "Create and manage Architecture Decision Records (ADRs) and Architecture Descriptions (AD.md) using Rozanski & Woods Viewpoints and Perspectives methodology"
   author: "Agentic SDLC Team"
   repository: "https://github.com/tikalk/agentic-sdlc-spec-kit"

extensions/architect/templates/views/development.md

@@ -11,6 +11,8 @@
 
 **Purpose**: Constraints for developers - code organization, dependencies, CI/CD
 
+> This view maps Functional View §3.2 architectural roles to specific technologies. See §3.5.2 for the technology stack mapping.
+
 ### 3.5.1 Code Organization
 
 ```text
@@ -27,7 +29,50 @@ project-root/
 └── infra/                # Infrastructure as code
 ```
 
-### 3.5.2 Module Dependencies
+### 3.5.2 Technology Stack Mapping
+
+Maps Functional View (§3.2) architectural roles to concrete technology choices.
+
+| Functional Role | Technology Choice | Version/Variant | ADR Reference |
+|-----------------|-------------------|-----------------|---------------|
+| App Shell | [e.g., Next.js 14] | [e.g., App Router] | [ADR-XXX] |
+| Database | [e.g., Neon PostgreSQL] | [e.g., Serverless] | [ADR-XXX] |
+| Object Storage | [e.g., Vercel Blob] | | [ADR-XXX] |
+| AI Gateway | [e.g., Vercel AI Gateway] | | [ADR-XXX] |
+| Workflow Runtime | [e.g., Vercel Workflow] | | [ADR-XXX] |
+
+**Mapping Rules:**
+- N:1 mappings allowed (multiple functional elements → one technology)
+- Every technology choice MUST reference a supporting ADR
+- Generic roles (Database) map to specific products (Neon PostgreSQL)
+
+### 3.5.3 Technology Architecture
+
+Concrete instantiation of Functional View §3.2.2 element interactions using specific technologies.
+
+```mermaid
+graph TD
+    %% Technology-specific labels mapped from Functional View
+    AppImpl["[Technology]<br/>[Variant]"]:::implNode
+    DBImpl["[Technology]<br/>[Variant]"]:::implNode
+    StorageImpl["[Technology]<br/>[Variant]"]:::implNode
+    AIGWImpl["[Technology]<br/>[Variant]"]:::implNode
+    WorkflowImpl["[Technology]<br/>[Variant]"]:::implNode
+    
+    AppImpl -->|ORM/Client| DBImpl
+    AppImpl -->|SDK| StorageImpl
+    AppImpl -->|API Routes| AIGWImpl
+    AppImpl -->|Triggers| WorkflowImpl
+    
+    classDef implNode fill:#e67e22,stroke:#333,stroke-width:2px,color:#fff
+```
+
+**Diagram Guidelines:**
+- Mirror the structure of Functional View §3.2.2
+- Replace generic labels with concrete technology names
+- Include connection mechanisms (SDK, ORM, API, etc.)
+
+### 3.5.4 Module Dependencies
 
 **Dependency Rules:**
 
@@ -48,13 +93,13 @@ graph LR
     class API,SVC,REPO layer
 ```
 
-### 3.5.3 Build & CI/CD
+### 3.5.5 Build & CI/CD
 
 - **Build System**: [e.g., npm, gradle, cargo]
 - **CI Pipeline**: [Key stages]
 - **Deployment Strategy**: [e.g., Blue-green, rolling]
 
-### 3.5.4 Development Standards
+### 3.5.6 Development Standards
 
 - **Coding Standards**: [e.g., ESLint config, PEP 8]
 - **Review Requirements**: [e.g., 2 approvals]
@@ -96,6 +141,18 @@ _Source ADRs: [ADR-XXX]_
 
 ---
 
+## Validation Checklist
+
+Before finalizing this view, verify:
+
+- [ ] **Technology Mapping**: Every Functional View §3.2 element has a corresponding entry in §3.5.2 (N:1 mappings acceptable)
+- [ ] **ADR References**: Every technology choice in §3.5.2 references a supporting ADR
+- [ ] **Diagram Parity**: Technology Architecture diagram (§3.5.3) mirrors Functional View diagram structure
+- [ ] **Code Alignment**: Code organization reflects the technology stack choices
+- [ ] **Dependency Rules**: Module dependencies are consistent with technology constraints
+
+---
+
 **ADR Traceability:**
 
 | ADR | Decision | Impact on Development View |

extensions/architect/templates/views/functional.md

@@ -11,11 +11,15 @@
 
 **Purpose**: Describe functional elements, their responsibilities, and interactions
 
+> **Technology Abstraction Rule**: Elements must be described by **architectural role** (Database, Object Storage, Cache, Message Queue, AI Gateway, Workflow Runtime, App Shell, etc.) — never by product name. This view captures *what* the system does, not *how* it's implemented.
+>
+> See Development View §3.5.2 for concrete technology choices mapped to these elements.
+
 ### 3.2.1 Functional Elements
 
 | Element | Responsibility | Interfaces Provided | Dependencies |
 |---------|----------------|---------------------|--------------|
-| [COMPONENT_1] | [e.g., User authentication] | [e.g., REST /auth/*] | [e.g., Database] |
+| [COMPONENT_1] | [e.g., User authentication] | [e.g., API /auth/*] | [e.g., Database] |
 | [COMPONENT_2] | [Responsibility] | [Interfaces] | [Dependencies] |
 
 ### 3.2.2 Element Interactions
@@ -87,6 +91,18 @@ _Source ADRs: [ADR-XXX]_
 
 ---
 
+## Validation Checklist
+
+Before finalizing this view, verify:
+
+- [ ] **Technology Neutrality**: All elements described by architectural role, not product name (Database, not PostgreSQL; Object Storage, not S3)
+- [ ] **Diagram Consistency**: Mermaid diagram nodes use generic labels matching the element table
+- [ ] **Interface Abstraction**: Interfaces describe capabilities, not implementation protocols
+- [ ] **Complete Coverage**: Every major functional responsibility is represented
+- [ ] **Clear Boundaries**: "What system DOES" and "does NOT do" are clearly articulated
+
+---
+
 **ADR Traceability:**
 
 | ADR | Decision | Impact on Functional View |

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentic-sdlc-specify-cli"
-version = "0.8.12+adlc14"
+version = "0.8.12+adlc15"
 description = "Specify CLI (tikalk fork). Agentic SDLC toolkit for Spec-Driven Development with pre-installed extensions and AI integrations."
 requires-python = ">=3.11"
 dependencies = [