# ADR-0005: Continuous rescaffolding is a V1 property, not a V2 feature

- **Date:** 2026-05-01
- **Status:** accepted
- **Reversibility:** medium-low (reverting would require removing the rescaffold protocol from BOOTSTRAP-BRIEF, deleting the architect-rescaffold skill, and downgrading the deploy skill to one-shot; structurally costly)
- **Deciders:** practitioner@example.com (operator)
- **Scope:** kit (V1.1 architectural shift)

## Context

ADR-0001 framed V1 as "polymorphic single kit, not recursive kit-of-kits" and deferred the recursive engine to V2. The V2 vision (Recursive Skill Optimization & Scaffolding Engine, tracked in `AI-Architect/BACKLOG.md`) was framed as a meta-tool that takes a source methodology + an environment profile + scaffolding rules and produces an adapted kit per target.

Operator feedback after V1 ship (2026-05-01): the V1 framing put too much in V2's column. The "learning is the process" insight is a property the kit needs in V1, not a feature deferred until V2. Specifically:

> "I've seen too many LLM processes do something once and not revisit. Or prepare for something once, and then not recalibrate. In this model, the learning is the process. it's not exhaustive because it is the plan. As the kit scaffolds, as more context is gathered, it rescaffolds. The first scaffold is thorough and intense. the later ones adapt."

This reframes V1: the kit is not "deployed once and operated"; it is "deployed initially and continuously rescaffolds." The deploy skill becomes a multi-phase orchestrator (bootstrap, discovery, scaffold, operate, rescaffold) rather than a one-shot landing. The validate skill produces rescaffold triggers, not just reports.

V2 stays as a separate concept (kit-of-kits; engine that generalizes across target environments) but no longer carries the burden of "this is where adaptation lives." Adaptation is now a V1 property; V2 is a future generalization layer above it.

## Decision

V1.1 makes continuous rescaffolding a first-class V1 property. Specifically:

1. The deploy skill is a multi-phase orchestrator: **bootstrap** (load brief, orient), **discovery** (extensive recursive questioning), **scaffold** (render templates against gathered context), **operate** (run the deployed instance), **rescaffold** (revisit affected scope on trigger).
2. A new skill `architect-rescaffold` drives the rescaffold cycle.
3. A new skill `architect-discovery` drives the recursive question-asking phase (first scaffold and rescaffold).
4. BOOTSTRAP-BRIEF Section XVII codifies the rescaffold protocol (triggers, scope, logging, operate-vs-rescaffold mode).
5. The validate skill's output produces explicit rescaffold triggers in addition to its existing audit findings.
6. Each rescaffold writes a session log; prior MATURITY-SCORECARD versions archive under `MATURITY-SCORECARD-history/YYYY-MM-DD.md`.
7. The third cardinal insight ("learning is the process") is added to BOOTSTRAP-BRIEF Section I.

V2 (the recursive engine; kit-of-kits) is unaffected; it remains future work in `AI-Architect/BACKLOG.md`.

## Options considered

### Option A: Continuous rescaffolding in V1.1 [CHOSEN]

- **Summary:** Add bootstrap/discovery/operate/rescaffold modes to V1; new skills (discovery, rescaffold); BOOTSTRAP-BRIEF revisions; multi-phase deploy orchestrator.
- **Pros:** Matches the third cardinal insight; operationalizes "learning is the process"; closes the named V1 failure mode (deploy-once-operate-static); does not require V2 to ship.
- **Cons:** Substantial revision to V1 just after first ship; existing deployments (none yet) would need migration; the discovery skill must be capable enough to drive recursive questioning effectively.

### Option B: Defer to V2 (status quo)

- **Summary:** V1 stays one-shot landing; V2 builds the recursive engine; rescaffolding is a V2 feature.
- **Pros:** Zero disruption to V1 ship; clean V1/V2 separation.
- **Cons:** V1 ages out within months because it does not rescaffold; operator's named concern (LLM processes that prep once and never recalibrate) is the V1 failure mode; V2 is at minimum 3 deployments away from being buildable, so "wait for V2" means months of static V1 deployments first.

