feat: integrate Construction through pull requests (pr-integration stage + aidlc-pr tool)

AGENTS.md

@@ -23,7 +23,7 @@ The hand-authored source lives in `core/` (harness-neutral) + `harness/<name>/`
 (per-CLI surfaces); `bun scripts/package.ts` regenerates the `dist/<harness>/`
 trees. The core uses the same building blocks in every harness:
 
-- **Skills** (`skills/aidlc/`) — Orchestrator (`SKILL.md`), stage protocol, and 33 stage files across 5 phases (initialization, ideation, inception, construction, operation)
+- **Skills** (`skills/aidlc/`) — Orchestrator (`SKILL.md`), stage protocol, and 34 stage files across 5 phases (initialization, ideation, inception, construction, operation)
 - **Agents** (`agents/`) — 14 `aidlc-<role>-agent.md` files: 11 domain-expert personas (product, design, delivery, architect, aws-platform, compliance, devsecops, developer, quality, pipeline-deploy, operations), 2 review-only agents (product-lead, architecture-reviewer), and the adaptive-workflows composer (aidlc-composer-agent)
 - **Method/rules** (`memory/`) — Layered config in the space memory layer: `org.md` (framework defaults), `team.md` (affirmed practices), `project.md` (project overrides), and `phases/<phase>.md` for ideation/inception/construction/operation
 - **Sensors** (`sensors/`) — Deterministic verification manifests (advisory): `aidlc-claim-sources.md`, `aidlc-required-sections.md`, `aidlc-upstream-coverage.md`, `aidlc-traceability.md`, `aidlc-linter.md`, `aidlc-type-check.md`

README.md

@@ -93,12 +93,13 @@ Ad-hoc AI coding loses context as projects grow. AI-DLC keeps requirements,
 decisions, implementation, tests, and operational work connected through one
 audited lifecycle:
 
-- 5 phases and 33 stages from initialization through operation
+- 5 phases and 34 stages from initialization through operation
+- [PR-based integration](docs/guide/18-pr-based-integration.md): protected-branch detection, evidence-rich PRs, review rounds, and merge receipts
 - 14 agents: 11 domain experts, 2 reviewers, and an adaptive composer
 - 11 workflow profiles for features, bug fixes, infrastructure, security,
   proofs of concept, enterprise delivery, and other common work
 - Human approval gates and source-bound review evidence
-- 98-event audit trail plus persistent state, team knowledge, and learned rules
+- 102-event audit trail plus persistent state, team knowledge, and learned rules
 - The same deterministic engine across every supported harness
 
 Start with [Workflow Profiles](docs/guide/workflow-profiles.md) to compare
@@ -124,7 +125,7 @@ for the architecture and methodology.
 ## Repository Layout
 
 - `core/` - hand-authored, harness-neutral methodology and engine
-- `core/tools/` - 70 aidlc-*.ts engine and authoring tools
+- `core/tools/` - 71 aidlc-*.ts engine and authoring tools
 - `harness/<name>/` - thin, harness-specific manifests and integrations
 - `plugins/<name>/` - optional AIDLC plugins
 - `scripts/` - packaging, binary, installer, and release tooling

core/agents/aidlc-composer-agent.md

@@ -24,7 +24,7 @@ planning**, not keyword pattern-matching:
 > minimum viable workflow that solves this intent safely and economically in
 > this codebase?'"
 
