Construction Phase -- Stage Reference (3.1-3.7)

Phase Overview

The Construction phase transforms design artifacts from Inception into working, tested software. It covers seven stages (3.1 through 3.7) that span functional design, non-functional requirements and design, infrastructure design, code generation, build/test verification, and CI pipeline configuration.

Construction is the fourth of five phases in the AI-DLC methodology. The compiled scope grid determines which stages execute and which are skipped. Runtime Unit batches come from unit-of-work-dependency.md (stage 2.7). Delivery Planning (Stage 2.9) produces the approved Bolt plan — planning content, not the walk source.

All stages follow stage-protocol.md for approval gates, question format, completion messages, and state tracking.

Path convention. Each workflow's artifacts live under its intent record dir — aidlc/spaces/<space>/intents/<YYMMDD>-<label>/ (where <space> is default unless a non-default space is in play, and <YYMMDD>-<label> is the intent directory: a compact UTC date prefix like 260624 plus a short kebab-case label so records sort chronologically). Below, <record>/ is shorthand for that dir; e.g. <record>/construction/{unit-name}/functional-design/ expands to aidlc/spaces/default/intents/<YYMMDD>-<label>/construction/{unit-name}/functional-design/. The dir name is a human-readable label; the canonical identity is the UUIDv7 stored in the intents.json registry row. (Projects created before the per-intent layout used a flat tree; the engine migrates them on first run.)

Construction walk

A Bolt is the planned Construction delivery slice from Delivery Planning (2.9): one or more Units with a Definition of Done, a confidence hypothesis, and ownership. Construction's default walk is stage-major: one stage runs for every Unit, then the next stage, with code-generation last. That walk does not yet treat the 2.9 plan as a runtime boundary. The opt-in Construction Iteration: unit-major walk (one Unit through every per-unit stage, then the next Unit) is closer to a per-Unit Bolt.

BOLT_STARTED / BOLT_COMPLETED are emitted on the swarm / worktree path; a default gated run does not record them. Runtime batches are recomputed from unit-of-work-dependency.md (stage 2.7). bolt-plan.md from stage 2.9 is the planning artifact (sequence, per-Bolt DoD, walking-skeleton marker). Walking-skeleton stance resolves org.md → team.md → project.md (most-specific non-empty statement wins); the bolt-plan marker is advisory against that resolved stance (PRACTICES_OVERRIDE / bolt-plan-marker-conflict). Under the default walk, the walking-skeleton gate is the first in-scope Construction EXECUTE stage. Stages 3.6 (Build and Test) and 3.7 (CI Pipeline) run once at the end across all Units.

Default walk (stage-major):
  First in-scope Construction EXECUTE stage for every Unit
  → Walking-skeleton gate
  → Ladder prompt (fires once): "Continue autonomously" or "Gate every Bolt"
  Then the next stage for every Unit, code-generation last

Opt-in (`Construction Iteration: unit-major`):
  Each Unit through every per-unit stage, then the next Unit

After all Units:
  3.6 Build and Test (runs once across the full codebase)
  3.7 CI Pipeline    (runs once, conditional)

Each design stage file (3.1–3.4) supports QUESTION-ONLY and ARTIFACT-ONLY execution modes — see the individual stage files for details. Code Generation's Step 3 Plan Approval always hard-stops before generation, including during Construction. Only its Step 7 per-Unit completion approval gate is suppressed by the engine during normal Construction; a single stage-level completion gate replaces it after the last Unit settles. Under an autonomous swarm that gate fires only after the final DAG batch has converged (intermediate batches merge without a gate). The per-Unit completion gate remains for direct-invocation use (e.g., /aidlc --stage code-generation).

Construction iteration order (opt-in). By default the engine iterates the per-unit construction stages stage-major: it runs 3.1 for every Unit, then 3.2 for every Unit, and so on, with 3.5 Code Generation last for every Unit. When the state file records Construction Iteration: unit-major under ## Runtime State (set at delivery-planning via aidlc-state.ts set-construction-iteration unit-major, or by a human), the engine walks unit-major instead: for each Unit in Bolt build order, it authors that Unit's four design documents (3.1 through 3.4) and then generates its code (3.5) before the next Unit begins — the first working code lands after one Unit's design, not after every Unit's. Code Generation's per-Unit Plan Approval (Step 3) still hard-stops before generation, and the autonomous Construction swarm never fires while the knob is set (the walk owns the build, serially in Bolt build order; parallel batches under autonomous swarm mode are stage-major territory). The per-stage approval gates are unchanged in count and machinery; under unit-major they fire late, in stage order, once the whole (stage by Unit) grid — Code Generation included — is covered, one human approval per stage. Only the exact value unit-major activates it; absent or stage-major is the default.

When delivery planning additionally records Unit Ownership: team, those late gates are replaced by Unit gates. The default per-stage rhythm gates each settled (stage, Unit) before that Unit advances; unit-end gates once after the final active, unskipped per-unit Construction stage for that Unit. The engine refreshes a derived ## Unit Progress table on every next, and reports include --unit so approvals/rejections and receipt floors affect only that Unit. solo or an absent ownership field keeps the legacy directives, state bytes, events, and late cascade unchanged.

Team-mode claims use claim/<intent-id8>/<unit> refs with compare-and-swap updates. A successful claim writes a gitignored checkout stamp; that checkout routes only the stamped Unit and carries the claim generation on lifecycle, review, gate, and fork evidence. Unscoped main emits a terminal fan-out notice while claims are live. aidlc-unit.ts release <unit> writes a tombstone instead of deleting the ref, invalidating stale attempts while preserving history. A participant clone opts into the guided claim picker once with aidlc-unit.ts participate; facilitator main deliberately omits that marker. Scoped routing and receipt writes are offline-first: the claim-time stamp is authoritative. Registry liveness is rechecked only at claim-sensitive boundaries such as fork/release; an unavailable remote warns and proceeds from the stamp, while an online stale or released attempt is refused.

