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 delivery slice recorded in Delivery Planning: one or more Units with a Definition of Done, confidence hypothesis, and ownership. Runtime order follows unit-of-work-dependency.md and the recorded iteration choice, not the grouping in bolt-plan.md.

New solo workflows that include Unit decomposition and an in-scope source-producing per-unit stage default to Construction Checkpoints: enabled, Construction Iteration: unit-major, and Construction Execution: serial. They complete one Unit's applicable design and source-producing stages before the next. Preserve an explicit stage-major choice. Design-only and no-Unit workflows retain their existing stage flow; team-owned work uses unit_gate. Existing workflows without the checkpoint setting keep the legacy first-stage review; their late stage approvals, like those of work with checkpoints off, come as one question.

For eligible checkpoint work with skeleton-on, the first DAG Unit is the smallest working integrated slice. It completes its applicable stages, including Code Generation, before later Units even with stage-major selected. Its real end-to-end project check must pass, and a human must approve that verified skeleton. A legacy first Construction-stage approval is only a stage review; it does not establish that an integrated skeleton has been built.

All Unit/batch checkpoints reuse the intent's recorded, human-authorized Construction Verification Command. Delivery Planning proposes it from the project scan. Before presenting the command, write it to <record>/verification-command.txt with the harness's file-write tool (Write/edit), never a shell echo or heredoc. Repo-derived command text must never be interpolated into a shell line, where substitutions could execute before approval. Both log decision and log answer take --checkpoint verification-command --command-file verification-command.txt and find the session they run in. Copy the complete canonical command exactly from the command field in the decision tool's JSON output into the verification-command question's code span; never abbreviate it. Choose a delimiter that preserves any command backticks. The human can also open <record>/verification-command.txt. The canonical command is a nonblank single line of at most 1024 characters. Control characters and display-spoofing characters (Unicode format characters, including zero-width and bidi controls, line/paragraph separators, and no-break space U+00A0) are refused. The human's Approve / Request Changes reply binds the answer to the pending command, in the chat that asked or in a new one while it is the newest question asked. Only Approve authorizes the receipt; an unrelated reply, Request Changes, or a reply to another question does not. Never write --details "Approve" unless the human chose it; only then run state set-construction-verification-command --command-file verification-command.txt to write the matching Runtime State field. A human may defer when no runnable check exists yet; the first checkpoint then asks. The current approval receipt, not the field alone, authorizes execution. Changing it requires a new receipt and typed setter, never generic state set or an automatic choice.

Skeleton-off offers Continue automatically / Review each checkpoint at Construction entry; skeleton-on offers it after the real skeleton checkpoint. Only an emitted offer with no recorded choice prompts automatically. On-demand requests can change the choice during Construction. The answer controls ordinary completion questions; it never grants Plan Approval, verification command selection, an enabled summary confirmation, or successful verification of a failed check.

Eligible new source-producing solo Unit workflow:
  Default: unit-major + serial + verified Unit checkpoints
  Skeleton-on: first whole integrated Unit → real check → human approval
  When offered: Continue automatically / Review each checkpoint
  Remaining Units: applicable stages → checks → completion per recorded policy
  Completion-only stage directives: bookkeeping over recorded Unit approvals

Existing, design-only, no-Unit, or team-owned workflow:
  Preserve its recorded path and applicable stage or Unit-gate policy

After the per-unit work:
  Build and Test, then CI Pipeline if included, run once across the solution

