archspec 1.6.2 → 1.6.4

package/lib/init.js

@@ -1,9 +1,15 @@
 const createFolderWithFiles = require("./createFolderWithFiles");
 const architectureTemplates = require("./templates/architecture");
+const governanceTemplates = require("./templates/governance");
+const implementationTemplates = require("./templates/implementation");
+const executionTemplates = require("./templates/execution");
 
 function init() {
   createFolderWithFiles("architecture", architectureTemplates);
-  console.log("Architecture folder initialized.");
+  createFolderWithFiles("governance", governanceTemplates);
+  createFolderWithFiles("implementation", implementationTemplates);
+  createFolderWithFiles("execution", executionTemplates);
+  console.log("Architecture, Governance, Implementation and Execution folders initialized.");
 }
 
 module.exports = init;

package/lib/templates/execution.js

@@ -0,0 +1,136 @@
+const executionTemplates = {
+    "README.md": `# Execution
+  
+  This directory defines how approved implementation decisions are executed.
+  
+  Execution does NOT define architecture.
+  Execution does NOT define implementation structure.
+  
+  Execution translates approved decisions into:
+  
+  - Phased delivery
+  - Tasks
+  - Testing
+  - Operational tracking
+  
+  If it is not tied to an approved decision, it must not be executed.
+  `,
+  
+    "execution-plan.md": `# Execution Plan
+
+## Phase 1 – Backend Core
+
+Layers:
+- Infra (Node + TS config)
+- DAL
+- Services
+- Controllers
+- Routes
+
+Deliverables:
+- Server starts successfully
+- SQLite DB connected
+- Endpoints respond correctly
+
+Testing Requirements:
+- Unit tests for Services
+- Integration tests for Controllers
+- Route-level tests using supertest
+- Prisma schema migration verified
+
+Completion Criteria:
+- \`npm test\` passes
+- All endpoints reachable
+
+## Phase 2 – Frontend Core
+
+Layers:
+- Infra (Vite config)
+- API Service
+- FE Services
+- Context
+- Components
+
+Testing Requirements:
+- Unit tests for FE Services
+- Context tests
+- Component tests (React Testing Library)
+
+Completion Criteria:
+- UI renders
+- Data loads
+- Form submission works
+
+## Phase 3 – E2E
+
+- Playwright or Cypress
+- Full user flow:
+  - Fetch random question
+  - Submit answer
+  - Reload page
+  - Verify persisted data appears
+  `,
+  
+    "test-strategy.md": `# Test Strategy
+
+## Backend
+- Jest
+- supertest
+- SQLite test DB
+
+## Frontend
+- Vitest
+- React Testing Library
+
+## E2E
+- Playwright
+
+All implementation phases must include:
+- Passing unit tests
+- No console errors
+- No TypeScript errors
+  `,
+  
+    "open-questions.md": `Example Structure:
+
+# Open Questions Log
+
+## Q-001
+Context: API Service
+Question: Should base URL differ between dev and prod?
+Status: Open
+
+## Q-002
+Context: DAL
+Question: Should timestamps be ISO strings or Date objects?
+Status: Open
+
+-----
+
+Add REAL open questions below, following the above structure EXACLY
+  `,
+  
+    "agents-prompts.md": `You are the Implementation Execution Agent.
+
+Your job is to implement the project according to:
+
+- architecture/architecture.md
+- implementation/implementation.md
+- execution/execution-plan.md
+- execution/test-strategy.md
+
+Rules:
+- If any ambiguity or missing detail appears, append question to open-questions.md instead of guessing.
+- Do NOT guess missing requirements
+- Implement phase-by-phase
+- After completing each phase, ensure all defined tests pass
+- Add unit tests for each implemented layer
+- Add integration tests where applicable
+- Add E2E tests in final phase
+- Do NOT modify architecture or implementation documents
+- Stop after each phase and report status
+  `
+  };
+  
+  module.exports = executionTemplates;
+  

package/lib/templates/governance.js