### Option C: V1.5 (intermediate version)

- **Summary:** V1.0 ships static; V1.5 adds rescaffolding; V2 adds kit-of-kits.
- **Pros:** Smaller delta per version; V1.0 deployments can ship before rescaffolding is built.
- **Cons:** V1.0 deployments produce evidence under static behavior, which is not the evidence V2 needs (V2 needs evidence from rescaffolding deployments to learn what generalizes); the V1.5 transition then requires migrating V1.0 deployments anyway.

## Rationale

Option B is the V1 status quo and the operator has named it inadequate. Option C produces evidence of the wrong shape; V1.0 static deployments cannot inform V2's recursion rules because V1.0 has no recursion to observe. Option A puts the right architecture in V1.1; deployments produce the right evidence; V2 generalizes from real recursive deployments rather than from speculation about how recursion would have worked.

The tradeoff explicitly accepted: V1.1 is a substantial revision soon after V1.0 ship. Mitigation: V1.0 had zero deployments at the time of V1.1 (by design; this revision lands before any real deployment), so no migration burden exists in practice. Future V1.x patches can add capability without requiring this kind of architectural shift.

## Consequences

### Positive

- V1.1 deployments operate by the third cardinal insight, not against it
- Honest unknowns at first scaffold become rescaffold triggers, not dead-ends
- The kit's value compounds with deployment age (more context => stronger scaffolds), not the inverse
- V2 receives evidence from real recursive deployments; the recursive engine can learn from observed rescaffold patterns rather than speculation
- BOOTSTRAP-BRIEF Section XVII (rescaffold protocol) is the operational form of the philosophy section "Why continuous rescaffolding"

### Negative

- Substantial V1.1 revision; multiple documents and skills updated in one cycle
- The discovery skill is now load-bearing; quality of first scaffold depends on discovery's recursive question-spawning behavior
- The architect-rescaffold skill is new; rescaffold operation is untested in real deployments at V1.1 ship time
- The validate skill's output shape changes (now produces explicit rescaffold triggers); existing validate consumers (none yet at V1.1 time) would need to handle the new field

### Followups

- ADR-0004 (recursive question discipline) accompanies this ADR; together they define the V1.1 question + rescaffold pair
- ADR-0006 (function-adaptation + organizationally-aware skill population) defines an additional V1.1 capability (deployments adapt to user function-mode and to org-local skill repositories)
- New skills authored: `architect-discovery`, `architect-rescaffold`
- Existing skill updated: `skills/deploy/SKILL.md` becomes multi-phase orchestrator
- BOOTSTRAP-BRIEF revisions: Section I cardinal insights (added insight 3); Section V behavior triggers (added new triggers); Section XVI first-scaffold test (softened); Section XVII rescaffold protocol (new)
- PHILOSOPHY.md additions: third insight; continuous-adaptation section; rescaffold-vs-deploy-once section; function-adaptation section
- TERMS.md additions: bootstrap, discovery, initial scaffold, rescaffold, function-mode, learning-is-the-process, rescaffold trigger
- V2 framing in `AI-Architect/BACKLOG.md` updated: V2 is now "kit-of-kits + cross-deployment learning across many V1.x recursive deployments," not "the layer where adaptation begins"

## Cross-references

- ADR-0001 (polymorphic single kit) - V1.1 stays polymorphic-single-kit; recursion happens within a single kit's lifecycle, not across kits
- ADR-0004 (recursive question discipline) - the question-asking discipline that operates inside the rescaffold cycle
- ADR-0006 (function-adaptation) - the kit's adaptation surface that rescaffolds touch
- BOOTSTRAP-BRIEF Section I (cardinal insight 3 added)
- BOOTSTRAP-BRIEF Section XVII (rescaffold protocol, new)
- PHILOSOPHY.md "Why continuous rescaffolding (not deploy-once)"
- `skills/architect-rescaffold/SKILL.md` (built as part of V1.1)
- `skills/architect-discovery/SKILL.md` (built as part of V1.1)
- `AI-Architect/BACKLOG.md` Recursive Skill Optimization & Scaffolding Engine entry