Route checkpoints before bodies. A construction_checkpoint directive verifies and approves existing Unit work; it does not rerun Code Generation. When it carries rereview, run that review request at once, without asking, then verify and ask the one approval question. rereview names one of three cases: the Unit's code or documents changed since a finished review; the Unit's own review has not finished (unfinished: no verdict yet, or NOT-READY with a pass left); or it was never asked for in this run of the Unit's work (first). Only Guard Policy strict re-checks a change after a finished review: under relaxed and off that change is accepted with one line and the Unit's approval stands, while an unfinished or never-asked review is still named. The same holds with reviews off: the line comes from the next checkpoint's verify or the Construction stage's own check, or, for a change made between the approval question and the person's answer, from their approve. With command_authorized: false, ask the verification-command question before any verify, complete the human decision/answer/setter flow, then call next. Show "Verified with <full command> (exit 0)" in the approval question; verification_command is the full canonical recorded command, never an abbreviated label. A swarm_checkpoint handles a completed batch before later batch work. After verification, approval, or rejection, call next, never approve the whole stage for one Unit or batch. Only after verify reports verified: true and the current checkpoint has ready: true, open the human Unit/skeleton approval question with aidlc engine bolt checkpoint --action ask --unit "<unit>" --kind <unit|skeleton>; ask refuses an unready or unverified checkpoint. For a human batch question, only after status reports ready: true, run aidlc engine bolt swarm-checkpoint --action ask --batch <N> --units "<Units>". When the Unit ask returns earlier_reply, the person already answered in this chat while the Unit's review ran: do not show the question, and run approve or reject as their words chose; when their words answer nothing, show the question and wait. Otherwise present Approve / Request Changes and wait. The human's exact reply to this checkpoint question authorizes the matching action, in that chat or a new one: with no question of its own, a new chat's reply is kept for the checkpoint question another chat asked, while it is the newest question asked and still open. An unrelated reply, the agent's own words, or a reply to a different question does not. These commands find their own session; never pass --user-input the human did not choose. Consent is one-shot and bound to the current checkpoint fingerprint, verification proof ID, and authorized command digest (batch questions bind the fingerprint and per-Unit Command SHA-256 set). Re-running verify or swarm finalize withdraws every open checkpoint question and captured checkpoint response for this intent, in any session. Re-verify, confirm verified: true (batch: ready: true after source landing), and ask again; an older response cannot approve the new evidence. Automatic approval (human_required: false) needs no ask and no --user-input; human rejection always needs this verified question-and-answer flow.

A stage with construction_policy.completion_only: true and human_completion_required: false skips body, questions, reviewer, and learnings prompt, then reports awaiting-approval and approved without invented user input. Other completion gates follow human_completion_required; the legacy path without policy retains its existing human-gate procedure.

Version-4 checkpoint proofs retain the command's command_sha256 and full canonical command in command_label, plus exit status, full stdout/stderr byte counts and SHA-256 digests, and the last 2 KiB of each stream in stdout_tail and stderr_tail. These tails also appear in checkpoint CLI JSON. They are decoded as UTF-8 after dropping a leading partial multibyte sequence, with control characters other than newline and tab replaced by U+FFFD; full output is not retained. Project check commands must not print secrets: tails are not secret-redacted. Use the tails to explain a failure; any further diagnostics use the same authorized project check, not a newly chosen command. Legacy version-1 through version-3 proofs require re-verification with aidlc engine bolt checkpoint --action verify --unit "<unit>" --kind <unit|skeleton> before the Unit can be approved. GATE_APPROVED binds Verification Command SHA-256 to the proof's digest. The verifier records a tool-owned CHECKPOINT_VERIFICATION_RECORDED receipt alongside the proof file, and approval requires that receipt; a hand-written proof file cannot verify a Unit. On a checkout with no proof file at all (a fresh clone, another machine), that receipt stands in for the proof of a Unit already approved whose evidence is unchanged, so nothing runs again.

While plan_approval is on, Code Generation's Plan Approval remains a human stop before generation for every Unit. Grouped Plan Approval may present the exact live swarm Unit set together, but still records individual receipts. Pre-generation summary confirmation is required only when directive.ceremony.summary_confirmation === "on". See Construction commands for the checkpoint and approval commands.

Iteration and execution are separate. Unit-major is serial. To choose swarm explicitly for eligible checkpoint work, select stage-major and then Construction Execution: swarm; guided and automatic completion are both supported. An autonomy answer does not change execution or iteration order. Already approved inline Units are not rebuilt by a later swarm. Legacy workflows without the execution setting retain their existing autonomy-based swarm route.

Team-owned gates. With Unit Ownership: team, the per-stage rhythm gates each settled (stage, Unit) before that Unit advances; unit-end gates once after its final applicable per-unit stage. These remain separate from the solo checkpoint policy. The engine refreshes Unit Progress, and each gate report names its Unit so decisions and receipt floors remain scoped to that work.

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 a recorded stage-major path, 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 initial Plan Approval, while plan_approval is on, is a mandatory stop in every execution mode: the engine's question to the person cannot fold into a builder's return message. With plan_approval off (express and poc by default) the engine builds the plan as written after one line naming it and records PLAN_APPROVAL_SKIPPED. Under a relaxed or off Guard Policy the plan re-approval fence stands aside for undirected work and records GUARD_STOOD_ASIDE instead of refusing. After approval, content edits for the same target and attempt follow the effective-fence rule in Code Generation below; a lowered fence permits continuation without another Plan Approval stop.

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-wave.md § "Per-unit batch waves" for the full contract.