@@ -0,0 +1,280 @@
+const governanceTemplates = {
+    "README.md": `# Governance
+  
+  This directory defines how architectural and implementation consistency is enforced.
+  
+  Governance ensures:
+  
+  - Contracts are respected
+  - Layer boundaries are preserved
+  - Deterministic generation is maintained
+  - No cross-layer drift occurs
+  
+  Governance files must not contain business logic.
+  They only enforce structural invariants.
+  `,
+  
+    "flow.md": `# Governance Flow
+
+This document defines the deterministic governance lifecycle between:
+
+- Architecture
+- Implementation
+- Cross-layer consistency
+
+This flow must be followed strictly.
+
+---
+
+# Phase 1 — Architecture Update
+
+1. Run a Layer Architecture Agent.
+2. Validate using Architect Validator Agent.
+3. Approve the decision (\`Status: approved\`).
+4. Run Architecture Writer Agent.
+5. \`architecture.md\` is regenerated.
+
+Architecture is now the authoritative specification.
+
+---
+
+# Phase 2 — Implementation Alignment
+
+1. Run Implementation Consistency Agent.
+2. If output is:
+
+   OK
+
+   → No action required.
+
+3. If violations are reported:
+
+   → Re-run ONLY the impacted Implementation Layer Agents.
+   → Validate with Implementation Validator Agent.
+   → Approve updated decisions.
+   → Run Implementation Writer Agent.
+   → Regenerate \`implementation.md\`.
+
+Repeat until Consistency Agent outputs:
+
+OK
+
+---
+
+# Phase 3 — Execution
+
+Once:
+
+- Architecture Validator → OK
+- Implementation Validator → OK
+- Consistency Agent → OK
+
+The system is considered structurally aligned.
+
+Development and execution may proceed.
+
+---
+
+# Hard Rules
+
+❌ Do NOT manually edit \`architecture.md\`  
+❌ Do NOT manually edit \`implementation.md\`  
+❌ Do NOT re-run all agents blindly  
+❌ Do NOT bypass the Consistency Agent  
+
+✅ Always validate before regenerating  
+✅ Only re-run impacted layer agents  
+✅ Delete + regenerate artifacts freely  
+
+---
+
+# Mental Model
+
+architecture.decisions.md → Specification  
+implementation.decisions.md → Realization  
+consistency-agent → Type
+  `,
+  
+    "contract-enforcement-agent.md": `# Architecture–Implementation Consistency Agent
+
+You are the Architecture–Implementation Consistency Agent.
+
+Your role is to verify that implementation decisions conform to approved architectural contracts.
+
+You MUST perform all reasoning internally.
+
+You MUST NOT display:
+- Any validation traces
+- Any intermediate checks
+- Any contract evaluation details
+- Any explanations
+
+Your entire output MUST strictly match the Output Format section.
+
+You are NOT allowed to:
+- Edit any files
+- Propose new decisions
+- Explain reasoning
+- Summarize
+- Infer intent
+- Output anything other than the strict result format
+
+---
+
+## Inputs
+
+You must read:
+
+- architecture/architecture.decisions.md
+- implementation/implementation.decisions.md
+
+You must consider ONLY decisions with:
+
+Status: approved
+
+Ignore all proposed decisions.
+
+---
+
+## Validation Rules
+
+For each architecture layer:
+
+1. Extract approved architectural decisions.
+2. If a decision contains a \`Contracts:\` section:
+   - Each contract entry is a required invariant.
+3. For each contract entry:
+   - Verify that the corresponding implementation layer contains a decision that satisfies that invariant.
+   - Matching must be structural and explicit.
+   - Do NOT rely on semantic interpretation of prose.
+   - If a required contract is missing or contradicted, mark it as a violation.
+
+If an architecture layer contains no Contracts section:
+- Skip structural validation for that layer.
+
+---
+
+## Output Format (STRICT)
+
+You must output EXACTLY one of the following:
+
+1) If no violations are found:
+
+OK
+
+OR
+
+2) If violations are found:
+
+A bullet list of violations in the following format:
+
+- Layer: <LayerName> — Missing contract: <contract key>
+- Layer: <LayerName> — Violates contract: <contract key>
+
+No additional text.
+No explanation.
+No reasoning.
+No headers.
+No summaries.
+No validation traces.
+No empty lines before or after.
+
+If there are no violations, output ONLY:
+
+OK
+  `,
+  
+    "structural-consistency-agent.md": `# Structural Consistency Agent
+
+You are the Structural Consistency Agent.
+
+Your role is to verify that implementation decisions structurally conform to approved architectural decisions.
+
+You are NOT allowed to:
+- Edit any files
+- Propose new decisions
+- Explain reasoning
+- Summarize
+- Infer intent
+- Output anything other than the strict result format
+
+You MUST perform all reasoning internally.
+
+You MUST NOT display:
+- Any validation traces
+- Any intermediate checks
+- Any contract evaluation details
+- Any explanations
+
+---
+
+## Inputs
+
+You must read:
+
+- architecture/architecture.decisions.md
+- implementation/implementation.decisions.md
+
+You must consider ONLY decisions with:
+
+Status: approved
+
+Ignore all proposed decisions.
+
+---
+
+## Validation Rules
+
+For each layer:
+
+1. Extract approved architectural decisions.
+2. Extract approved implementation decisions for the same layer.
+
+Then validate:
+
+- Implementation does not contradict architectural boundaries.
+- Implementation does not introduce structural paths that violate architectural topology.
+- Implementation paths match architectural topology (e.g., monorepo vs single-app).
+- Implementation dependency direction respects architectural dependency rules.
+- Implementation does not reference layers that architecture forbids.
+
+This validation must be structural.
+
+Do NOT rely on semantic interpretation.
+Do NOT infer intent.
+Only flag explicit structural inconsistencies.
+
+---
+
+## Output Format (STRICT)
+
+You must output EXACTLY one of the following:
+
+1) If no violations are found:
+
+OK
+
+OR
+
+2) If violations are found:
+
+A bullet list of violations in the following format:
+
+- Layer: <LayerName> — Structural mismatch: <short description>
+
+No additional text.
+No explanation.
+No reasoning.
+No headers.
+No summaries.
+No validation traces.
+No empty lines before or after.
+
+If there are no violations, output ONLY:
+
+OK
+  `
+  };
+  
+  module.exports = governanceTemplates;
+  

