@zigrivers/scaffold 2.1.0

package/knowledge/validation/decision-completeness.md

@@ -0,0 +1,218 @@
+---
+name: decision-completeness
+description: Verifying all architectural decisions are recorded, justified, and non-contradictory
+topics: [validation, decisions, adrs, completeness, contradictions]
+---
+
+# Decision Completeness
+
+Decision completeness validation ensures that every architectural and design decision made during the pipeline has been explicitly recorded in an ADR, that no decisions contradict each other, and that no deferred decisions remain unresolved before implementation begins.
+
+## Why Decision Completeness Matters
+
+Unrecorded decisions become tribal knowledge. When AI agents implement the system, they have no tribal knowledge — only documented decisions. Every implicit "we agreed that..." or "obviously we'd use..." that is not in an ADR is a gap that will cause agents to guess, and guesses introduce inconsistency.
+
+## What to Check
+
+### 1. Explicit Decision Extraction
+
+Walk through every artifact and extract every explicit decision.
+
+**Where explicit decisions live:**
+- **ADRs** — The primary home. Each ADR records a decision, its context, and consequences.
+- **Architecture document** — Technology choices, pattern selections, component organization.
+- **Database schema** — Choice of database type, normalization level, indexing strategy.
+- **API contracts** — Choice of API style (REST/GraphQL), versioning strategy, auth mechanism.
+- **UX spec** — Framework choice, design system decisions, accessibility level target.
+- **Task breakdown** — Sequencing decisions, parallelization choices.
+- **Testing strategy** — Test framework, coverage targets, test environment setup.
+- **Operations runbook** — Deployment strategy, CI/CD tool choice, monitoring approach.
+
+**Process:**
+1. Read each artifact sequentially.
+2. For every statement that represents a choice between alternatives, extract it:
+   - "We use PostgreSQL" — this is a decision.
+   - "Authentication is handled via JWT tokens" — this is a decision.
+   - "The frontend uses React" — this is a decision.
+   - "We follow trunk-based development" — this is a decision.
+3. Record the decision, the artifact it appears in, and whether it has a corresponding ADR.
+
+### 2. Implied Decision Mining
+
+Many decisions are implied rather than stated. These are harder to find but equally important.
+
+**Techniques for finding implied decisions:**
+
+**Absence-based detection** — Ask "what was NOT chosen?" If the architecture uses REST, there is an implied decision not to use GraphQL. If the schema uses PostgreSQL, there is an implied decision not to use MongoDB. Each such absence is a decision that may need an ADR.
+
+**Convention-based detection** — When an artifact follows a specific pattern without justification, that is an implied decision. "All endpoints return JSON" — decided but not documented. "Errors follow RFC 7807" — decided but not documented.
+
+**Technology-stack detection** — Extract the full technology stack from all artifacts. Each technology is a decision. Common technologies that often lack ADRs:
+- Package manager (npm vs yarn vs pnpm)
+- ORM or query builder
+- Logging library
+- Date/time library
+- Validation library
+- State management approach
+- Test runner and assertion library
+- CSS approach (modules, Tailwind, styled-components)
+- Linter and formatter configuration
+
+**Pattern-based detection** — Scan for phrases that indicate undocumented decisions:
+- "We decided to..." (but no ADR exists)
+- "The approach is..." (implies alternatives were considered)
+- "For simplicity..." (implies a trade-off was made)
+- "Following best practices..." (implies a specific practice was chosen)
+- "Using the standard..." (implies a standard was selected)
+
+**Assumption-based detection** — When one artifact assumes something about another, there may be an undocumented decision behind the assumption. "The API assumes eventual consistency for order status updates" — was that decided? By whom? What are the consequences?
+
+### 3. ADR Coverage Verification
+
+For every extracted decision (explicit and implied), verify:
+
+1. **An ADR exists** — The decision is recorded in a numbered ADR document.
+2. **The ADR has context** — Why was this decision needed? What problem was being solved?
+3. **The ADR has rationale** — Why was this option chosen over alternatives?
+4. **Alternatives were considered** — At least for significant decisions, alternatives should be listed.
+5. **Consequences are documented** — What are the positive and negative consequences?
+6. **Status is current** — The ADR status is "accepted" (not "proposed" or "deprecated" without a replacement).
+
+### 4. Contradiction Detection
+
+Contradictions occur when two decisions conflict. They are especially dangerous because each may be internally consistent — the conflict only appears when both are considered together.
+
+**Where contradictions hide:**
+
+**Cross-ADR contradictions** — Two ADRs make conflicting choices. Example: ADR-005 mandates "all inter-service communication via REST" and ADR-012 mandates "order events are published to a message queue." These may or may not contradict depending on whether the message queue counts as inter-service communication.
+
+**ADR-vs-artifact contradictions** — An ADR mandates one approach, but an artifact implements a different one. Example: ADR-003 says "use bcrypt for password hashing" but the auth service implementation task references "argon2."
+
+**Cross-artifact contradictions** — Two artifacts make different assumptions about the same thing. Example: API contracts define pagination with `page` and `pageSize` parameters, but the UX spec assumes cursor-based pagination with `after` tokens.
+
+**Detection process:**
+1. Group decisions by topic (database, authentication, API style, deployment, etc.).
+2. Within each topic, compare all decisions for consistency.
+3. For each pair of potentially conflicting decisions, determine:
+   - Are they actually about the same thing?
+   - Can both be true simultaneously?
+   - If not, which takes precedence and why?
+
+### 5. Deferred Decision Resolution
+
+During earlier pipeline phases, some decisions may have been explicitly deferred with "we'll decide later" or "TBD" annotations. By validation time, these should be resolved.
+
+**Process:**
+1. Search all artifacts for deferred-decision indicators:
+   - "TBD", "TODO", "to be decided", "to be determined"
+   - "deferred", "will decide later", "pending decision"
+   - "open question", "needs investigation", "spike needed"
+   - Question marks in decision contexts ("PostgreSQL or MongoDB?")
+2. For each deferred item, determine:
+   - Has it been silently resolved in a later artifact? (If so, add the ADR.)
+   - Is it still genuinely unresolved? (If so, it must be resolved before implementation.)
+   - Was it rendered moot by another decision? (If so, document why.)
+
+## Decision Categories Checklist
+
+Use this checklist to verify that all common decision categories have been addressed:
+
+### Infrastructure & Platform
+- [ ] Cloud provider / hosting platform
+- [ ] Programming language(s) and version(s)
+- [ ] Runtime environment (Node.js version, Python version, etc.)
+- [ ] Package manager
+- [ ] Containerization approach (Docker, etc.)
+- [ ] CI/CD pipeline tool
+
+### Data
+- [ ] Primary database type and product
+- [ ] Caching strategy and product (if applicable)
+- [ ] Search engine (if applicable)
+- [ ] Message queue / event bus (if applicable)
+- [ ] File/blob storage (if applicable)
+- [ ] Data migration strategy
+
+### API & Communication
+- [ ] API style (REST, GraphQL, gRPC)
+- [ ] API versioning strategy
+- [ ] Authentication mechanism
+- [ ] Authorization model
+- [ ] Real-time communication (WebSockets, SSE, polling)
+
+### Frontend (if applicable)
+- [ ] Frontend framework
+- [ ] State management approach
+- [ ] CSS / styling approach
+- [ ] Component library (build vs buy)
+- [ ] Routing approach (client-side, server-side, hybrid)
+- [ ] Build tool
+
+### Quality
+- [ ] Test framework(s) and runner(s)
+- [ ] Coverage targets
+- [ ] Linting and formatting tools
+- [ ] Code review process
+- [ ] Error tracking / monitoring tool
+
+### Operations
+- [ ] Deployment strategy (rolling, blue-green, canary)
+- [ ] Environment management (staging, production)
+- [ ] Logging approach and tool
+- [ ] Monitoring and alerting tool
+- [ ] Secret management approach
+- [ ] Backup and disaster recovery
+
+### Process
+- [ ] Branching strategy (trunk-based, GitFlow, feature branches)
+- [ ] Commit message format
+- [ ] PR and merge strategy
+- [ ] Release versioning scheme
+
+## Output Format
+
+### Decision Inventory
+
+```markdown
+| # | Decision | Source | ADR? | Status |
+|---|----------|--------|------|--------|
+| 1 | Use PostgreSQL 16 | Architecture doc §4.2 | ADR-007 | Covered |
+| 2 | JWT for auth | API contracts §2.1 | ADR-003 | Covered |
+| 3 | React 19 for frontend | UX spec §1.1 | MISSING | Needs ADR |
+| 4 | Use pnpm | Task breakdown §setup | MISSING | Needs ADR |
+| 5 | TBD: caching strategy | Architecture doc §5.3 | — | Unresolved |
+| 6 | REST for all APIs | ADR-005 | ADR-005 | Contradicted by ADR-012 |
+```
+
+### Contradiction Report
+
+```markdown
+## Contradiction: API Communication Style
+
+**Decision A:** ADR-005 — "All inter-service communication uses REST endpoints"
+**Decision B:** ADR-012 — "Order state changes are published to a message queue for downstream consumers"
+
+**Analysis:** These decisions conflict if message queue communication is considered inter-service communication. If ADR-005 intends only synchronous request-response, the contradiction is real.
+
+**Recommended Resolution:** Amend ADR-005 to clarify scope: "Synchronous inter-service communication uses REST. Asynchronous event distribution uses the message queue per ADR-012."
+```
+
+### Deferred Decision Report
+
+```markdown
+## Unresolved: Caching Strategy
+
+**Source:** Architecture document §5.3 — "Caching strategy TBD based on load testing results"
+**Impact:** Without a caching decision, the operations runbook cannot define cache invalidation procedures, and the architecture cannot specify cache layers.
+**Recommendation:** Make a provisional decision (e.g., Redis with read-through caching for frequently accessed entities) and record as an ADR. Note that it may be revisited after load testing.
+```
+
+## Prioritizing Findings
+
+Not all missing ADRs are equally important. Prioritize by impact:
+
+- **Critical** — Decisions that affect system architecture, data model, or security. Missing these leads to incompatible implementations.
+- **Major** — Decisions that affect developer workflow, tooling, or operational procedures. Missing these leads to inconsistent practices.
+- **Minor** — Decisions about conventions, formatting, or low-impact library choices. Missing these is annoying but not dangerous.
+
+Focus resolution on critical and major findings. Minor findings can be resolved during implementation as they arise, as long as they are documented when made.