Completed teams commit and run aidlc unit publish <unit>. Unscoped main then pins the exact claim-ref OID, validates its artifacts/receipts/gates/reviews and Plan Approval without materializing a worktree, records one human merge gate, and lands the candidate through aidlc unit land. Git content lands before the Unit row is folded; main-owned state/runtime markers are retained, the team's new audit shard transports its attempt-keyed receipts, and UNIT_MERGED marks the row. Source conflicts abort before state mutation. After the final merged row, Build and Test and CI Pipeline route once on main.

Per-unit batch waves (optional, stage-major only). On the default stage-major walk, the engine MAY emit directive.wave for one of the four inline design stages (3.1–3.4). The wave comes from one healed DAG snapshot; the conductor does not read runtime-graph.json or derive sibling paths. Code Generation (3.5, workspace_requires: true) is NEVER wave-eligible: concurrent builders would collide writing into the shared workspace (the swarm path's per-unit worktrees exist for exactly this isolation), and its Step 3 Plan Approval is a mandatory hard stop in every execution mode that cannot fold into a builder's return message.

Each entry carries kind-resolved consumes, explicit absent consumes, all produces, the applicable required subset, a Unit-local diary path, build state, paired-review state, and whether its wave completion receipt is still required. Builders receive the parent stage file, inline context roster, warnings, and exact accumulated steering content. A blocked builder withholds an applicable required path, not an optional or kind-exempt path. After build and review, unit complete --wave verifies the live entry, fans Unit diary entries into the parent diary idempotently, and emits UNIT_COMPLETED. The engine holds the current batch until every applicable Unit has all of that evidence, then permits a dependent batch or the single stage gate. Waves never apply under Construction Iteration: unit-major; harnesses without a parallel dispatch primitive process the entries serially. See stage-protocol-construction.md § "Per-unit batch waves" for the full contract.

Parallel batches. When two or more Units share dependency-satisfaction and don't depend on each other, the conductor dispatches their Code Generation stages concurrently by issuing N Task calls in a single assistant message. Under an autonomous swarm the engine converges every DAG batch and then presents one Code Generation stage gate — intermediate batches merge without a gate. Audit events (BOLT_STARTED, BOLT_COMPLETED) are per Unit/worktree on the swarm path; SWARM_COMPLETED closes the batch. A default gated run does not record BOLT_*.

Failure handling. A Code Generation failure always halts Construction regardless of autonomy mode. Options are retry (re-run just the failed Unit), skip (mark [S] and continue — dependents may also fail), or abort. Successful siblings in a parallel batch keep their [x] status and artifacts. See stage-protocol-construction.md § "Construction Bolt gates" for the canonical specification.

Stage Summary Table

Stage 3.1: Functional Design

Metadata

Purpose

Design the business logic, domain model, and rules for a single unit of work. The aidlc-architect-agent leads with the aidlc-developer-agent providing technical feasibility input.

Inputs

• Unit definition from <record>/inception/units-generation/unit-of-work.md
• Assigned stories from <record>/inception/units-generation/unit-of-work-story-map.md
• Requirements from <record>/inception/requirements-analysis/requirements.md
• Domain design artifacts from <record>/inception/domain-design/

Steps

1. Read Unit Context -- Read the unit definition, assigned stories, requirements, and domain design artifacts.

2. Create Functional Design Plan -- Analyze the unit's scope and create a questions file at <record>/construction/{unit-name}/functional-design/functional-design-questions.md with context-appropriate questions using [Answer]: tags. Focus areas:

3. Business logic workflows and algorithms
4. Domain models and entity relationships
5. Business rules, constraints, and validation logic
6. Data flow and transformations
7. Integration points with other units or external systems
8. Error handling and edge cases
9. Frontend components (component hierarchy, props/state, interaction flows, form validation)

10. Business scenarios (end-to-end user journeys, happy/unhappy paths, concurrency edge cases)

11. Collect and Analyze Answers -- Collect answers following stage-protocol.md question flow (offer interaction mode choice, collect answers, write back to file). Perform MANDATORY ambiguity analysis:

12. Identify vague answers ("mix of", "not sure", "depends", "probably")
13. Check for contradictions between answers
14. Flag missing details needed for artifact generation

15. If ANY ambiguity found: create follow-up questions and resolve before proceeding

16. Generate Artifacts -- Generate the following in <record>/construction/{unit-name}/functional-design/:

17. functional-spec.md: Detailed algorithms, workflows, data transformations, processing sequences, and decision trees for the unit's business logic
18. rules.md: Decision rules, validation logic, constraints, policies, conditional behavior, and business invariants
19. entities.md: Entities, relationships, data structures, attributes, lifecycle states, and entity interaction patterns

20. frontend-components.md (CONDITIONAL -- only if unit includes frontend/UI): Component hierarchy, props/state design, interaction flows, form validation rules, API integration points

21. Prepare Completion -- Verify the unit's Functional Design artifacts. Do not edit state; report the gate outcome through aidlc-orchestrate.ts.

22. Completion -- Present completion message and approval gate.

Outputs

Approval Gate

Strictly 2-option: Approve / Request Changes.

Notes

• The questions file is co-located with stage artifacts at <record>/construction/{unit-name}/functional-design/functional-design-questions.md.
• frontend-components.md is only produced when the unit includes frontend/UI work.
• All questions use the tri-mode interaction flow (Guide me / I'll edit the file / Chat).

Stage 3.2: NFR Requirements

Metadata

Purpose

Define non-functional requirements across performance, security, scalability, reliability, observability, and technology selection for a single unit. The aidlc-architect-agent leads, with the aidlc-devsecops-agent providing security input, the aidlc-compliance-agent providing regulatory input, and the aidlc-quality-agent providing testability and measurability input.

Inputs

• Functional design artifacts from <record>/construction/{unit-name}/functional-design/ (if they exist)
• Requirements from <record>/inception/requirements-analysis/requirements.md
• Reverse engineering artifacts from aidlc/spaces/<active-space>/codekb/<repo>/ (if they exist)

Steps

1. Read Prior Artifacts -- Read functional design artifacts (if they exist), requirements, and reverse engineering artifacts.

2. Assess NFR Categories -- Analyze the unit across NFR categories:

3. Performance: Response times, throughput, latency targets, resource utilization
4. Security: Authentication, authorization, data protection, compliance requirements
5. Scalability: Load handling, growth projections, scaling strategies
6. Reliability: Availability targets, fault tolerance, disaster recovery, data durability

7. Observability: Monitoring, logging, alerting, tracing requirements

8. Generate Questions -- Create a questions file at <record>/construction/{unit-name}/nfr-requirements/nfr-requirements-questions.md for unclear NFR areas using [Answer]: tags. Focus on quantifiable targets and specific constraints.

9. Collect and Analyze Answers -- Collect answers following stage-protocol.md question flow. Perform MANDATORY ambiguity analysis:

10. Identify vague answers ("fast enough", "highly available", "secure")
11. Check for contradictions between NFR targets
12. Flag missing quantitative targets

13. If ANY ambiguity found: create follow-up questions and resolve before proceeding

14. Generate Artifacts -- Generate the following in <record>/construction/{unit-name}/nfr-requirements/:

15. performance-requirements.md: Response time targets, throughput requirements, latency budgets, resource constraints, benchmarks
16. security-requirements.md: Authentication requirements, authorization model, data protection, compliance, threat considerations
17. scalability-requirements.md: Load projections, scaling triggers, capacity planning, data growth, concurrency targets
18. reliability-requirements.md: Availability targets (SLA/SLO), fault tolerance requirements, backup/recovery, graceful degradation
19. observability-requirements.md: Monitoring requirements, logging standards, distributed tracing needs, alerting thresholds, dashboard requirements, SLI/SLO definitions

20. tech-stack-decisions.md: Technology selections and rationale -- languages, frameworks, databases, infrastructure tools, and justification for each choice

21. Prepare Completion -- Verify the unit's NFR Requirements artifacts. Do not edit state; report the gate outcome through aidlc-orchestrate.ts.

22. Completion -- Present completion message and approval gate.

Outputs

Approval Gate

Strictly 2-option: Approve / Request Changes.

Notes -- NFR Granularity Expansion

This stage produces 6 artifact files, expanded from the upstream reference which defines only 2 files for NFR Requirements. This is a deliberate deviation documented in SKILL.md ("Deliberate Deviations from Reference"). The finer granularity improves traceability and allows per-concern review without overloading a single document. The six files separate performance, security, scalability, reliability, and observability into dedicated artifacts, and add a dedicated tech-stack-decisions.md for technology selection rationale.

Stage 3.3: NFR Design

Metadata

Purpose

Translate NFR requirements into concrete design patterns and architectural solutions. The aidlc-architect-agent leads with the aidlc-aws-platform-agent providing infrastructure and platform input.

Inputs

• NFR requirements from <record>/construction/{unit-name}/nfr-requirements/
• Functional design artifacts from <record>/construction/{unit-name}/functional-design/ (if they exist)
• Domain design from <record>/inception/domain-design/ for architectural context

Steps

1. Read Prior Artifacts -- Read NFR requirements, functional design artifacts (if they exist), and domain design for architectural context.

2. Generate Design Questions -- Create a questions file at <record>/construction/{unit-name}/nfr-design/nfr-design-questions.md with context-appropriate questions using [Answer]: tags. Focus areas:

3. Resilience patterns (circuit breakers, bulkheads, fallback strategies)
4. Scalability patterns (horizontal vs vertical, data partitioning, caching tiers)
5. Performance optimization (latency budgets, throughput targets, resource pooling)
6. Security approach (defense in depth, zero trust, encryption standards)
7. Observability approach (metrics and SLI/SLO targets, structured logging, tracing depth, alerting philosophy, dashboard needs)

8. Logical component boundaries (service isolation, failure domains, blast radius)

9. Collect and Analyze Answers -- Collect answers following stage-protocol.md question flow. Perform MANDATORY ambiguity analysis:

10. Identify vague answers ("mix of", "not sure", "depends", "probably")
11. Check for contradictions between answers
12. Flag missing details needed for artifact generation

13. If ANY ambiguity found: create follow-up questions and resolve before proceeding

14. Design NFR Solutions -- Design concrete solutions for each NFR category:

15. Performance: Caching strategies, query optimization, connection pooling, async processing, CDN usage, lazy loading, pagination
16. Security: Authentication flows, authorization model, encryption (at rest and in transit), input validation, CSRF/XSS protection, secrets management, audit logging
17. Scalability: Horizontal/vertical scaling approach, load balancing, data partitioning/sharding, queue-based decoupling, stateless design
18. Reliability: Circuit breakers, retry policies with backoff, health checks, graceful degradation, failover strategies, data replication

19. Observability: Metrics collection strategy, structured logging design, distributed tracing architecture, alerting rules, dashboard specifications, SLI/SLO tracking, correlation ID propagation

20. Generate Artifacts -- Generate the following in <record>/construction/{unit-name}/nfr-design/:

21. performance-design.md: Caching architecture, optimization strategies, resource pooling, async patterns, performance budgets
22. security-design.md: Authentication/authorization architecture, encryption design, input validation strategy, security headers, compliance controls
23. scalability-design.md: Scaling architecture, load distribution, data partitioning strategy, capacity thresholds, auto-scaling rules
24. reliability-design.md: Resilience patterns, circuit breaker configuration, retry policies, health check design, failover procedures, backup strategy
25. observability-design.md: Metrics collection architecture, structured logging design, distributed tracing strategy, alerting rules and escalation, dashboard specifications, SLI/SLO definitions, correlation ID propagation

26. logical-components.md: Logical infrastructure component inventory -- service boundaries, failure domains, blast radius mapping, component isolation strategy, shared resource identification. Bridges NFR design decisions with Infrastructure Design by providing a component-level view of where NFR patterns apply.

27. Prepare Completion -- Verify the unit's NFR Design artifacts. Do not edit state; report the gate outcome through aidlc-orchestrate.ts.

28. Completion -- Present completion message and approval gate.

Outputs

Approval Gate

Strictly 2-option: Approve / Request Changes.

Notes -- NFR Design Granularity

This stage produces 6 artifact files (5 NFR-specific designs plus logical-components.md), expanded from the upstream reference which defines only 2 files for NFR Design. This is a deliberate deviation documented in SKILL.md ("Deliberate Deviations from Reference"). The logical-components.md artifact serves as a bridge between NFR design and Infrastructure Design (Stage 3.4) by mapping where NFR patterns apply at the component level.

Stage 3.4: Infrastructure Design

Metadata

Purpose

Design the infrastructure, deployment architecture, monitoring, and CI/CD pipeline for a single unit. The aidlc-aws-platform-agent leads, with the aidlc-devsecops-agent ensuring infrastructure security and the aidlc-compliance-agent checking data residency and regulatory constraints.

Inputs

• NFR design from <record>/construction/{unit-name}/nfr-design/ (if exists)
• Functional design from <record>/construction/{unit-name}/functional-design/ (if exists)
• Domain design from <record>/inception/domain-design/
• NFR requirements from <record>/construction/{unit-name}/nfr-requirements/ (if exists)

Steps

1. Read Prior Artifacts -- Read all prior design artifacts for context: NFR design, functional design, domain design, NFR requirements.

2. Generate Infrastructure Questions -- Create a questions file at <record>/construction/{unit-name}/infrastructure-design/infrastructure-design-questions.md with context-appropriate questions using [Answer]: tags. Focus areas:

3. Deployment strategy (containerized, serverless, hybrid, multi-region)
4. Compute/storage/networking (sizing, topology, latency requirements)
5. Monitoring approach (metrics, logging, tracing, alerting thresholds)
6. CI/CD pipeline (build stages, deployment strategy, rollback procedures)
7. Secrets management (vault, environment variables, rotation policy)

8. Scaling policy (auto-scaling triggers, capacity limits, cost constraints)

9. Collect and Analyze Answers -- Collect answers following stage-protocol.md question flow. Perform MANDATORY ambiguity analysis:

10. Identify vague answers ("cloud-based", "auto-scale", "standard monitoring")
11. Check for contradictions between answers
12. Flag missing details needed for artifact generation

13. If ANY ambiguity found: create follow-up questions and resolve before proceeding

14. Design Infrastructure -- Design infrastructure across four areas:

15. Deployment Architecture: Compute model (containers, serverless, VMs), networking topology, storage strategy, environment layout (dev/staging/prod)
16. Infrastructure Services: Databases (type, sizing, replication), caches (strategy, eviction), message queues, search services, CDN, DNS, load balancers
17. Monitoring & Observability: Metrics collection, log aggregation, distributed tracing, alerting rules, dashboards, SLI/SLO tracking

18. CI/CD Pipeline: Build stages, test stages, deployment stages, environment promotion, rollback strategy, feature flags, artifact management

19. Generate Artifacts -- Generate the following in <record>/construction/{unit-name}/infrastructure-design/. Keep the content tabular (deployment, services, shared, and monitoring are tables):

20. infrastructure-specification.md: the core infra design — a Deployment table (compute, networking, storage, environments, IaC, sizing), an Infrastructure Services table (databases, caches, messaging, integrations, service discovery), and a CONDITIONAL Shared Infrastructure table (shared resources across units + ownership/access boundaries), all in one document
21. monitoring-design.md: the monitoring that implements NFR Design's observability-design strategy, tabular — metrics/KPIs, alerts, SLIs/SLOs, plus log-aggregation and tracing configuration and dashboard specifications

22. cicd-pipeline.md: pipeline stages, build configuration, test automation integration, deployment strategy (blue-green, canary, rolling), rollback procedures, environment promotion, secrets management in CI/CD

23. Prepare Completion -- Verify the unit's Infrastructure Design artifacts. Do not edit state; report the gate outcome through aidlc-orchestrate.ts.

24. Completion -- Present completion message and approval gate.

Outputs

Approval Gate

Strictly 2-option: Approve / Request Changes.

Notes -- Infrastructure Design Consolidation

This stage produces 3 artifact files. Deployment, infrastructure services, and shared resources were consolidated into a single tabular infrastructure-specification.md (closer to the upstream reference's single infra doc), while monitoring-design.md and cicd-pipeline.md stay dedicated artifacts because downstream Operation stages consume them independently (observability-setup reads monitoring; deployment-pipeline reads the CI/CD design). Shared infrastructure is a CONDITIONAL section of the specification, present only when multiple units share resources.

Stage 3.5: Code Generation

Metadata

Purpose

Generate all application code, tests, and configuration for a single unit of work. This is the only stage that always executes for every unit regardless of the execution plan. Code is written to the workspace root, never to <record>/.

Critical Rules

• Application code goes to workspace root, NEVER to <record>/
• Brownfield: modify files in-place. NEVER create duplicates like ClassName_modified.java
• Add data-testid attributes to interactive UI elements for test automation
• Before review, write the engine-required companion source-manifest.json listing every application-source path this unit created, modified, or deleted, including files written by shell commands, scaffolding, or generators
• Measurable quality targets from NFR Requirements, NFR Design, and the Testing Contract coverage floor are inputs, not suggestions. NEVER relax, lower, or disable a defined target, including threshold settings in test or build configuration, to make a step pass; surface the gap instead.

Inputs

• Functional design from <record>/construction/{unit-name}/functional-design/ (if exists)
• NFR requirements from <record>/construction/{unit-name}/nfr-requirements/ (if exists)
• NFR design from <record>/construction/{unit-name}/nfr-design/ (if exists)
• Infrastructure design from <record>/construction/{unit-name}/infrastructure-design/ (if exists)
• Domain design from <record>/inception/domain-design/
• Unit definition from <record>/inception/units-generation/unit-of-work.md
• Story map from <record>/inception/units-generation/unit-of-work-story-map.md

Steps

This stage has a two-part structure: planning followed by generation.

PART 1 -- Planning (Steps 1-3)

1. Read All Unit Artifacts -- Read all design artifacts for the current unit (functional design, NFR requirements, NFR design, infrastructure design, domain design, unit definition, story map).

2. Create Code Generation Plan -- Create a detailed plan at <record>/construction/{unit-name}/code-generation/code-generation-plan.md with checkboxes for each implementation step. Include story-to-code-step traceability -- map each plan step back to the user story it implements.

Run aidlc-testing-posture.ts render and paste its complete ## Testing Contract JSON block into the plan. The resolver reads org/team/project Testing Posture sections additively: a project coverage or integration note remains applicable but does not erase a team methodology; a contradictory narrower methodology is rejected.

The contract supplies a methodology-specific plan profile:

• TDD -- Red/Green/Refactor for every applicable testable layer: data, repository, business logic, API, and frontend.
• BDD -- executable behavior scenarios before an observable feature slice, followed by cross-layer implementation, green scenarios, and refactoring. It is not converted to layer-local TDD.
• ATDD -- executable acceptance tests before the complete cross-layer feature implementation, followed by acceptance-green and refactoring.
• Custom/mixed -- the exact affirmed ordering is preserved, including combinations such as scenario-first BDD with lower-level unit tests after implementation.
• Test-after -- implementation then tests for every applicable testable layer.

Greenfield plans bootstrap a minimal runnable test command before the first Red/scenario/acceptance step; brownfield plans verify the existing command first. The selected Test Strategy supplies volume/types and the scope adds its floor (coverage/CI, targeted regression, or no additional floor); neither obligation replaces the other. Under Minimal, a bug/security targeted regression may add one integration/E2E test when that is the narrowest level that reproduces the defect.

Test files are MANDATORY in the plan. The plan MUST include steps for: - Unit test files (one per component/module with key behavior coverage) - Test configuration (vitest.config, jest.config, or equivalent)

If the plan omits test file steps, they must be added before presenting to the user. Tests are not deferred to Build and Test -- that stage verifies and extends, not creates from scratch.

Number each plan step sequentially (Step 1, Step 2, etc.) for clear execution ordering and traceability.

Resolve one code-generation record directory from the directive: <record>/construction/<directive.unit>/code-generation/ when directive.unit is present, otherwise the zero-Unit stage directory <record>/construction/code-generation/. Also create unit-test-instructions.md there before Plan Approval. Match the active test strategy: - Minimal: Requirement-driven unit tests (1 test per requirement, happy-path floor per component), approximately 5-15 tests total - Standard: 5-8 tests per component, with key behavior coverage - Comprehensive: 10-15 tests per component, with thorough coverage

Include test framework setup and configuration, the exact runnable command available before the first test-first cycle, expected coverage targets, mocking/stubbing guidance, and test data management. Every run command MUST be scoped to this unit using exact test file paths or an exact unit filter. A bare project-wide command such as npm test is not acceptable because Build and Test executes every unit's commands.

Present the unit test instruction summary together with the plan summary.

1. Plan Approval -- Request approval for both code-generation-plan.md, its Testing Contract, and unit-test-instructions.md. On a revision, reset the prior [Answer]: to blank first. After both files are final, run aidlc-testing-posture.ts fingerprint --unit <unit> for a unit directive or aidlc-testing-posture.ts fingerprint for zero-Unit stage-level work. Then create or reset code-generation-questions.md in the resolved record directory with that [Approval Fingerprint], a Plan Approval question, and blank [Answer]:; render it as a structured question and stop the turn:
2. "Approve Plan" -- proceed to code generation
3. "Request Changes" -- revise the plan

Fill the tag only after the human responds. A request for changes is recorded, both files are revised as needed, the contract/fingerprint are regenerated, and the Plan Approval tag is reset before re-prompting. A post-approval plan/instruction change or Testing Posture/scope/strategy/type change invalidates the fingerprint and reopens approval. A forwarding-loop continuation is never approval.

PART 2 -- Generation (Steps 4-7)

1. Generate Code -- Before delegating, display to the user: "Generating code for [N] plan steps. This may take several minutes depending on project complexity. I'll show a summary when complete."

Delegate to Task tool with the aidlc-developer-agent subagent (subagent_type="aidlc-developer-agent").

Context passed to subagent: - As the first prompt line, the exact target marker: AIDLC-UNIT: <directive.unit> for unit work, or AIDLC-STAGE: code-generation for a zero-Unit directive. Contextual dependencies do not receive additional target markers. - As the second line, AIDLC-TESTING-CONTRACT: <contract_sha256> from the approved plan. The dispatch guard rejects missing, different, or stale hashes. - The lead agent's persona from agents/aidlc-developer-agent.md and knowledge from .claude/knowledge/aidlc-developer-agent/ (included in the prompt since subagents cannot access conversation history) - Design artifacts for the CURRENT UNIT ONLY (not all units) - A 1-2 line summary of each inception-phase artifact with its file path (requirements summary, stories summary, app design summary) -- the subagent can Read specific files if it needs full content - The approved code-generation-plan.md (full content) - The approved unit-test-instructions.md (full content) - Project workspace details (languages, frameworks, conventions from aidlc-state.md) - Instructions to execute each plan step sequentially and mark checkboxes as completed - The approved Testing Contract is authoritative. The subagent does not independently re-resolve memory; it executes the approved TDD, BDD, ATDD, test-after, or custom/mixed profile exactly. - Measurable quality targets from NFR Requirements, NFR Design, and the Testing Contract coverage floor are inputs, not suggestions. The subagent must NEVER relax, lower, or disable a defined target, including threshold settings in test or build configuration, to make a step pass; it must surface the gap instead.

Context budget: Pass only the current unit's design artifacts, not all units. Summarize inception artifacts with file paths rather than embedding full content. The subagent generates all code, test files, and configuration artifacts in the workspace.

1. Generate Code Summary and Source Manifest -- After the subagent completes, create <record>/construction/{unit-name}/code-generation/code-summary.md documenting:
2. Files created/modified
3. Key implementation decisions
4. Test coverage summary
5. Any deviations from the plan

Also create <record>/construction/{unit-name}/code-generation/source-manifest.json. This is a strict version-1 JSON companion file, not a declared produces[] artifact. It records stage: "code-generation", the exact unit name, and a writes array containing every application-source path the unit created, modified, or deleted, including shell-, scaffolding-, and generator-written files. Paths are POSIX-relative and use no globs or ..; a trailing / claims a generated directory tree. In a main-workspace multi-repo run every entry names its recorded repo; inside the worktree hosting the Bolt, paths are relative to that selected repo and omit repo.

The engine validates this schema and refuses to record a terminal per-unit review without it. Its bytes and claims join the Unit Source Fingerprint; changed stage-source paths outside all fresh reviewed manifests block completion.

1. Prepare Completion -- Verify the unit's code and summary artifacts. Do not edit state; report the gate outcome through aidlc-orchestrate.ts.

2. Completion -- Present completion message and approval gate.

Outputs

Approval Gate

Strictly 2-option: Approve / Request Changes.

Notes

• Two-part structure: The planning phase (Steps 1-3) runs inline with user interaction and plan approval. The generation phase (Steps 4-7) delegates to the aidlc-developer-agent subagent via the Task tool. This is different from most Construction stages which run entirely inline.
• Developer-agent subagent: Code generation uses subagent_type="aidlc-developer-agent" (delegated via Task tool), not inline execution. This is the only Construction stage that uses a subagent. The subagent inherits the full session toolset (the aidlc-developer-agent declares no tools: allowlist), so it reaches Read, Edit, Write, Glob, Grep, Bash, AskUserQuestion, and the inherited MCP tools.
• Context budget: Only the current unit's design artifacts are passed to the subagent. Inception-phase artifacts are summarized in 1-2 lines with file paths so the subagent can selectively Read what it needs.
• Mandatory test file inclusion: Test files MUST be part of the code generation plan. Stage 3.6 (Build and Test) verifies and extends tests but does not create them from scratch.
• Source-manifest enforcement: source-manifest.json is engine-validated, not a Markdown required-sections target. Its strict schema and Unit Source Fingerprint bind every exact/directory source claim; the engine refuses the terminal review when it is absent or invalid and refuses stage completion for changed source outside the fresh reviewed claims union.
• Unit-scoped execution: Each per-unit test instruction file uses exact test paths or an exact unit filter so the cross-unit execution stage does not rerun the project-wide suite for every unit.
• Brownfield awareness: In brownfield projects, the subagent modifies existing files in-place rather than creating duplicates.

Stage 3.6: Build and Test

Metadata

Purpose

Generate cross-unit test instructions, consume the per-unit unit test instructions, then actually execute the build and tests via Bash. This stage operates across ALL units -- it is NOT per-unit. The aidlc-quality-agent leads with the aidlc-devsecops-agent providing security testing expertise.

Inputs

• Code generation outputs across all units from <record>/construction/*/code-generation/code-summary.md
• Per-unit test instructions from <record>/construction/*/code-generation/unit-test-instructions.md
• Every applicable artifact under each unit's nfr-requirements/ and nfr-design/ directory
• Every approved ## Testing Contract in the stage-level or per-unit code-generation-plan.md

Steps

1. Analyze Testing Requirements -- Read code generation summaries and per-unit test instructions across all units. Build a source-complete inventory of every measurable target from NFR Requirements, NFR Design, and every approved Testing Contract. For each target, record a stable ID, source path/section, expected value, the check that produces its actual value, and any later validation stage that owns it. Catalog all required test types.

2. Generate Build Instructions -- Create <record>/construction/build-and-test/build-instructions.md:

3. Dependency installation steps
4. Environment setup (env vars, config files, local services)
5. Build commands (compile, bundle, transpile)
6. Build verification steps
7. Troubleshooting common build issues

3-7. Generate Additional Test Instructions -- Consult the active test strategy and generate the matching cross-unit instruction files: - Minimal: Generate no additional files. Unit tests are covered per-unit by Code Generation. - Standard: Generate integration-test-instructions.md for key boundaries and cross-unit interactions. - Comprehensive: Generate integration instructions, plus performance-test-instructions.md when performance NFRs exist and security-test-instructions.md when security NFRs exist. - At any strategy, add specifically named contract, E2E, accessibility, or other instruction files when the project context requires them.

All files go in <record>/construction/build-and-test/. Each file includes framework setup, run commands and filters, coverage targets, and test data or environment setup.

1. Generate Build and Test Summary -- Create <record>/construction/build-and-test/build-and-test-summary.md:
2. Overall build status and prerequisites
3. Test type inventory (which test types were generated)
4. Coverage expectations per unit
5. A Target Verification Matrix with Target ID, Source, Expected, Actual, Evidence, Owning Stage, and Verdict
6. Applicable targets begin Pending; N/A is valid only when the source-complete inventory found no applicable measurable target
7. Readiness assessment (build-ready, test-ready, deployment-ready)

8. Known limitations or outstanding items

9. Execute Build and Tests -- Attempt to execute the build and test commands documented in the instruction files via Bash:

   a. Build: Run the build commands from build-instructions.md via Bash. Capture output. b. Unit tests: Collect commands from every per-unit code-generation/unit-test-instructions.md, deduplicate identical commands, and run each distinct command once. Commands should be unit-scoped; if a file contains a project-wide command, run it once, never once per unit. Report per-unit pass/fail without double counting. c. Integration tests (if applicable): Run integration test commands. Capture results. d. Other applicable checks: Run every applicable command from performance, security, contract, E2E, accessibility, and other generated instruction files. Defer only a check that requires a deployed or production-like environment and has a named owning validation stage in the current execution plan. Record that stage and its expected evidence path; the target remains Unverified and cannot make this stage successful. Without a scheduled owning stage, it is simply Unverified. e. Finalize and report results: Create or update <record>/construction/build-and-test/test-results.md and build-and-test-summary.md on every exit path with: - Build status (success/failure + output) - Test results (total, passed, failed, skipped) - Failure details (test name, assertion, stack trace) - Coverage report (if test framework supports it) - The finalized Target Verification Matrix. Every applicable target has an actual value, evidence, owning stage, and final Met, Not Met, or Unverified verdict. No Pending verdict remains after Step 9. - ## Loop-Back Log (only when the failure ladder's rung 3 or 4 fires a loop-back): one ### Loop-back N -- <ISO timestamp> entry per attempt (Diagnosis / Root-cause stage / Planned fix / Estimated impact). Append-only; survives re-runs (Modify, never Redo, on loop-back re-entry).

   Failure-escalation ladder: The stage has failed when a build or test command fails or an applicable target is Not Met or Unverified. Finalize the matrix and summary before entering the same ladder for every failure kind. Lowering, relaxing, or disabling a target is never an acceptable fix.

   1. In-stage fix (max 2 attempts) -- for root causes inside this stage's own remit (test config, build scripts, environment setup, or an executable target check): read the evidence, identify the failing configuration or scaffolding, apply the fix, re-run the failing step, and refresh the target matrix.
   2. Classify and estimate impact -- when in-stage attempts are exhausted or the diagnosis points upstream: decide whether the root cause lies in generated source or test code -- regardless of defect size -- or a code-generation approach choice (library/version, container image, instance type, algorithm, flag); find a fix in a swappable dimension and ESTIMATE ITS IMPACT (effort, financial cost, risk). Never declare a feasible path out of scope on an impact-unestimated effort assumption.
   3. Autonomous bounded loop-back -- if Construction Autonomy Mode: autonomous, an impact-estimated fix exists, and fewer than 3 entries exist under ## Loop-Back Log: record the diagnosis + impact-estimated fix, jump back to code-generation via the engine, and replay forward through its settlement-aware route per the construction protocol module (aidlc-common/protocols/stage-protocol-construction.md), "Build-and-Test failure loop-back". The failed run's gate is not presented; its learnings ritual defers to the eventual passing run.
   4. Halt-and-ask -- gated/unset mode, bound exhausted, or no identifiable fix: log the failure and present the halt-and-ask question from the construction protocol module (aidlc-common/protocols/stage-protocol-construction.md) -- the impact-estimated 3-option variant (Retry with fix [estimated impact] / Accept failure / Abort) when a candidate fix exists, or the no-fix 2-option variant (Accept failure / Abort) when rung 2 found none.

   Loop-back replay routing: If Code Generation never used unit lifecycle receipts, preserved artifacts can take the all-covered gate: true fast path; apply the planned fix and deterministic Modify/Keep decisions before that gate. Once any lifecycle row exists, receipt mode is sticky and the jump re-emits per-Unit work: re-mint unit start / unit complete, apply Modify to targeted Units and Keep to the rest, and run the declared reviewer per Unit. Both paths MUST record a fresh current-attempt REVIEW_COMPLETED for every applicable Unit before the settle/approval gate because STAGE_JUMPED invalidates all earlier reviews. Under unit-major the autonomous swarm never fires; the replay follows the serial per-Unit walk and still needs no extra human turn.

   The replay repairs the already-approved Code Generation plan. Preserve its Plan Approval [Answer]:, record the delta in the Loop-Back Log, and treat gated "Retry with fix" as the human's re-approval of the revised approach.

   Swarm cheap path: A jump creates a new exact stage-attempt Run floor boundary token, so stale convergence rows cannot count. Discard stale worktrees/branches and run a fresh prepare; they cannot be adopted into the new attempt because finalize requires its current prepare stamp. Run check first. A green Unit can skip a builder turn, but it still needs a terminal current-attempt reviewer receipt in the fresh worktree before it enters finalize --claimed; finalize verifies that receipt's current artifact fingerprint as well as the attempt stamp.

   Single-stage runs (--single) stop at rung 2 -- there is no main-workflow position to move; the impact-estimated options are logged and presented in that run's isolated-run summary.

   On success: A successful readiness result requires every command to pass and every applicable target to be Met, or the single explanatory N/A row when no target applies.

10. Prepare Completion -- Verify the build/test evidence. Do not edit stage or phase state; the reported gate outcome owns the transition.

11. Completion -- Present completion message and approval gate.

Outputs

Approval Gate

Strictly 2-option: Approve / Request Changes.

Notes

• Actual Bash execution: This stage does not just document test instructions -- it actually runs the build and test commands via Bash and captures real results. This is one of the few stages that executes real commands against the codebase.
• Quality target evidence: The source-complete matrix is finalized on every exit path. Deployed-environment checks may name a later owning stage, but remain Unverified; Not Met and Unverified both enter the failure ladder.
• Failure-escalation ladder: In-stage fixes are bounded at 2 attempts; when the root cause lies upstream in generated code or a code-generation approach choice, the stage classifies and estimates the impact of a fix, then either runs the bounded autonomous loop-back to code-generation (max 3, counted by the append-only ## Loop-Back Log in test-results.md) or presents the impact-estimated halt-and-ask question. See the construction protocol module (aidlc-common/protocols/stage-protocol-construction.md), "Build-and-Test failure loop-back". Re-entry is settlement-aware, preserves the approved plan, and cannot reach its gate until every applicable Code Generation Unit has a fresh current-attempt review.
• Conditional test types: Performance tests, security tests, contract tests, E2E tests, and accessibility tests are only generated when relevant conditions are met (NFR requirements exist, microservice architecture, UI-driven application, user-facing interfaces).
• Cross-unit scope: Unlike stages 3.1-3.5 which are per-unit, Build and Test runs once across all code produced by all units. It validates the integrated codebase, not individual units.
• Phase completion: This stage (along with 3.7 if applicable) marks the end of the Construction phase. The final approved report makes the engine mark Construction complete and route to Operation atomically.

Stage 3.7: CI Pipeline

Metadata

Purpose

Configure the CI (Continuous Integration) pipeline with quality gates, artifact management, and build/test automation. The aidlc-pipeline-deploy-agent leads with no support agents.

Inputs

• Build/test results from <record>/construction/build-and-test/
• Infrastructure design from <record>/construction/infrastructure-design/ (if exists)
• Workspace profile for existing CI configuration

Steps

1. Load Prior Context -- Read build/test results, infrastructure design (if exists), and workspace profile for existing CI configuration.

2. Generate Clarifying Questions -- Create <record>/construction/ci-pipeline/ci-pipeline-questions.md with questions:

3. What CI tool is in use (CodePipeline, CodeBuild, GitHub Actions, Jenkins)?
4. What is the branch strategy?
5. What quality gates are required before merge?
6. What artifact repositories are used (ECR, CodeArtifact, S3)?

Follow stage-protocol.md question flow.

1. Collect and Analyze Answers -- Validate CI choices against existing infrastructure and team capabilities.

2. Generate Artifacts -- Create CI pipeline configuration (buildspec.yml, workflow YAML, or equivalent), quality gate definitions, and artifact repository configuration.

3. Phase Boundary Verification -- Run Construction-to-Operation verification check:

4. Architecture-to-code-to-tests alignment
5. All code traces to design
6. Test coverage against acceptance criteria

7. Write results to <record>/verification/phase-check-construction.md

8. Prepare Completion -- Verify the CI and boundary artifacts. Do not edit stage or phase state; the reported gate outcome owns the transition.

9. Completion -- Present completion message and approval gate.

Outputs

Approval Gate

Strictly 2-option: Approve / Request Changes.

Notes

• Phase boundary verification: This is the last stage of the Construction phase. It performs the Construction-to-Operation phase boundary verification check (per stage-protocol-governance.md section 13), validating that architecture traces to code and code traces to tests. Results are written to <record>/verification/phase-check-construction.md.
• Conditional execution: This stage is skipped if the project already has an adequate CI pipeline. The execution plan from Delivery Planning determines whether it runs.
• Post-unit execution: Like Stage 3.6, this stage runs once after all per-unit work is complete, not per-unit.

Phase Summary

The Construction phase transforms Inception designs into working software through a phased construction flow:

Per-unit stages (3.1-3.5): - 3.1 Functional Design -- Business logic, domain models, rules (architect-led) - 3.2 NFR Requirements -- Performance, security, scalability, reliability, observability, tech stack (architect-led) - 3.3 NFR Design -- Concrete patterns for NFR categories (architect-led) - 3.4 Infrastructure Design -- Deployment, services, monitoring, CI/CD (aws-platform-led) - 3.5 Code Generation -- Two-part planning + generation via subagent (developer-led)

Post-unit stages (3.6-3.7): - 3.6 Build and Test -- Instruction generation + actual Bash execution with failure diagnosis (quality-led) - 3.7 CI Pipeline -- CI configuration + phase boundary verification (pipeline-deploy-led)

Key characteristics: - Stages 3.1-3.4 are CONDITIONAL; 3.5-3.6 ALWAYS execute; 3.7 is CONDITIONAL - All conditional stages follow the execution plan from Delivery Planning - Default walk is stage-major (a stage for every Unit, then the next stage); the opt-in unit-major walk runs one Unit through every per-unit stage before the next Unit begins - NFR artifacts use expanded granularity (6 files for requirements, 6 for design) compared to the upstream reference - Infrastructure Design is expanded to 5 artifacts with dedicated monitoring and CI/CD files - Code generation uses the aidlc-developer-agent subagent with context budget controls - Build and Test performs actual command execution and automated failure diagnosis - CI Pipeline includes phase boundary verification before transitioning to Operation

Deliberate deviations from upstream reference: - NFR Requirements: 6 files (expanded from 2 in reference) - NFR Design: 6 files including logical-components.md (expanded from 2 in reference) - Infrastructure Design: 3 files — a consolidated infrastructure-specification.md (deployment + services + shared) plus dedicated monitoring-design.md and cicd-pipeline.md - Plan/question file co-location with stage artifacts