Parallel batches. Follow the exact dependency-ready Units emitted by the engine. Explicit stage-major/swarm execution can dispatch eligible Code Generation Units concurrently. In checkpoint-enabled workflows, each completed batch returns a swarm_checkpoint for guided or automatic completion before later work. Legacy swarm settlement retains its existing stage gate. BOLT_STARTED / BOLT_COMPLETED are per Unit/worktree on the swarm path; SWARM_COMPLETED closes the batch. Serial inline work uses its Unit lifecycle and checkpoint receipts.

Each new Bolt worktree is .aidlc/worktrees/bolt-<id8>_<slug> on branch bolt-<id8>_<slug>. The intent registry UUID suffix <id8> is shared with Unit claims, so parallel intents can reuse Unit slugs without sharing branches or retained/parked refs. Creation refuses an intent without a registry UUID; adopt or re-create the intent before Construction. See Bolt identity for naming and the provenance checks that let pre-upgrade legacy Bolts finish without creating new Bolts in the old shape. Cleanup refuses a branch checked out at another worktree path and preserves that owner's branch and refs.

A submodule the main checkout has initialized is set up in each new Bolt worktree too, at the commit the base records, cloned from the main checkout's own copy (no network or credentials). An uninitialized submodule stays an empty directory. Landing keeps the worktree, and names the submodule, when its copy there has uncommitted changes or a commit the main checkout's copy lacks. The committed-source check reads an initialized submodule the way the live source walk does, its commit plus its files, so a clean checkout with a submodule matches its own HEAD.

Before initial protected prepare, all Units undergo a read-only preflight of current approval or permitted postapproval continuation, plus committed, reproducible parent application source. This applies to legacy autonomy and new checkpoints. An uncommitted approved source snapshot is refused before any child is created: obtain explicit authorization to commit it, then retry. The inline skeleton's approved source must be committed before a later parallel batch; prepare never makes that commit automatically.