-A **scope** is an EXECUTE/SKIP grid over the full stage set (33 stages today;
+A **scope** is an EXECUTE/SKIP grid over the full stage set (34 stages today;
 the compiled stage graph is authoritative). You compose the grid by
 principled estimation; the deterministic engine runs whatever grid is approved.
 Single-shot is valid only when it IS the minimum viable workflow (clear

core/aidlc-common/protocols/stage-protocol-construction.md

@@ -25,7 +25,7 @@ module applies only when `directive.reviewer` is present.
 > them.
 >
 > **Non-executable future-state:** any instruction in this subsection to treat
-> a Bolt as one pass through 3.1–3.5, to gate a Bolt's combined design
+> a Bolt as one pass through the applicable 3.1–3.6 per-Unit stages, to gate a Bolt's combined design
 > artifacts and generated code, to emit `BOLT_COMPLETED` on the default gated
 > walk, or to present subsequent Bolt-level / per-Bolt-batch gates. The
 > default walk is stage-major; runtime batches come from
@@ -136,7 +136,7 @@ options:
 
 ### Build-and-Test failure loop-back (3.6 → 3.5)
 
-When Build and Test (3.6) diagnoses a failure whose ROOT CAUSE lies in the
+When Build and Test (3.7) diagnoses a failure whose ROOT CAUSE lies in the
 generated code or an approach chosen at code-generation (not in this stage's
 own test/build scaffolding), the workflow may return to code-generation and
 repair it rather than writing the approach off or dead-ending at the gate.
@@ -337,7 +337,7 @@ When `directive.wave` is present, branch on it before the ordinary per-Unit or g
 
 After builds, `review_state: "outstanding"` runs the named iteration; `"retry-required"` repeats the unmatched request with `aidlc-log.ts review --retry-pending`; `"repair-required"` runs the lead-only repair and then the next reviewer iteration; and `"recovery-required"` runs the one stale-receipt recovery at the emitted `review_iteration`. `"escalation-required"` means that recovery was already spent: do not request another review or complete the Unit; halt and present the situation to the human, and only a human Request Changes decision may reset the stage attempt. `READY`, terminal `NOT-READY`, and `not-required` need no review work. Under Change Control `relaxed` a post-review change to a Unit's reviewed artifacts or claimed source does not produce `"recovery-required"`: the receipt stays valid, the engine records the change once (`CHANGE_ACCEPTED`) when the gate opens or the Unit completes, and the human hears one `change_notices` line. Reviewer dispatches remain serialized where the single reviewer-scope record is enforced; only an enforcement-free harness may run them as parallel foreground work. Once an entry is build-complete and review-settled, run `{{INVOKE}} engine state unit complete --wave --stage <slug> --unit <name>`. That command re-verifies the live wave entry, copies new Unit diary entries verbatim into the parent diary with deterministic deduplication, binds the receipt to the final artifact fingerprint, and only then emits `UNIT_COMPLETED`. Therefore a crash before diary fan-in or a later artifact change leaves `completion_required: true` and re-hands the entry; neither a dependent batch nor the stage gate can overtake build, review, memory, or completion evidence. Re-run `next` without report-approve after processing the emitted prefix. Unit-major iteration stays serial and never carries `directive.wave`.
 
-**Unit-major iteration (opt-in).** By default the walk above is stage-major: a design stage runs for every Unit, then the next design stage runs for every Unit, and code-generation runs 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 instead walks EVERY per-unit Construction stage unit-major: for each Unit in Bolt build order (outer), for each per-unit stage in graph order (inner — the four inline design stages, then code-generation), it emits the first unsettled (stage, Unit) pair with `gate: false`, so one Unit's four design documents are authored consecutively and the Unit is BUILT before the next Unit begins. The first working code therefore lands after ONE Unit's design, not after every Unit's; code-generation's own Step 3 Plan Approval still hard-stops per Unit before generation. The autonomous swarm never fires under unit-major: the walk owns code-generation through the normal non-swarm per-unit settlement path, so an `autonomous` grant changes no routing while the knob is set. The gates are UNCHANGED in count and machinery: the per-stage gates still fire, but late and in a cascade at the end of the block once the whole (stage x Unit) grid — code-generation included — is settled, one human approval per stage per turn. Because a stage's per-Unit work can run while `Current Stage` still points at an earlier stage, a directive's `directive.stage` may name a LATER Construction stage (including code-generation) than `Current Stage`, and a stage's `STAGE_STARTED` audit event may land after that stage's per-Unit artifacts were written; unit-major receipt floors therefore use the current workflow/jump/rejection boundary and survive that later `STAGE_STARTED`. The audit trail stays complete and stage-keyed. Always act on the directive's own `directive.stage` + `directive.unit`, never on `Current Stage`.
+**Unit-major iteration (opt-in).** By default the walk above is stage-major: a design stage runs for every Unit, then the next design stage runs for every Unit, followed by code-generation and any affirmed PR Integration pass. 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 instead walks EVERY per-unit Construction stage unit-major: for each Unit in Bolt build order (outer), for each per-unit stage in graph order (inner — the four inline design stages, code-generation, then PR Integration when promoted), it emits the first unsettled (stage, Unit) pair with `gate: false`, so one Unit's design, code, and publication are prepared before the next Unit begins. Code-generation's own Step 3 Plan Approval still hard-stops per Unit before generation. An integrating PR is terminal to the active-unit checkpoint but remains unsettled; the walk skips it and continues another eligible Unit. The autonomous swarm never fires under unit-major: the walk owns code-generation through the normal non-swarm per-unit settlement path, so an `autonomous` grant changes no routing while the knob is set. The gates are UNCHANGED in machinery: the per-stage gates fire late in a cascade once the whole (stage x Unit) grid is settled. Because a stage's per-Unit work can run while `Current Stage` still points at an earlier stage, a directive's `directive.stage` may name a later Construction stage than `Current Stage`, and a stage's `STAGE_STARTED` audit event may land after that stage's per-Unit artifacts were written; unit-major receipt floors therefore use the current workflow/jump/rejection boundary and survive that later `STAGE_STARTED`. The audit trail stays complete and stage-keyed. Always act on the directive's own `directive.stage` + `directive.unit`, never on `Current Stage`.
 
 **Team-owned Unit Progress and gates (opt-in).** `Unit Ownership: team` is valid
 only with unit-major. In that mode every `next` rewrites `## Unit Progress` from