package/knowledge/validation/dependency-validation.md

@@ -0,0 +1,233 @@
+---
+name: dependency-validation
+description: Verifying dependency graphs are acyclic, complete, and correctly ordered
+topics: [validation, dependencies, graphs, cycles, ordering, parallelization]
+---
+
+# Dependency Validation
+
+Dependency validation extracts all dependency relationships between implementation tasks, builds a graph, checks for correctness, and verifies that the ordering matches architectural constraints. A valid dependency graph ensures that tasks can be executed in an order that never requires unbuilt dependencies.
+
+## What a Dependency Graph Represents
+
+Each node in the graph is an implementation task. Each directed edge represents a "must complete before" relationship: if task A depends on task B, then B must be completed before A can start.
+
+The graph encodes:
+- **Sequencing constraints** — What must happen before what.
+- **Parallelization opportunities** — Tasks with no dependency relationship can run simultaneously.
+- **Critical path** — The longest chain of sequential dependencies, which determines minimum project duration.
+- **Blocking risk** — Tasks that many other tasks depend on, whose delay blocks the most work.
+
+## How to Extract Dependencies
+
+### From the Task Breakdown
+
+Implementation tasks should have explicit dependency declarations. Extract these directly:
+
+```
+Task T-012: Set up database schema
+  Depends on: T-010 (database connection config)
+
+Task T-015: Implement user registration endpoint
+  Depends on: T-012 (user table must exist), T-011 (auth middleware)
+
+Task T-020: Build sign-up form
+  Depends on: T-015 (registration endpoint must exist)
+```
+
+### From Architecture Data Flows
+
+Data flow diagrams imply dependencies. If Component A sends data to Component B, then Component B's implementation depends on Component A's interface being defined (though not necessarily fully implemented — interface-first development can decouple this).
+
+### From Schema Dependencies
+
+Database schema has inherent ordering:
+- Tables with foreign keys depend on the referenced tables.
+- Migration scripts must run in order.
+- Seed data depends on table creation.
+
+### From API Contract Dependencies
+
+API implementation depends on:
+- Schema (data layer must exist for the API to read/write)
+- Auth middleware (if endpoints are protected)
+- External service clients (if the endpoint calls external services)
+
+### Implicit Dependencies to Look For
+
+Some dependencies are not stated but are real:
+
+1. **Shared configuration** — Multiple tasks may depend on environment setup, config files, or shared constants that no task explicitly produces.
+2. **Shared libraries** — Multiple tasks may depend on utility functions, custom error classes, or helper modules.
+3. **Framework scaffolding** — All tasks may depend on the initial project setup (package.json, tsconfig, linting config) which may or may not be its own task.
+4. **Test infrastructure** — Tests depend on test utilities, fixtures, and configuration that must be set up first.
+
+## Graph Validation Checks
+
+### 1. Cycle Detection
+
+A cycle means task A depends on B, B depends on C, and C depends on A. No task in the cycle can ever start because each is waiting for another.
+
+**Detection algorithm (Kahn's algorithm):**
+1. Compute the in-degree (number of incoming edges) for each node.
+2. Add all nodes with in-degree 0 to a queue.
+3. While the queue is not empty:
+   a. Remove a node from the queue.
+   b. For each outgoing edge from that node, decrement the in-degree of the target.
+   c. If the target's in-degree reaches 0, add it to the queue.
+4. If all nodes have been processed, the graph is acyclic.
+5. If nodes remain unprocessed, they are part of cycles.
+
+**What to do when cycles are found:**
+- Identify the minimal cycle (the smallest set of tasks that form a loop).
+- Determine which dependency is weakest — can it be broken by splitting a task or defining an interface?
+- Common resolution: split a task into "define interface" and "implement interface" — other tasks can depend on the interface definition without waiting for the full implementation.
+
+### 2. Completeness Check
+
+Every task referenced as a dependency must exist in the task list.
+
+**Process:**
+1. Collect all task IDs from the implementation tasks.
+2. Collect all task IDs referenced in dependency declarations.
+3. Any referenced ID not in the task list is an orphaned dependency.
+
+**Common causes:**
+- Task was removed or renamed but its dependents were not updated.
+- Dependency references a task from a different phase or project.
+- Typo in the task ID.
+
+### 3. Ordering vs. Architectural Constraints
+
+The dependency ordering should match the architecture's layered structure:
+
+**Layer ordering (typical):**
+1. Infrastructure setup (database, message queue, cache)
+2. Schema creation (tables, indexes, constraints)
+3. Core domain logic (entities, business rules, domain services)
+4. Repository/data access layer
+5. Service layer (application services, orchestration)
+6. API layer (endpoints, middleware, serialization)
+7. Frontend components (if applicable)
+8. Integration and E2E tests
+
+Verify that no task in a lower layer depends on a task in a higher layer (e.g., schema creation should not depend on an API endpoint).
+
+**Exceptions:** Some cross-cutting concerns (logging, auth, error handling) may be set up early and used by all layers. This is acceptable as long as the dependency is on the shared infrastructure, not on a specific feature in a higher layer.
+
+### 4. Parallel Task Independence
+
+Tasks that can run in parallel (no dependency relationship between them) should not share mutable state.
+
+**Process:**
+1. Identify all task pairs that have no dependency path between them (neither A→B nor B→A exists).
+2. For each parallel pair, verify:
+   - They do not modify the same files.
+   - They do not modify the same database tables in conflicting ways.
+   - They do not depend on the same external service configuration.
+   - They do not modify the same API endpoints.
+
+**What findings look like:**
+- "Tasks T-015 and T-018 can run in parallel but both modify `src/middleware/auth.ts`. If both agents work simultaneously, they will produce merge conflicts."
+- "Tasks T-020 and T-022 both add columns to the `users` table. Parallel execution will cause migration conflicts."
+
+**Resolution options:**
+- Add a dependency between the conflicting tasks (breaking the parallelism).
+- Split the shared resource into separate modules that can be independently modified.
+- Sequence the conflicting tasks and note that parallelism is not available.
+
+### 5. Critical Path Analysis
+
+The critical path is the longest chain of sequential dependencies. It determines the minimum time to complete all tasks, even with unlimited parallelism.
+
+**How to find it:**
+1. Perform a topological sort of the graph.
+2. For each node, compute the longest path from any root (node with no dependencies) to that node.
+3. The node with the longest path is the end of the critical path.
+4. Trace backward from that node along the longest incoming path to find the full critical path.
+
+**Why it matters:**
+- Tasks on the critical path cannot be parallelized — any delay directly extends the project.
+- Tasks NOT on the critical path have slack — they can be delayed without extending the project.
+- Optimization efforts should focus on the critical path: Can any critical-path task be split? Can any dependency be relaxed?
+
+### 6. Fan-in and Fan-out Analysis
+
+**High fan-in tasks** (many tasks depend on them):
+- These are blockers. If they are delayed, many downstream tasks are blocked.
+- They should be prioritized and possibly split into smaller deliverables.
+- Example: "Set up authentication middleware" — 15 API tasks depend on it.
+
+**High fan-out tasks** (depend on many other tasks):
+- These can only start late in the project.
+- They should be reviewed for whether all dependencies are truly necessary.
+- Example: "E2E test suite" depends on all API and frontend tasks.
+
+## Graph Visualization
+
+For communication, represent the dependency graph visually:
+
+```
+T-001 (Project setup)
+  ├─> T-010 (DB config)
+  │     └─> T-012 (Schema creation)
+  │           ├─> T-015 (User registration endpoint)
+  │           │     └─> T-020 (Sign-up form)
+  │           └─> T-016 (Product CRUD endpoints)
+  │                 └─> T-021 (Product listing page)
+  └─> T-011 (Auth middleware)
+        ├─> T-015 (User registration endpoint)
+        └─> T-016 (Product CRUD endpoints)
+```
+
+Or as a dependency table:
+
+```markdown
+| Task | Depends On | Depended On By | Parallelizable With |
+|------|-----------|----------------|---------------------|
+| T-001 | — | T-010, T-011 | — |
+| T-010 | T-001 | T-012 | T-011 |
+| T-011 | T-001 | T-015, T-016 | T-010, T-012 |
+| T-012 | T-010 | T-015, T-016 | T-011 |
+| T-015 | T-012, T-011 | T-020 | T-016 |
+| T-016 | T-012, T-011 | T-021 | T-015 |
+| T-020 | T-015 | — | T-016, T-021 |
+| T-021 | T-016 | — | T-015, T-020 |
+```
+
+## Output Format
+
+### Validation Summary
+
+```markdown
+## Dependency Graph Validation Results
+
+**Total tasks:** 45
+**Total dependencies:** 72
+**Graph is acyclic:** Yes / No
+**Cycles found:** [list if any]
+**Orphaned dependencies:** [list if any]
+**Critical path length:** 12 tasks
+**Critical path:** T-001 → T-010 → T-012 → T-015 → T-025 → ... → T-045
+**Maximum parallelism:** 6 tasks simultaneously (at step 4 of topological sort)
+**High fan-in tasks (>5 dependents):** T-001, T-011, T-012
+**Parallel conflicts found:** 3 (listed below)
+```
+
+### Finding Report
+
+```markdown
+## Finding: Parallel Conflict Between T-020 and T-022
+
+**Type:** Parallel task conflict
+**Severity:** Major
+**Description:** Both tasks modify `src/models/User.ts` — T-020 adds email verification fields, T-022 adds profile fields. Parallel execution will cause merge conflicts.
+**Recommendation:** Add dependency T-020 → T-022 (or vice versa) to serialize these tasks.
+```
+
+## When to Run Dependency Validation
+
+- After the implementation tasks are complete.
+- After any task is added, removed, or modified.
+- Before starting implementation — the dependency graph is the work scheduler.
+- When agents report being blocked — verify the blockage is real and not a missing dependency resolution.