A rejected batch with resume_existing: true uses prepare --resume-existing. If rejection retired the prior approval, obtain fresh Plan Approval for the revision. Retries after that approval may use lowered-fence continuation for the same intent, target, and attempt: execution_allowed: true permits it even with ok: false, without reviving an older attempt's approval. Surviving worktrees retain source and archive prior metadata. If native source landing removed a child, the tool can recreate it from the already-landed parent source when the required landing evidence exists, retaining the rejection revision. It does not promise preservation of every post-merge child. See Swarm prepare.

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-checkpoint.md and stage-protocol-construction.md § "Halt-and-ask on failure" for the canonical procedures. The ordinary failure-prompt Abort pauses Construction with the worktree preserved. A stale-review recovery abort explicitly carrying --discard instead parks tracked and non-ignored untracked files and reviewed source refs, then removes the live checkout and branch. After obtaining the human's selection, execute the returned abort command unchanged. When present, the abort result's restore_operation has route worktree and exact args selecting the saved slug, stamp, and repository (--repo <name> or --repo .), followed by --intent <record-dir-name> --space <space> so recovery stays bound to that intent after the active intent changes. On a human restore request, invoke {{INVOKE}} engine worktree <args...> with each listed arg passed exactly as a separate argv argument, never joined into a shell command. Restoration recovers files in .aidlc/restored/bolt-<id8>_<slug>-<stamp> on restore/bolt-<id8>_<slug>-<stamp>, without overwriting a new live Bolt or reviving the old attempt's review authority. restore_hint is optional human display text only, not execution input. If safe rendering fails, the hint is omitted and restore_hint_error explains why while the operation remains. Offer restoration based on the operation, not the hint. If only review evidence remained, the evidence-only descriptor has no restoration operation, hint, hint error, or exclusions: no working files were saved, restore refuses, and doctor offers purge only. The recovery walkthrough explains what was set aside, the exclusions, exact restore selection, and informational doctor listings and purge options. Legacy restores retain the legacy name and require the selected intent's exact WORKTREE_DISCARDED Parked ref provenance.

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
• Acceptance criteria of those stories from <record>/inception/user-stories/stories.md (if produced)
• 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 and their acceptance criteria, 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 (at Standard and Comprehensive depth, swept per component against the product agent's corner-checklist.md; corners the requirements already settled carry forward)
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

Which files a Unit gets follows its kind: a ui Unit gets no entities.md or rules.md, only a ui Unit gets frontend-components.md, and a packaging Unit gets none of them.

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

Which files a Unit gets follows its kind: scalability, reliability and observability requirements are for service Units, and performance for service and ui Units.

Approval Gate

Strictly 2-option: Approve / Request Changes.

Notes -- NFR Granularity Expansion

This stage produces 6 Markdown artifacts plus traceability.json, expanded from the upstream reference which defines only 2 files for NFR Requirements. 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

Which files a Unit gets follows its kind, as in NFR Requirements; spec and packaging Units get no logical-components.md.

Approval Gate

Strictly 2-option: Approve / Request Changes.

Notes -- NFR Design Granularity

This stage produces 6 Markdown artifacts (5 NFR-specific designs plus logical-components.md) and traceability.json, expanded from the upstream reference which defines only 2 files for NFR Design. 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

Which files a Unit gets follows its kind: a spec Unit gets none of them, and a library Unit only cicd-pipeline.md and traceability.json.

Approval Gate

Strictly 2-option: Approve / Request Changes.

Notes -- Infrastructure Design Consolidation

This stage produces 3 Markdown artifacts plus traceability.json. 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. It runs for every Unit in every scope that includes it; infra runs no Code Generation and no Build and Test, as its compiled plan shows:

$ aidlc engine graph scope infra
workspace-scaffold
workspace-detection
state-init
practices-discovery
requirements-analysis
nfr-requirements
nfr-design
infrastructure-design
ci-pipeline
deployment-pipeline
environment-provisioning
deployment-execution
observability-setup

Code is written to the workspace root, never to <record>/.

Critical Rules

• Application code goes to workspace root, NEVER to <record>/. The developer's one change there is ticking each step's box in the plan as it finishes that step
• Brownfield: modify files in-place. NEVER create duplicates like ClassName_modified.java
• Add data-testid attributes to interactive UI elements for test automation
• Work in this order: plan (Step 2), Step 3 (the person's Plan Approval; with plan approval off, only its one-line notice), generation (Step 4), the Step 5 files, then the review (when the directive lists the reviewer protocol module) and completion (Step 6). The review checks the finished work: the reviewer never runs before the Step 5 files exist. When the directive already carries plan_approval.status: "approved" (a resumed or continued build), the plan and test instructions on disk are the approved ones: skip Steps 2 and 3 and build them as they are. Never rewrite an approved plan or its test instructions; change them only when the person asks
• For a Unit (directive.unit present), write the engine-required companion source-manifest.json in Step 5, before the review, listing every application-source path this unit created, modified, or deleted, including files written by shell commands, scaffolding, or generators. Zero-Unit work writes no source-manifest.json
• 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.

The plan opens with a short ## Summary (Builds, Touches, Tests lines) that the engine shows the person when it asks for approval.

1. Plan Approval -- the engine asks. When both files are written, the conductor runs next. A ready plan (non-empty plan and instructions, a valid and current Testing Contract, a readable workspace source) makes next return a plan-approval ask instead of the build: the question, each target's summary and plan path, and Approve Plan, Request Changes, and I'll edit the files. The engine writes code-generation-questions.md (the question, both tags, and a blank [Answer]:) and records the question in the protected runtime directory; the conductor shows it and ends the turn. The human-turn hook keeps the person's reply, from any chat on this piece of work, except one typed in a chat where the agent has asked a question of its own since the plan question was last shown in that chat, still open (the verification command, say), which answers that question; the conductor reads it and records their choice with answer --checkpoint plan-approval, which takes the fingerprint of the files as they are then and writes the answer, the receipt, and the PLAN_APPROVAL_RECORDED row with the person's words. The person may instead write their answer on the questions file's own [Answer]: line, as that file invites, and say so: the engine never overwrites an answer they wrote there while the same question stands, and on an exact "done" it reads that line and records an answer that is one of the choices, the same way it records an exact pick typed in chat, naming the file in one line for the conductor. When the person says it in their own words instead ("I put my answer in the file"), the conductor reads the line and records the choice they made. When the person's message in this chat that the question opened for already asked for a change ("go back to code generation: also accept -S", on finished work too) and no decision has used it, the conductor records it as that question's Request Changes, with their words (the message record is the proof, as --message reads it); an approval still needs a reply after the question shows, and the revised plan's question needs its own. The next next returns the run-stage with plan_approval.status: "approved" (build), revise (with the person's words), repair (a Testing Contract an edit broke), or plan (finish the files). In edit mode the person changes the files or writes their answer in the questions file and says done, and the conductor reads what they wrote and records their choice; the guard refuses the conductor's writes to those files meanwhile. A plan that is not ready is never asked about: next names the repair instead.

A postapproval plan, instruction, or Testing Contract edit for the same target and attempt asks again under Guard Policy strict. Under relaxed or off the build continues with the updated content. Preserve the original evidence; the edited content was not thereby approved. Testing Posture, scope, strategy, or project type changes follow that same rule. Other code moving after approval never asks again on any Guard Policy: the build continues with one change_notices line naming the files. A swarm under strict is the exception for the person's own files: prepare refuses until the plan is approved again, and the source landing refuses the same change until it is undone or Guard Policy is relaxed. A different intent or target, a new attempt, or missing actual initial approval still requires its own approval. After a rejected gate (the Code Generation completion gate, a Unit checkpoint, or a swarm batch checkpoint), while the plan is still the one approved before, next first returns revise with the person's words from that gate, so the question that follows shows the revised plan. Reopening the step through /aidlc --stage code-generation (Reopen: jump) starts a fresh attempt and asks about the plan as it stands, without requiring an arbitrary edit. Redo (Reopen: redo) starts the step again, including its plan, before asking for approval. Reopen: change and a gate's Request Changes still return revise with the person's feedback. Re-running next, or a reissued directive for the same target and attempt, never reopens it, and neither does whatever the engine said in between: a chat that compacted, a piece of work parked and resumed, or a guard-recovery question. next reads the approval for the plans its routed directive builds, not for the directive it replaces. A forwarding-loop continuation is never approval.

testing-posture verify reports execution_allowed: true with exit 0 when continuation is permitted, even if ok: false says the current content is not approved. Use that execution result; begin and brief honor it too. The friendly reason explains continuation; approval_reason keeps the stale binding detail and is not a new approval stop. When both content and source changed, read-only verify also previews the source change in change_notices. Generation start, including guard dispatch and swarm preparation, records and announces the accepted source change and re-baselines source provenance under the lowered fence. The original approval fingerprint, answer, and session remain unchanged. Existing delegated workers follow the live fence of their verified parent intent, including later lowering or raising. Missing artifacts or malformed or structurally incomplete Testing Contracts need repair before execution, not an automatic new approval ceremony. obligations.strategy must match test_strategy; both strategy_volume and scope_floor must contain nonblank obligations. A lowered fence also leaves execution provenance mandatory: before generation starts, an unbindable source or a failed runtime/audit publication blocks the operation. Repair that operational failure and retry with the same approval and fence setting. A valid human-issued break-glass receipt retains its existing source-binding exception. Lowering the per-work fence does not replace genuine initial approval, executable artifacts, or current target/attempt authority. Direct writes and developer dispatch validate every selected target before publishing any generation start. Repairing the plan records remains available while those execution requirements are unmet. A dispatch selecting multiple targets holds the generation authority locks across the whole start. If any target fails or source changes during publication, every receipt newly started by that dispatch is restored. Retry then checks the current source again; the original approvals and lowered fence settings remain unchanged.

PART 2 -- Generation (Steps 4-7)

1. Generate Code -- The directive's narration is the user's line for this build, said once before delegating. The engine counts the plan from the plan file, once for both lines: "Generating unit-2's code for 9 plan steps. This may take several minutes depending on project complexity. I'll show a summary when complete." at the start, and where an interrupted build picks up ("Picking up unit-2's code at step 5 of 9 (1-4 done)."; with the code written and no step marked, "Picking up unit-2's code: the plan marks none of its 9 steps done, checking what is built."). When the plan groups its tasks under "Step N" headings, both lines count the tasks and name the heading ("Generating unit-2's code for the 19 tasks in 4 plan steps ...", "Picking up unit-2's code at task 7 of 19, in Step 3 (tasks 1-6 done)."). The agent never counts the steps itself.

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

Context passed to subagent: - First, verbatim, the output of aidlc-testing-posture.ts brief --unit <unit> (or --stage-level). Its first line is the exact target marker, AIDLC-UNIT: <directive.unit> for unit work or AIDLC-STAGE: code-generation for a zero-Unit directive; its second line is AIDLC-TESTING-CONTRACT: <contract_sha256> from the current plan. With its fence on, the dispatch guard rejects missing, different, or stale hashes. Contextual dependencies do not receive additional target markers. - 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, domain design summary) -- the subagent can Read specific files if it needs full content - The current plan and unit-test-instructions.md, which that output already carries using the approval-content projection: the plan with a terminal ## Review appendix removed, task markers reset, and spacing normalized, plus the instructions byte for byte. The fingerprint excludes the appendix, so it is not work to execute; with its fence on, the dispatch guard refuses a handoff that quotes it. After permitted postapproval edits, use the current brief without calling the edits approved - When a build of the same plan was interrupted, that output also carries a ## Progress before the interruption section after its marker lines: the steps the plan file ticks (or, with none ticked, the steps whose named files changed since the build started), each file a done step names in a code span that is not in the project (a bare file name counts when a file of that name is anywhere in it), stated as a fact for the worker to judge, and the step to continue at. When neither the ticks nor the named files say what is done, it says the build wrote code and the plan marks none of its steps, and asks for each finished step to be ticked. It appears only when the build already started on the plan and instructions as they are now (the receipt for this target, stage attempt, and approved content is at generation, and the content on disk is the approved content or, when the fence was lowered for a plan edited after its approval, the edited content generation start kept on that receipt); a Redo, a rejected gate, a new approval, or a plan edited after the build started starts the steps fresh. When a build starts under a new approval, the engine sets the plan file's task markers back to [ ] (nothing else in the file changes, and the fingerprint is the same), so ticks from before never count. A swarm batch keeps its own continuation rule. The section is a hint, never evidence for a gate, review, or receipt, and ticks stay outside the fingerprint - Project workspace details (languages, frameworks, conventions from aidlc-state.md) - Instructions to execute each plan step sequentially and mark checkboxes as completed, starting where that progress section says when present - The Testing Contract in the current brief is authoritative. The subagent does not independently re-resolve memory; it executes that contract's 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

For a Unit (directive.unit present), also create <record>/construction/<directive.unit>/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 stage file gives this shape:

{
  "stage": "code-generation",
  "unit": "u1-auth",
  "version": 1,
  "writes": [
    { "path": "src/auth/login.ts" },
    { "path": "src/auth/generated/" },
    { "repo": "repo-a", "path": "src/api/routes.ts" }
  ]
}

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. Under Guard Policy strict, changed stage-source paths outside all fresh reviewed manifests block completion; under relaxed or off they are kept and the person is told once which files changed outside the Units.

A zero-Unit directive (directive.unit absent) writes no source-manifest.json and creates no Unit directory for one: the engine reads the manifest only for a Unit, and a zero-Unit review binds the whole workspace source instead. Its Step 5 files are <record>/construction/code-generation/code-summary.md and <record>/construction/code-generation/traceability.json.

1. Review, then Prepare Completion -- When the directive lists the reviewer protocol module, the architecture reviewer checks the finished work first (plan, test instructions, code summary, traceability, and, for a Unit, the source paths source-manifest.json claims), per section 12a of stage-protocol-reviewer.md. The review is recorded against code-generation-plan, the stage's review_artifact; that names where the review is filed, not a review of the plan before it is built. For a Unit the engine refuses the review request until the Step 5 files exist. Then 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 aidlc-developer-agent declares no tools: allowlist and denies Task.
• 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 (Unit work only): 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, under Guard Policy strict, 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 current ## Testing Contract in the stage-level or per-unit code-generation-plan.md, including postapproval edits permitted by a lowered plan re-approval fence and plans built with plan approval off; neither is described as human-approved. A CI obligation (the contract's "Run the selected tests in CI before merge." line, or a memory note's "CI execution before merge") is a target only when the plan runs CI Pipeline (ci-pipeline listed as EXECUTE and not [S] in aidlc-state.md); otherwise it is recorded N/A with that reason and is never a failure. While CI Pipeline is still ahead ([ ]), the target is CI Pipeline's to meet: recorded N/A with Owning Stage ci-pipeline and the reason that CI Pipeline, later in the plan, sets up CI to run these tests before merge, never a failure

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 current 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, or for a target the plan makes inapplicable here (the CI obligation of a plan that runs no CI Pipeline or has it still ahead)
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 the stage-level <record>/construction/code-generation/unit-test-instructions.md (when present, including Express) and 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, reopen code-generation via the engine for the Unit(s) the fix names (every Unit only when the cause spans them all), and replay forward through its settlement-aware route per the loop-back protocol module (aidlc-common/protocols/stage-protocol-loopback.md), "Build-and-Test failure loop-back". The failed run's gate is not presented; its enabled learnings ritual defers to the eventual passing run. When the learnings module is absent, no diary or ritual runs.
   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 loop-back protocol module (aidlc-common/protocols/stage-protocol-loopback.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 Construction checkpoints are off and 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. With checkpoints on (receipts are required from the first Unit), or 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 reopened Unit before the settle/approval gate because the reopen invalidates those Units' earlier reviews; Units the fix does not name keep their work and approvals. Under unit-major the swarm never fires; replay follows the serial per-Unit walk. A revised Code Generation plan still requires fresh human Plan Approval.

   The replay repairs the Code Generation plan under a NEW stage attempt, so the prior approval no longer applies. Record the delta in the Loop-Back Log and write the repaired plan; next then asks the person for Plan Approval again before any fix generation. The gated "Retry with fix" choice authorizes the jump; it is not approval of the revised plan.

   Swarm cheap path: A jump creates a new exact stage-attempt Run floor boundary token, so stale convergence rows cannot count. Park/discard stale worktrees/branches and run a fresh prepare; they cannot be adopted into the new attempt because finalize requires its current prepare stamp. The saved abort result's or doctor's restore_operation, when present, recovers parked files separately, not their current-attempt authority. Invoke its worktree engine route with each listed arg exactly as argv, never joined into a shell command. Hints and rendered commands are human display text only; rendering errors do not remove typed operations. Evidence-only attempts have no restore operation or files to restore. 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. Cross-Unit Final Coverage Gate -- Run aidlc engine sensor-traceability --stage build-and-test. It reports every FR and NFR in requirements.md (a requirement with sub-requirements through its FR{n}.{m} IDs) and every AC in stories.md (when User Stories ran), each built when a stage-level or per-unit Code Generation traceability.json covers it OK with an existing target file. A requirement with sub-requirements is built when each Unit has built its own (the NFR1.x its NFR Requirements wrote; a row for NFR1 alone does not cover them); otherwise by its own row or, when User Stories ran, through every acceptance criterion of the stories User Stories traced it to. One that nothing builds is settled when the latest stage that traced it (User Stories, NFR Requirements, then Code Generation) marked it N/A with its reason in every table there that lists it; an N/A with no reason is not settled. Write cross-unit-traceability.md from that output with the verdict, per-ID coverage and every uncovered ID; an uncovered ID is a finding shown at the approval gate.

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

12. 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 loop-back protocol module (aidlc-common/protocols/stage-protocol-loopback.md), "Build-and-Test failure loop-back". Re-entry is settlement-aware, asks for Plan Approval again on the repaired plan while plan_approval is on (the earlier approval belongs to the previous attempt), 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 plan (the scope, plus any skip or add the person makes) decides whether it is reached, and the stage still applies its own condition; Delivery Planning plans the Bolts, not the stages.
• 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 run in every scope that includes them (infra has neither); 3.7 is CONDITIONAL - Which conditional stages are reached comes from the plan (the scope, plus any skip or add the person makes), not from Delivery Planning; each still applies its own condition - New source-producing solo Unit workflows default to unit-major, serial execution and verified Unit checkpoints. Preserve explicit iteration choices and the existing legacy, design-only, no-Unit, and team-owned paths. - NFR artifacts use expanded granularity (6 Markdown files for requirements, 6 for design, each with a traceability.json) compared to the upstream reference - Infrastructure Design produces 3 Markdown artifacts (with dedicated monitoring and CI/CD files) plus traceability.json - 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 Markdown files plus traceability.json (expanded from 2 in reference) - NFR Design: 6 Markdown files including logical-components.md, plus traceability.json (expanded from 2 in reference) - Infrastructure Design: 3 Markdown files plus traceability.json: 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