package/lib/templates/implementation.js

@@ -0,0 +1,355 @@
+const implementationTemplates = {
+    "current-project-desc.md": `# Current Project Description`,
+    "README.md": `# Implementation Governance
+
+This directory defines how stack-specific implementation decisions are created and maintained.
+
+## Relationship to Architecture
+- Layer structure and responsibilities are inherited from \`/architecture\`.
+- Implementation decisions may not redefine, rename, reorder, or remove architectural layers.
+- Implementation must respect all approved architectural boundaries.
+
+## Source of Truth
+- \`implementation.decisions.md\` is the ONLY source of truth for stack-specific realization.
+- \`implementation.md\` is a GENERATED artifact and must never be edited manually.
+
+## Core Rules
+1. All implementation changes are expressed as Decisions.
+2. Each Decision belongs to exactly ONE layer (as defined in \`/architecture\`).
+3. Only Decisions with \`Status: approved\` are applied.
+4. Agents may NOT edit \`implementation.md\`.
+5. \`implementation.md\` can be deleted and regenerated at any time.
+
+## Scope of Implementation Decisions
+Implementation decisions define how architectural layers are realized in this project and may specify:
+- Frameworks and libraries
+- Folder structure and file organization
+- Dependency injection patterns
+- Validation libraries
+- Transport clients
+- Testing frameworks
+- Tooling and build configuration
+
+Implementation decisions may NOT:
+- Change layer responsibilities
+- Introduce, remove, or rename architectural layers
+- Modify dependency direction between layers
+- Override approved architectural decisions
+
+## Workflow
+1. Layer implementation agent proposes a Decision (\`Status: proposed\`)
+2. Human reviews and approves the Decision
+3. Implementation writer agent regenerates \`implementation.md\`
+
+If it is not a Decision, it is not implementation.
+
+## Operation
+
+For daily usage and workflow, see:
+
+- \`flow.md\` – Implementation decision lifecycle
+- \`agent-prompts.md\` – Agent definitions
+- \`init.md\` – Initial setup instructions
+
+## Project Context
+
+This implementation system operates within the context of the current project description.
+
+See:
+
+- \`current-project-desc.md\` – Functional description and goals of this project
+
+All implementation decisions must align with this document while respecting architectural boundaries.
+  `,
+  
+    "flow.md": `
+## The daily workflow (this is the loop)
+
+### Step A – Propose
+
+* Run a **layer agent**
+* It appends a \`Status: proposed\` decision to \`implementation.decisions.md\`
+
+### Step B – Validate
+
+* Run **Implementation Validator Agent**
+* Fix or clarify decision if blocked
+
+### Step C – Approve (YOU)
+
+* Change **one word**:
+
+  \`Status: approved\`
+
+### Step D – Generate
+
+* Run **Writer Agent**
+* \`implementation.md\` is regenerated fully
+
+That’s it.
+
+---
+
+## Hard rules (do not break these)
+
+* ❌ No agent edits \`implementation.md\`
+* ❌ No decision spans multiple layers
+* ❌ No prose inside decisions
+* ❌ No incremental edits to implementation.md
+* ✅ Delete + regenerate is always safe
+
+If these rules hold → system is deterministic.
+
+---
+
+## Mental model (for Cursor usage)
+
+* \`implementation.decisions.md\` = **config**
+* Writer agent = **compiler**
+* \`implementation.md\` = **build artifact**
+* You = **approver of intent**
+* Cursor = **execution environment**
+
+---
+
+<!-- ## Optional (but powerful, later)
+
+* Add Decision IDs enforcement
+* Add a script that deletes + regenerates implementation.md
+* Add a CI check that fails if implementation.md is edited manually -->
+
+---
+
+### Final checkpoint
+
+If you can:
+
+* delete \`implementation.md\`
+* regenerate it
+* get the same result
+
+✅ You’ve set it up correctly.
+  `,
+  
+    "init.md": `# Cursor Setup: Deterministic Bottom-Up Architecture
+
+## 1. Create the files (once)
+
+In your repo root:
+
+/implementation
+  ├─ implementation.decisions.md ← ONLY editable implementation truth
+  ├─ implementation.md           ← GENERATED, read-only
+  ├─ README.md                   ← governance
+  └─ agent-prompts.md            ← implementation agents
+
+---
+
+## 2. Initialize \`implementation.decisions.md\`
+
+Paste this exactly:
+
+Paste this exactly, until the line \`-- END OF PASTING --\`:
+
+# Implementation Decisions
+
+## Rules
+- Decisions are the ONLY source of truth
+- implementation.md is generated, never edited
+- Every decision belongs to exactly ONE layer
+- Only decisions with Status: approved are applied
+
+## Layers (fixed)
+{
+    TAKE LAYERS FROM architecture/README.md > Layers (Fixed)
+    write each layer in a new line by order with ## before the name
+}
+
+-- END OF PASTING --
+
+This file is **the system state**.
+
+### Mapping for creating identical prompts from agents-prompts.md:
+same as Mapping for creating identical prompts from architecture/agents-prompts.md, just replace the 'D-' with 'I-',
+example:
+- DAL → \`I-DAL-XXX\`
+
+---
+
+## 3. Create Cursor Agents Prompts (THIS IS KEY)
+
+- Create prompt for **one agent per layer** 
+- follow instructions in implementation/agents-prompts.md
+  `,
+  
+    "implementation.md": `<!-- GENERATED FILE – DO NOT EDIT -->
+  
+  # Implementation
+  
+  This file is generated from implementation.decisions.md
+  `,
+  
+    "implementation.decisions.md": `# Implementation Decisions
+  
+  ## Rules
+  - Decisions are the ONLY source of truth
+  - implementation.md is generated, never edited
+  - Every decision belongs to exactly ONE layer
+  - Only decisions with Status: approved are applied
+  
+  ## Layers (fixed)
+  - Infra
+  - DAL
+  - Services
+  - Controllers
+  - Routes
+  - API Service
+  - FE Services
+  - Context
+  - Components
+  
+  ---
+  
+  ## Infra
+  
+  ## DAL
+  
+  ## Services
+  
+  ## Controllers
+  
+  ## Routes
+  
+  ## API Service
+  
+  ## FE Services
+  
+  ## Context
+  
+  ## Components
+  `,
+  "agents-prompts.md": `# Implementation Agent Prompts
+
+This document defines the exact prompts used to operate the implementation system in this repository.
+
+These prompts are part of implementation governance and must remain stable.
+
+Layer structure is inherited from \`/architecture\`.
+Implementation may not redefine or modify architectural layers.
+
+---
+
+## 1. Layer Implementation Agent (Template)
+
+Use **one instance per layer**.
+Duplicate this prompt and hard-code the layer name.
+
+### Example: DAL Implementation Agent
+
+You are the DAL Implementation Agent.
+
+Rules:
+- Read implementation/implementation.decisions.md
+- Respect boundaries and Contracts defined in architecture/architecture.decisions.md
+- If the architecture layer defines Contracts, your proposal must satisfy them
+- Compare existing approved decisions in your layer with current architecture contracts
+- If structural paths or dependencies violate architecture, propose a minimal corrective Decision
+- If an existing approved decision already satisfies architecture and Contracts, do NOT propose a replacement
+- Prefer additive or corrective decisions over rewriting existing ones
+- Propose NEW stack-specific decisions for the DAL layer ONLY
+- Do NOT redefine architectural responsibilities
+- Do NOT edit implementation.md
+- Do NOT modify or replace decisions outside your layer
+- Do NOT ask exploratory questions
+- Output ONLY a Decision block
+- If escalation is required, include the escalation bullet inside the Decision block as the final bullet
+- Decisions may reference technologies, libraries, file structure, or patterns
+- Only propose minimal corrective or additive decisions
+
+
+
+Output format (exact):
+
+[I-DAL-XXX]
+Layer: DAL
+Decision:
+- bullet
+- bullet
+Rationale:
+- short
+Confidence: High | Medium | Low
+Status: proposed
+
+### Layer name substitutions
+
+Create identical prompts with only the layer name changed according to mapping in init.md
+
+No other changes are allowed.
+
+---
+
+## 2. Implementation Validator Agent
+
+You are the Implementation Validator Agent.
+
+Rules:
+- Read implementation/implementation.decisions.md
+- Do NOT edit files
+- Do NOT propose new decisions
+- Validate proposed decisions by checking:
+  - Do not violate architectural boundaries
+  - Do not redefine layers
+  - Do not contradict approved architecture decisions
+  - Are stack-specific (not architectural)
+
+Output format is STRICT.
+
+You must output EXACTLY ONE of the following:
+
+1) OK
+
+OR
+
+2) A bullet list of blocking issues.
+
+Do NOT include:
+- Explanations
+- Summaries
+- Validation traces
+- Decision reviews
+- Any text before or after the output
+
+If there are no blocking issues, output ONLY:
+
+OK
+
+---
+
+## 3. Implementation Writer Agent (Deterministic Generator)
+
+You are a deterministic implementation document generator.
+
+Input:
+- implementation/implementation.decisions.md
+
+Rules:
+- Read ONLY implementation/implementation.decisions.md
+- You must NOT read architecture/architecture.decisions.md except to determine layer order
+- You must write ONLY implementation.md
+- You must NOT create, modify, or delete any other file
+- Ignore existing implementation.md
+- Generate implementation.md from scratch
+- Add comment on top <!-- GENERATED FILE – DO NOT EDIT -->
+- Apply ONLY decisions with Status: approved
+- Preserve bullet wording exactly
+- Do NOT rephrase, summarize, or infer
+- Use layer order inherited from architecture/architecture.decisions.md
+- Do NOT emit a "Layers" list; layers are represented only by section headers
+- No creative language
+
+Output:
+- A complete implementation.md`
+  };
+  
+  module.exports = implementationTemplates;
+  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archspec",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "description": "Architecture governance scaffolding CLI for structured project execution.",
   "bin": {
     "archspec": "./index.js"