# Quellen und Fragestellungen

Quellrevision: ba5838eb3444ebb642dddf603c9e9cc991e69c97
Snapshot: 02c5084cea90f072e1556c3f541e9bfb66448d93d81181279d3138f97f458e80

## Warum sollten unsere Coding Agents Regenerative Software nutzen?

### [S026] REGENERATIVE-SOFTWARE.md:146–168

### 2.1 Preserve the system's identity

A product retains its identity through the promises users, callers, and operators depend on:

- Useful outcomes, domain rules, supported inputs, outputs, and workflows.
- Data meaning, ownership, identifiers, durability, and lifecycle.
- Authorization, isolation, privacy, and applicable domain constraints.
- Error semantics, ordering, timing, resource budgets, and recovery behavior.
- Operational and accessibility expectations, including less visible consumers.

Code realizes these promises today. Durable knowledge makes it possible to realize them again tomorrow. Preserve that knowledge outside the implementation selected for removal; continue keeping readable, idiomatic source and accepted artifacts for inspection, debugging, and recovery.

Keep four categories distinct:

| Category | Meaning |
|---|---|
| Accepted | What should be true: intent and contracts |
| Observed | What an identified implementation or environment actually did, including defects |
| Proposed | Requirements, architecture, or changes awaiting resolution |
| Demonstrated | What identified evaluations and operations establish within their scope |

Production behavior can reveal an undocumented obligation or a bug. Specifications can be incomplete. Green tests can miss the important failure. None of these categories substitutes for another.

### [S133] REGENERATIVE-SOFTWARE.md:1737–1744

### 20.6 Test the next useful change

Suppose the next requested feature adds an optional progress event between visible completion and auxiliary state. Confirm the extension policy and old-client behavior first. Update the acceptance delta and examples, implement the bounded change, and extend the gate while retaining late-state persistence checks.

Measure whether unrelated persistence/server-state internals needed changes and whether the packet supplied the knowledge. If the work fits the predicted seam, that supports the benefit hypothesis. If not, revise the seam or hypothesis. The original successful replacement alone could not establish cheaper future evolution.

---

### [S062] REGENERATIVE-SOFTWARE.md:661–680

## 8. Match pace and rigor to architectural position

Pace concerns dependency position and change cadence. Risk concerns a particular change's consequences and recoverability. Record both.

| Position | Typical characteristics | Discipline |
|---|---|---|
| Fast-changing | Contained consumers, reversible state, bounded effects | Focused behavioral gate, fast feedback, simple recovery |
| Shared product layer | Multiple consumers, meaningful persistence or workflows | Contract/integration evidence, version awareness, staged introduction where useful |
| Foundational or slow-changing | Long-lived data/clients, pervasive identity, expensive failure or reversal | Deep compatibility, migration rehearsal, broader observation, explicit retirement horizon |

Classify actual dependencies, not component names. A recommendation system can have high-consequence decisions. A cache library can be foundational because its serialization defines all active sessions. A tiny diff in a slow layer needs slow-layer evidence.

Record the reason to change now, supported consumers and oldest data/client versions, failure-appropriate verification, rollout/recovery triggers when relevant, and observation duration **plus representative volume**. Include infrequent jobs, billing periods, expiry windows, and offline clients. Define what ends old compatibility and recovery obligations.

Use existing review and release policies; resolve actual product or architectural decisions without adding generic approval queues. Tool-enforced policy exceptions require current authority for the exact artifacts/versions and evidence from the actual enforcement mechanism, including allowed and disallowed controls. An interactive offer or dependency documentation is not that authority. Keep unmet correctness checks unmet even when an exception authorizes a limited next action. Verify expiry/removal through the policy's real mechanism; self-retiring policy needs no invented manual step. Actions already inside a recorded exception need no repeated approval.

Intent and foundational contracts often outlive many implementations. Evaluations expand as operational knowledge grows. A gate is frozen for a candidate judgment, not forever. Retest apparently stable boundaries when consumers or dependencies change: an unchanged interface can acquire new timing, log, or cache dependencies.

---

### [S029] REGENERATIVE-SOFTWARE.md:199–226

### 2.4 Invest where it improves useful change

Protect knowledge before removing its container. Make correctness external to the candidate. Preserve state separately from code. Treat boundary changes as architectural decisions. Exercise replaceability rather than inferring it from diagrams, and pair introduction with retirement.

The relevant cost is:

```text
knowledge recovery + boundary work + implementation + evaluation
+ migration + observation + retirement + ongoing knowledge/tooling upkeep
```

Cheap generation changes one term. Prioritize frequent or costly changes, fragile integrations, and consequential unknowns. Stable, low-stakes code can remain ordinary maintained code. Some strong coupling intentionally protects an invariant; a consistent ledger may belong in one replacement unit.

Before an architectural investment, write a falsifiable hypothesis: **which likely change becomes easier, which obstacle disappears, and what observation would support the claim?** Use actual backlog work, incidents, or recent changes. Compare with a normal patch or deliberate retention. Estimates can select a pilot; label them separately from measured savings.

| Evidence | Useful operation |
|---|---|
| Local defect understood; boundary sound | Patch and preserve the lesson |
| Useful boundary obscured by implementation | Refactor enough to expose the seam |
| Strong intent and oracle; costly or unsuitable implementation | Compare a replacement behind the boundary |
| Ownership or communication no longer fits | Deliberate architecture change with migration |
| Behavior or consumers poorly understood | Observe, characterize, and extract knowledge first |
| Full cost exceeds likely benefit | Retain; record a revisit trigger if useful |

Reassess scope when a repair introduces a new intermediary, state owner, dependency, or long-lived resource. Successive failures that reveal a new protocol or lifecycle call for revisiting the target, not an indefinite chain of local patches. Demonstrate a useful local cycle before building a regeneration platform.

---

### [S032] REGENERATIVE-SOFTWARE.md:243–294

### 3.2 Reuse canonical knowledge and install a small operating contract

Find an existing owner for each knowledge role before adding files:

| Role | Typical existing home |
|---|---|
| Purpose, journeys, requirements | README, product specifications, domain docs |
| Architecture and rationale | Architecture docs, ADRs, dependency policies |
| Public shape and semantics | Schemas, protocol definitions, public types, interface docs |
| Behavioral truth | Tests, contract suites, evaluation datasets and runners |
| Operational knowledge | Runbooks, incident records, observability and SLO definitions |
| Agent navigation | Root/scoped instructions and supported harness configuration |
| Evidence and current work | CI artifacts, change records, issue/task, small local index |

A small product may need one design record and its existing tests. A larger one may use an index linking intent, architecture, unit dossiers, contracts, decisions, evaluations, and receipts. These roles matter more than directory names. Keep the portable guide generic and product facts in the product's own records.

The local index should expose supported commands, capability-to-path mapping, canonical contracts and gates, one current checkpoint, and the next action. Link predecessor records instead of accumulating their full narratives in the entry index; retain history at its owning records.

#### Discover actual instruction loading

Inspect the intended harnesses and their versions/configuration. Distinguish automatically loaded files, expanded imports, configured sources, and ordinary links or explicit read requests. A Markdown link does not load its target. One harness's import syntax may be inert in another; a nearer instruction file may alter root loading; delegated agents may receive only root context.

Keep a small load map:

```text
entry directory / harness → delivered files → canonical rule owner
                          → scoped read rule → observation or uncertainty
```

Check observed context or loader diagnostics when available. Documentation describes expected behavior, not an observed session. Cover root, relevant subtree, and delegated entry paths only to the extent claimed. If a delegated context lacks scoped guidance, name the required scoped reads in its work package.

#### Compile the hierarchy

| Layer | Content |
|---|---|
| Session root, such as `AGENTS.md` or `CLAUDE.md` | Short seven-primitive loop, shared constraints, precedence, canonical navigation, finish/harvest rule |
| Harness adapter, when needed | Supported import or minimal delivery mechanism; genuinely harness-specific additions |
| Scoped guide | Concrete boundaries, state/effect owners, consequential invariants, exact local commands and gates, compatibility/recovery needs |
| Local packet and evidence | Decisions, input identities, current checkpoint, detailed results and history |

Choose one canonical owner per rule. Preserve useful existing instructions, reconcile contradictions, and avoid pointer cycles or competing copies. A scoped-only entry must require reading the root contract; root guidance must require applicable scoped guides. These fallbacks are not claims of automatic loading.

Install the root contract early enough to guide the first slice, then refine it through actual work. For an adoption claim, effective session instructions MUST contain actions for all seven primitives, not merely names or a link:

```text
Start: inspect current work and checkpoint; load applicable root/scoped guidance
       and the affected contract when not already delivered.
Intent: name the outcome, preserved promises, and accepted behavior changes.
Compilation: identify the unit, boundary, state owner, consumers, and allowed effects.
Evaluations: choose justified oracles and meaningful required checks before changing code.
Provenance: retain reasons, input/candidate identities, attempts, results, and limitations.
Pace: match verification, introduction, and recovery to coupling and consequence.

### [S068] REGENERATIVE-SOFTWARE.md:804–826

| A, B | B, A | B, A | A held before forwarding | State A; distinguish commit truth from latest-dispatched selection at the required reconciliation point |
| A held, then B | B, A | B, A | Capture positive B; deliver newer positive A, then old B | State A; old positive B read must not replace newer accepted A evidence |

These are designs, not evidence that any schedule ran. Preserve genuine responses and prove their phases. A delayed acknowledgment can describe an accepted mutation whose state was later superseded. Reverse acknowledgments do not prove reverse commits. An old positive read can be stale without being empty. Leave unexecuted orderings explicitly uncovered.

#### Test direct consumers without accidentally repairing their state

An ordinary re-fetch can conceal broken adoption, recall, cache, or immutable retry state. Use a supported consumer that uses the state being judged, with independent expected content, metadata, and opaque values; inspect its attempt, acknowledgment, and exact durable effect. IDs/counts alone cannot prove freshness. Inspect attempted effects as well as final state: an incidental uniqueness or authority check may prevent corruption while losing the required origin update.

Trigger an actual supported value change for a persistence probe. An already-selected control may intentionally do nothing; evaluate that no-op separately. Resolve selectors to record identity, not to a substring mistaken for the full stored value.

Scope no-refetch/no-repair observations to actor, resource, operation, and phase. A peer's valid adoption or a legitimate post-completion refresh is not a prohibited pre-dispatch repair. If a valid pending refresh can change selection before an action, stabilize delivery at a declared boundary and allow the coherent outcomes the contract permits; do not demand an earlier view remain selected without that promise.

#### Exercise subscriptions, recovery, and retries

Establish actual feed readiness before a healthy remote-write control. A connection object or previous page read is insufficient. Confirm that the chosen operation emits the channel the consumer listens to; an auxiliary write may publish no notification. Accept supported optional/default event fields and correlate actor plus committed effect.

For delayed-read races, hold a genuine response, verify its captured state, perform navigation/newer work, and release it. Include progress arriving between capture and delivery: a live overlay must compose the fresh settled base with exactly the latest owned progress, without stale pairs or duplicates.

Reconnection and catch-up are separate obligations. Observe actual failure and renewed readiness, then verify missed settled changes and current live progress through non-repairing consumers. Include recovery after remote completion, during ongoing work, and repeated drops when claimed. Exact replay must not duplicate data. An offline-emulation flag may leave sockets alive; prove the fault with a minimal diagnostic before an expensive journey.

For retries that restart rather than resume, show partial progress, trigger the real retry signal, and hold the next attempt ready before new output. Observe the required reset then final state, bounded exhaustion, and healthy non-retry behavior. Distinguish user-action correlation from physical attempt identity; stable correlation is not idempotency evidence.

### [S020] REGENERATIVE-SOFTWARE.md:3–20

## A repository translation and operating playbook for coding agents

**Version:** 3.0.1

**Purpose:** Make useful software evolution cheaper and more reliable by preserving product knowledge, establishing independently changeable boundaries, and verifying that implementations can change or be replaced without losing essential behavior or state.

This is a standalone execution brief for engineers and coding agents. It supplies principles, discovery methods, design rules, implementation procedures, evaluations, and completion criteria. It assumes no particular language, framework, agent harness, deployment platform, or repository layout.

The result should be a working product that becomes easier to change correctly: justified improvements, executable behavioral knowledge, accurate documentation, trustworthy evidence, and a usable next step. An implementation engagement must deliver a verified product or enabling improvement; a report alone does not complete it. Replacement is one operation available to achieve that result. A rewrite, a documentation tree, or a large test count is not the objective.

**The reconstruction question:** If a chosen implementation disappeared, could another engineer or agent reconstruct an acceptable substitute from the surviving knowledge, evaluate it independently, and introduce it without surprising its consumers?

**The economic test:** Does the next useful change require less rediscovery, coordination, and verification effort without degrading the product?

Earn the answer boundary by boundary. Some systems cannot be made broadly replaceable at reasonable cost. Preserve what matters, expose remaining coupling, and make claims no broader than the evidence.

---

### [S024] REGENERATIVE-SOFTWARE.md:111–125

### 1.3 Execute the next useful action

For each slice:

1. **Choose:** name the product outcome, boundary, and reason to invest. Keeping the implementation is a legitimate choice.
2. **Understand:** trace the affected journey, consumers, state, and checks; resolve the uncertainties this slice depends on.
3. **Specify:** record preserved promises and intentional changes; identify the oracle, required checks, baseline, and recovery needs before judging a candidate.
4. **Change:** implement the smallest complete patch, seam repair, replacement, migration, or knowledge improvement, including affected consumers and documentation.
5. **Verify:** evaluate the identified integrated candidate and affected journeys. Diagnose failure rather than lowering the gate.
6. **Harvest:** retain reasons and evidence, remove justified temporary complexity, update the owning instructions and packet, state the exact outcome, and continue to the next in-scope slice.

The minimum packet answers **why, what must hold, where change belongs, how to verify, what happened, and what comes next**. Existing documents and tests can supply most of it. Use the six-line template in Section 19.1.

Add an evaluation for an important uncovered promise, not merely to mirror a reversible, low-impact edit. If a corrected gate accepts the unchanged implementation, preserve that implementation and record the verified evaluation or knowledge improvement.

### [S061] REGENERATIVE-SOFTWARE.md:644–660

### 7.8 Classify architectural scope before implementation

| Change | Treatment |
|---|---|
| Implementation behind an unchanged boundary | Preserve accepted contracts and required behavior |
| Intentional behavior change | Record acceptance delta and supported combinations |
| Contract, ownership, or communication change | Record architecture decision, consumer migration, and recovery |
| Runtime/framework/provider upgrade | Revalidate implicit behavior, historical state, packaging, and operations |
| Evaluation correction | Correct knowledge separately; rejudge affected claims without automatically changing code |
| Documentation clarification | Verify meaning and examples; rebuild only actual derived artifacts |

Additive changes can break consumers through new enum values, defaults, validation, order, or extra events. Compatibility is a demonstrated property, not a diff-size label.

When the target changes, retain the old target, evidence that it no longer fits, proposed target, preserved intent, migration cost, and evaluation plan. Cost, latency, reliability, platform support, and team operating capacity can justify architectural change; novelty alone does not.

---

### [S096] REGENERATIVE-SOFTWARE.md:1232–1249

### 13.5 Rehearse recovery at storage and product boundaries

Use sanitized historical fixtures and disposable targets for interrupted migration, partial backfill, retry, concurrent updates, restart, and restoration. Define recovery-point/time expectations when relevant. Distinguish binary rollback, forward repair, replay, and disaster restore; an old backup can discard valid later writes.

Verify a restore through exact records, identities, referenced blobs/bytes, and schema/producer metadata in a fresh target. A command exit, row count, or healthy process is insufficient. Challenge completeness with an intentionally incomplete copy. Retain the original snapshot, prove later source writes are absent from the restored point, and allow only enumerated recovery changes. A quiesced snapshot rehearsal does not establish online, atomic, or incremental backup guarantees.

Recover the complete representation, including journals, sidecars, keys, and blobs. Renaming one live file is not recovery of a multi-file store. Validate commands against actual configuration precedence and reject unsupported combinations before effects.

**Storage restoration and product recovery are separate claims.** For product recovery, boot real consumers on disposable restored copies and exercise supported authentication, allowed/denied reads, linked content, keys, and important journeys. Capture originals before/after to establish isolation. HTTP checks do not establish browser behavior; a no-model run does not establish model quality.

Startup may legitimately mutate state through schema ensures, defaults, or backfills. Enumerate exact permitted definitions, owners, and values derived from pre-boot state or an independent rule. Do not hide unexplained writes behind broad metadata/timestamp exclusions or copy product output into the oracle.

For process-restart continuity, observe actual termination, retain durable bytes, launch a fresh process on the same owned state root, and check subsequent exact content/opaque state against independent prior values. Two clients in one process, or state retained in a fixture, cannot establish persistence across restart.

External effects such as payments and notifications survive code rollback. Define domain-appropriate deduplication, compensation, or reconciliation. Where an artifact is intrinsically immutable, choose a replaceable adapter boundary or an explicit migration to a new identity.

---

### [S108] REGENERATIVE-SOFTWARE.md:1397–1398

## 16. Retire implementations and compact the system

## Was muss überleben, wenn sich die Implementierung verändert?

### [S007] README.md:172–187

## The seven primitives

| Primitive | What agents do |
| --- | --- |
| Intent | Preserve outcomes, invariants, negative constraints, and their reasons |
| Compilation | Implement inside explicit boundaries, ownership, and runtime constraints |
| Evaluations | Judge observable promises with justified, reusable oracles |
| Provenance | Retain reasons, actual inputs, candidates, results, and limitations |
| Pace | Match verification and introduction to coupling and consequences |
| Deletion | Protect knowledge, state, and consumers before removing implementations |
| Compaction | Retire complexity whose obligations have ended |

These are working practices, not seven required documents. Reuse the project's
canonical records. Templates are optional information shapes, not a directory
scaffold to stamp into every repository.

### [S027] REGENERATIVE-SOFTWARE.md:169–184

### 2.2 Make the seven primitives work together

| Primitive | Question | Durable expression | Practical demonstration |
|---|---|---|---|
| **Intent** | What must remain true, for whom, and why? | Requirements, invariants, negative constraints, reasons | A replacement author understands the obligations without reading the old implementation |
| **Compilation** | What architectural shape must implementations fit? | Boundaries, ownership, communication, runtime constraints, explicit freedoms | The candidate fits the target without silently redesigning neighbors |
| **Evaluations** | How do we judge whether promises survived? | Behavioral checks, fixtures, properties, workload and quality criteria | The same meaningful oracle judges different implementations |
| **Provenance** | Why does this exist, and what produced it? | Decisions, rejected alternatives, incident lessons, versioned inputs and results | A maintainer can recover the reason for an unusual rule and identify what ran |
| **Pace** | How cautiously should this layer evolve? | Compatibility policy, consequence-based gates, observation and recovery needs | Introduction matches actual dependencies and failure consequences |
| **Deletion** | Can the old implementation disappear? | Consumer inventory, isolation evidence, retirement and recovery procedure | Removal preserves known obligations |
| **Compaction** | What no longer earns its complexity? | Consolidated concepts, retired paths, simpler configuration and guidance | The next maintainer needs less incidental knowledge to change the product |

Operational evidence connects all seven: it exposes missing intent, challenges oracles, explains constraints, informs pace, reveals consumers, and supports retirement.

A durable artifact counts when the workflow actually uses it. The primitives are neither seven mandatory documents nor a waterfall. An ordinary patch can express them with existing references and a short record. A report describing them does not establish their adoption.

### [S032] REGENERATIVE-SOFTWARE.md:243–294

### 3.2 Reuse canonical knowledge and install a small operating contract

Find an existing owner for each knowledge role before adding files:

| Role | Typical existing home |
|---|---|
| Purpose, journeys, requirements | README, product specifications, domain docs |
| Architecture and rationale | Architecture docs, ADRs, dependency policies |
| Public shape and semantics | Schemas, protocol definitions, public types, interface docs |
| Behavioral truth | Tests, contract suites, evaluation datasets and runners |
| Operational knowledge | Runbooks, incident records, observability and SLO definitions |
| Agent navigation | Root/scoped instructions and supported harness configuration |
| Evidence and current work | CI artifacts, change records, issue/task, small local index |

A small product may need one design record and its existing tests. A larger one may use an index linking intent, architecture, unit dossiers, contracts, decisions, evaluations, and receipts. These roles matter more than directory names. Keep the portable guide generic and product facts in the product's own records.

The local index should expose supported commands, capability-to-path mapping, canonical contracts and gates, one current checkpoint, and the next action. Link predecessor records instead of accumulating their full narratives in the entry index; retain history at its owning records.

#### Discover actual instruction loading

Inspect the intended harnesses and their versions/configuration. Distinguish automatically loaded files, expanded imports, configured sources, and ordinary links or explicit read requests. A Markdown link does not load its target. One harness's import syntax may be inert in another; a nearer instruction file may alter root loading; delegated agents may receive only root context.

Keep a small load map:

```text
entry directory / harness → delivered files → canonical rule owner
                          → scoped read rule → observation or uncertainty
```

Check observed context or loader diagnostics when available. Documentation describes expected behavior, not an observed session. Cover root, relevant subtree, and delegated entry paths only to the extent claimed. If a delegated context lacks scoped guidance, name the required scoped reads in its work package.

#### Compile the hierarchy

| Layer | Content |
|---|---|
| Session root, such as `AGENTS.md` or `CLAUDE.md` | Short seven-primitive loop, shared constraints, precedence, canonical navigation, finish/harvest rule |
| Harness adapter, when needed | Supported import or minimal delivery mechanism; genuinely harness-specific additions |
| Scoped guide | Concrete boundaries, state/effect owners, consequential invariants, exact local commands and gates, compatibility/recovery needs |
| Local packet and evidence | Decisions, input identities, current checkpoint, detailed results and history |

Choose one canonical owner per rule. Preserve useful existing instructions, reconcile contradictions, and avoid pointer cycles or competing copies. A scoped-only entry must require reading the root contract; root guidance must require applicable scoped guides. These fallbacks are not claims of automatic loading.

Install the root contract early enough to guide the first slice, then refine it through actual work. For an adoption claim, effective session instructions MUST contain actions for all seven primitives, not merely names or a link:

```text
Start: inspect current work and checkpoint; load applicable root/scoped guidance
       and the affected contract when not already delivered.
Intent: name the outcome, preserved promises, and accepted behavior changes.
Compilation: identify the unit, boundary, state owner, consumers, and allowed effects.
Evaluations: choose justified oracles and meaningful required checks before changing code.
Provenance: retain reasons, input/candidate identities, attempts, results, and limitations.
Pace: match verification, introduction, and recovery to coupling and consequence.

### [S048] REGENERATIVE-SOFTWARE.md:474–495

### 6.1 State obligations independently of implementation

A useful statement contains:

```text
stable ID + scope + actor/context + invariant or outcome + reason
          + evidence/authority + verification method + status
```

Describe the promise rather than today's method calls:

| Implementation description | Durable intent |
|---|---|
| Call `reserve()` before `charge()` | A customer must not be charged for stock that was not successfully reserved for that order |
| Cache for 30 seconds | Meet the accepted freshness and response-time budgets under the stated workload; preserve their rationale |
| Invoke a final-stream callback | Distinguish visible completion, transport completion, and required durable state completion |
| Use an auth helper in every route | Every entry exposing protected state must enforce the applicable principal and resource scope |

Preserve negative constraints such as no duplicate financial effects, cross-tenant exposure, lost accepted work, false durable success, or silent truncation where completeness is promised. Pair them with positive progress: rejecting every request can satisfy a prohibition while defeating the product.

Include contractual, regulatory, and domain obligations where they actually apply, with their sources and scope. A user story describes an activity; intent also states what must remain true across implementations of that activity.

### [S091] REGENERATIVE-SOFTWARE.md:1139–1146

### 13.1 Inventory the whole state boundary

Identify durable records, files, indexes, caches, sessions, checkpoints, queues, blobs, journals, and sidecars; authoritative sources versus derived representations; mutation/transaction owners; IDs/references; schemas, serialization, defaults, encryption/key dependencies, retention; and export, backup, repair, reconciliation, and restore procedures.

“Derived” does not mean disposable without cost. Verify that inputs, transformation versions, permissions, compute, and reconstruction time are available within the recovery requirement. Rebuilding an index or embedding store can alter behavior as well as consume resources.

Carry semantic distinctions throughout the lifecycle. Updates, historical records, or deletion of the last grant can produce empty sets that creation validation excluded. Preserve the difference between absent/unrestricted and empty/none through every consumer, including counts and enrichment.

### [S062] REGENERATIVE-SOFTWARE.md:661–680

## 8. Match pace and rigor to architectural position

Pace concerns dependency position and change cadence. Risk concerns a particular change's consequences and recoverability. Record both.

| Position | Typical characteristics | Discipline |
|---|---|---|
| Fast-changing | Contained consumers, reversible state, bounded effects | Focused behavioral gate, fast feedback, simple recovery |
| Shared product layer | Multiple consumers, meaningful persistence or workflows | Contract/integration evidence, version awareness, staged introduction where useful |
| Foundational or slow-changing | Long-lived data/clients, pervasive identity, expensive failure or reversal | Deep compatibility, migration rehearsal, broader observation, explicit retirement horizon |

Classify actual dependencies, not component names. A recommendation system can have high-consequence decisions. A cache library can be foundational because its serialization defines all active sessions. A tiny diff in a slow layer needs slow-layer evidence.

Record the reason to change now, supported consumers and oldest data/client versions, failure-appropriate verification, rollout/recovery triggers when relevant, and observation duration **plus representative volume**. Include infrequent jobs, billing periods, expiry windows, and offline clients. Define what ends old compatibility and recovery obligations.

Use existing review and release policies; resolve actual product or architectural decisions without adding generic approval queues. Tool-enforced policy exceptions require current authority for the exact artifacts/versions and evidence from the actual enforcement mechanism, including allowed and disallowed controls. An interactive offer or dependency documentation is not that authority. Keep unmet correctness checks unmet even when an exception authorizes a limited next action. Verify expiry/removal through the policy's real mechanism; self-retiring policy needs no invented manual step. Actions already inside a recorded exception need no repeated approval.

Intent and foundational contracts often outlive many implementations. Evaluations expand as operational knowledge grows. A gate is frozen for a candidate judgment, not forever. Retest apparently stable boundaries when consumers or dependencies change: an unchanged interface can acquire new timing, log, or cache dependencies.

---

### [S017] SKILL.md:148–176

## Embed the operating loop

Where edits are permitted, merge the
[operating contract](assets/templates/operating-contract.md) into the target
repository's real instruction entry point early, then refine it from actual work.
Actions for all seven primitives must be present: intent, compilation,
evaluations, provenance, pace, deletion, and compaction. Bind navigation and checks
to real product paths. Keep one canonical owner per rule and scoped guidance for
local boundaries. Preserve useful preexisting instructions.

When another process workflow runs alongside, such as Superpowers, keep one
owner per role. Its steps may own the design dialog, plan, execution, review, and
branch completion; this method keeps accepted intent, the frozen gate, evidence
claims, the checkpoint, and harvest. Name the binding in the canonical entry,
carry slice fields and gate commands into the companion's records, and harvest
records the companion deletes by design before they disappear. A companion
decision that changes accepted intent or acceptance semantics pauses only the
affected task and its dependents: harvest completed verified work, update the
checkpoint, and ask the existing decision owner about the consequential
unresolved change; independent authorized work continues. For Superpowers,
merge the [Superpowers binding](assets/templates/companion-superpowers.md).

Discover the intended harness's actual loading rules. Keep content/navigation,
loader observation, and ordinary fresh-session use as three separate checks.
Provide explicit read fallbacks when loading cannot be observed. Skill
installation alone does not establish ongoing adoption, schedule future agents,
or authorize unattended changes. Continue through the existing task/release
system; any automation must have explicit scope, ownership, and stop conditions.

### [S122] REGENERATIVE-SOFTWARE.md:1534–1557

### 19.2 Intent or finding record

```yaml
id: INV-001
version: 1
type: invariant
status: proposed  # proposed / accepted / disputed / superseded
scope: "<actor, capability, conditions>"
statement: "<implementation-independent obligation>"
reason: "<product consequence and rationale>"
authority: "<established source or decision owner>"
evidence:
  - reference: "<retrievable source, version, symbol or observation>"
    classification: observed  # required / historical / inferred / unknown
definitions: []
contracts: []
evaluations: []
operational_signals: []
supersedes: []
open_questions: []
```

For a finding, add reproduction/query, observed environment, affected consumer, contradictory evidence, and next action. An inference remains an inference until supported.

### [S006] README.md:159–171

## Skills

| Skill | Purpose |
| --- | --- |
| [regenerative-software](SKILL.md) | Entry point: route, execute, verify, harvest, continue |
| [regenerative-architecture](regenerative-architecture/SKILL.md) | Greenfield design, intent, contracts, state ownership, seam repair |
| [regenerative-adoption](regenerative-adoption/SKILL.md) | Existing-repo discovery, instruction integration, campaigns and resumes |
| [regenerative-evaluations](regenerative-evaluations/SKILL.md) | Independent oracles, fail-closed gates, async and runtime AI evaluation |
| [regenerative-state](regenerative-state/SKILL.md) | Durable state, migrations, late work, compatibility and recovery |
| [regenerative-provenance](regenerative-provenance/SKILL.md) | Input identities, execution receipts, documentation and operational evidence |
| [regenerative-reconstruction](regenerative-reconstruction/SKILL.md) | Survival packs, isolated substitution, fresh-context reconstruction |
| [regenerative-evolution](regenerative-evolution/SKILL.md) | Continuous improvement, selective revalidation, retirement and compaction |

### [S021] REGENERATIVE-SOFTWARE.md:21–47

## Contents

1. [Activate this playbook](#1-activate-this-playbook)
2. [Define the target](#2-define-the-target)
3. [Establish the engagement and durable workspace](#3-establish-the-engagement-and-durable-workspace)
4. [Coordinate work and optional delegation](#4-coordinate-work-and-optional-delegation)
5. [Discover the actual product](#5-discover-the-actual-product)
6. [Extract and validate intent](#6-extract-and-validate-intent)
7. [Define the architectural target and contracts](#7-define-the-architectural-target-and-contracts)
8. [Match pace and rigor to architectural position](#8-match-pace-and-rigor-to-architectural-position)
9. [Build evaluations that survive replacement](#9-build-evaluations-that-survive-replacement)
10. [Evaluate probabilistic and agentic behavior](#10-evaluate-probabilistic-and-agentic-behavior)
11. [Make documentation part of the product contract](#11-make-documentation-part-of-the-product-contract)
12. [Preserve provenance and operational evidence](#12-preserve-provenance-and-operational-evidence)
13. [Make state and migrations survive replacement](#13-make-state-and-migrations-survive-replacement)
14. [Run the regeneration pipeline](#14-run-the-regeneration-pipeline)
15. [Exercise replacement and reconstruction](#15-exercise-replacement-and-reconstruction)
16. [Retire implementations and compact the system](#16-retire-implementations-and-compact-the-system)
17. [Keep the feedback loop operating](#17-keep-the-feedback-loop-operating)
18. [Adapt to different repository and product types](#18-adapt-to-different-repository-and-product-types)
19. [Use the implementation templates](#19-use-the-implementation-templates)
20. [Walk through a worked example](#20-walk-through-a-worked-example)
21. [Recognize failure modes](#21-recognize-failure-modes)
22. [Finish with evidence and a usable handoff](#22-finish-with-evidence-and-a-usable-handoff)

---

### [S028] REGENERATIVE-SOFTWARE.md:185–198

### 2.3 Use precise working terms

- **Unit:** a capability or decision that can change coherently; it may be a module within a monolith.
- **Boundary:** the supported interaction across which consumers should not need coordinated implementation changes.
- **Contract:** the boundary's behavioral and state obligations, not just its type or schema.
- **Oracle:** the justified source of expected behavior or acceptance criteria.
- **Gate:** the versioned selection of required checks and decision rules for a named stage.
- **Candidate:** the identified implementation and relevant built artifacts being judged.
- **Receipt:** a retained record of an execution or judgment, including its inputs, outcomes, and limitations.
- **Input closure:** the direct and transitive inputs actually consumed by a stage, including generated artifacts, configuration, and tools where relevant.
- **Survival pack:** the knowledge, execution support, and declared dependencies that remain when a selected implementation is unavailable.

“Compilation” describes implementing accepted intent inside an explicit architectural target. Natural-language validation remains judgment, and generation may be probabilistic. Content digests and stable records make inputs addressable; they do not make semantic interpretation or generation deterministic.

## Wie installieren wir den Skill und wie arbeitet ein Agent damit?

### [S032] REGENERATIVE-SOFTWARE.md:243–294

### 3.2 Reuse canonical knowledge and install a small operating contract

Find an existing owner for each knowledge role before adding files:

| Role | Typical existing home |
|---|---|
| Purpose, journeys, requirements | README, product specifications, domain docs |
| Architecture and rationale | Architecture docs, ADRs, dependency policies |
| Public shape and semantics | Schemas, protocol definitions, public types, interface docs |
| Behavioral truth | Tests, contract suites, evaluation datasets and runners |
| Operational knowledge | Runbooks, incident records, observability and SLO definitions |
| Agent navigation | Root/scoped instructions and supported harness configuration |
| Evidence and current work | CI artifacts, change records, issue/task, small local index |

A small product may need one design record and its existing tests. A larger one may use an index linking intent, architecture, unit dossiers, contracts, decisions, evaluations, and receipts. These roles matter more than directory names. Keep the portable guide generic and product facts in the product's own records.

The local index should expose supported commands, capability-to-path mapping, canonical contracts and gates, one current checkpoint, and the next action. Link predecessor records instead of accumulating their full narratives in the entry index; retain history at its owning records.

#### Discover actual instruction loading

Inspect the intended harnesses and their versions/configuration. Distinguish automatically loaded files, expanded imports, configured sources, and ordinary links or explicit read requests. A Markdown link does not load its target. One harness's import syntax may be inert in another; a nearer instruction file may alter root loading; delegated agents may receive only root context.

Keep a small load map:

```text
entry directory / harness → delivered files → canonical rule owner
                          → scoped read rule → observation or uncertainty
```

Check observed context or loader diagnostics when available. Documentation describes expected behavior, not an observed session. Cover root, relevant subtree, and delegated entry paths only to the extent claimed. If a delegated context lacks scoped guidance, name the required scoped reads in its work package.

#### Compile the hierarchy

| Layer | Content |
|---|---|
| Session root, such as `AGENTS.md` or `CLAUDE.md` | Short seven-primitive loop, shared constraints, precedence, canonical navigation, finish/harvest rule |
| Harness adapter, when needed | Supported import or minimal delivery mechanism; genuinely harness-specific additions |
| Scoped guide | Concrete boundaries, state/effect owners, consequential invariants, exact local commands and gates, compatibility/recovery needs |
| Local packet and evidence | Decisions, input identities, current checkpoint, detailed results and history |

Choose one canonical owner per rule. Preserve useful existing instructions, reconcile contradictions, and avoid pointer cycles or competing copies. A scoped-only entry must require reading the root contract; root guidance must require applicable scoped guides. These fallbacks are not claims of automatic loading.

Install the root contract early enough to guide the first slice, then refine it through actual work. For an adoption claim, effective session instructions MUST contain actions for all seven primitives, not merely names or a link:

```text
Start: inspect current work and checkpoint; load applicable root/scoped guidance
       and the affected contract when not already delivered.
Intent: name the outcome, preserved promises, and accepted behavior changes.
Compilation: identify the unit, boundary, state owner, consumers, and allowed effects.
Evaluations: choose justified oracles and meaningful required checks before changing code.
Provenance: retain reasons, input/candidate identities, attempts, results, and limitations.
Pace: match verification, introduction, and recovery to coupling and consequence.

### [S003] README.md:32–83

## How

Four steps, in the project you want to improve.

**1. Install the skill into that project.** From the intranet skills host, one
command; it works for Claude Code, Codex, and other
[Agent Skills](https://agentskills.io/specification) loaders:

```sh
cd /path/to/your-project
npx skills add https://reg.deploy.qwellco.de --skill regenerative-software
```

The CLI verifies the archive digest, writes the skill into the agent's skills
directory, and records the digest in `skills-lock.json`. Commit that file so
teammates get the same copy. Add `--agent claude-code` or `--agent codex` to
choose the target; `--list` shows all eight skills.

**2. Set the project up on first use.** Installing only copies files, so the
entry skill runs its setup the first time it is used in a project with neither
a usable regenerative operating contract in its entry instructions nor a
current checkpoint, or when you ask: *"Use regenerative-software setup."* It
detects what it can, reuses answers you already supplied, and asks once for
the consequential rest: new or existing project, which companion workflows run
alongside (for example
[Superpowers](docs/usage.md#working-alongside-superpowers)), which agent
harnesses you use, and what agents may commit, branch, delegate, or push. It
writes no operating contract, adapters, or checkpoint until you answer;
independent work the session is already authorized to do can continue while
answers are pending. The result is a canonical `AGENTS.md` operating contract,
thin harness adapters such as a `CLAUDE.md` that imports it, and a checkpoint.

**3. Start a coding session there and state the objective.** The entry skill
routes to the right topic (architecture, adoption, evaluations, state,
provenance, reconstruction, evolution), discovers the product's journeys and
current state, works in bounded slices, verifies with the project's own
commands, and leaves a replayable checkpoint. If it does not trigger on its own,
name it: *"Use the regenerative-software skill to …"*. Ready-made prompts for an
existing repository, a new project, and ongoing work are
[below](#prompts-to-start-with).

**4. Continue from the checkpoint next time.** Later sessions reconcile the
checkpoint, contracts, and evidence instead of rediscovering the product. After
the host is redeployed with a newer skill, `npx skills update` refreshes the
installed copy.

Modes: `translate` (default: implement and verify an improvement), `assess`
(report only), `regenerate <unit>`, `rehearse <unit>`, `compact <scope>`, and
`setup` (configure the project's entry instructions).
The skills contain no executable code and require no particular model, MCP
server, or framework. [Using the skills](docs/usage.md) is the full walkthrough.

### [S005] README.md:117–158

## Prompts to start with

Copy one of these into a coding session in the installed project.

**Existing repository**

```text
Use regenerative-software to improve this repository. Discover the important
journeys and current working state, choose a valuable bounded slice, preserve
supported behavior, implement a justified improvement, and verify it. Embed the
seven-primitive operating loop in our actual agent entry points and leave a
replayable checkpoint for the next session.
```

**New project**

```text
Use regenerative-software to build this new project: <product and constraints>.
Design around user outcomes, coherent state ownership, independently changeable
boundaries, and behavioral evaluations. Build a working vertical slice and retain
the intent, architecture decisions, exact checks, and next step in the repository.
Keep hypotheses provisional and avoid speculative infrastructure.
```

**Ongoing work**

```text
Continue from <checkpoint>. Reconcile current changes, contracts, and evidence.
Implement <next requested outcome>, preserve existing promises, record intentional
changes, run the affected gate, and harvest what the next agent needs to know.
```

Use `assess` for a report-only engagement; it offers setup rather than writing
instructions on its own. Implementation requests require a
verified product or enabling improvement. A repository-wide request becomes a
multi-slice campaign; the first successful slice is a checkpoint.

See [using the skills](docs/usage.md) for the complete loading and utilization
guide: what gets installed, how agents load the skill and its topic references,
the six modes, project setup and companion workflows, what a healthy engagement
looks like, keeping installed copies current, and troubleshooting.

### [S013] SKILL.md:15–51

## Begin

1. Read [REGENERATIVE-SOFTWARE.md](REGENERATIVE-SOFTWARE.md) completely on initial
   adoption, continuing beyond truncated output. It is the foundation. On resume,
   reconcile its version, the checkpoint, and changed inputs; reread affected
   sections rather than repeating product discovery.
2. Follow the engagement's instruction hierarchy and repository rules. Inspect
   staged, unstaged, untracked, generated, and externally managed work. Preserve
   other writers' changes and use existing commands and canonical knowledge.
3. If the project has neither a usable regenerative operating contract nor a
   current checkpoint, or the user asks for setup, run
   [Set up a project](#set-up-a-project) first. If the user declines, continue
   the requested work and state that the project remains unconfigured. In
   report-only `assess`, offer setup and record that the project remains
   unconfigured instead of writing instructions uninvited.
4. State mode, scope, environment, intended evidence claim, and the next useful
   outcome. Default to `translate`: discover, implement justified improvements,
   and verify locally. Without a wider objective, choose one valuable capability.
5. For an empty repository, use the architecture workflow below to establish
   intent and a working vertical slice. Do not invent a historical baseline.
6. For a repository-wide objective, inventory capabilities and important journeys,
   prioritize slices, and continue through the requested scope. Give every
   capability an evidenced disposition; a pilot does not complete the campaign.

| Mode | Finish with |
| --- | --- |
| `translate` | Verified product or enabling improvement and durable knowledge |
| `assess` | Evidence-backed findings, boundaries, obstacles, prioritized next work |
| `regenerate <unit>` | Evaluated candidate behind an explicit, ready boundary |
| `rehearse <unit>` | Isolated reconstruction experiment with honest context records |
| `compact <scope>` | Verified removal/consolidation of eligible complexity |
| `setup` | Confirmed setup answers, bound entry instructions and adapters, checkpoint, next action |

New-project work is a `translate` starting condition, not an excuse to skip
implementation when the user asked for a build. An architecture-only request may
finish in `assess` with a concrete design and implementation handoff.

### [S033] REGENERATIVE-SOFTWARE.md:295–305

Deletion: protect knowledge and state; establish consumer/removal conditions first.
Compaction: remove superseded complexity while retaining distinct behavior and rationale.
Finish: verify the integrated candidate; update canonical/published knowledge;
        harvest reusable lessons into owning instructions; state the actual claim
        and next actionable step.
```

Bind those actions to real paths, commands, owners, and change consequences. Keep routine context small: measure expanded instructions, because unconditional imports do not reduce context cost. Load deep packets only when needed. Qualify machine-specific paths, tool versions, scratch locations, and limits by machine and date.

If instruction edits are forbidden, retain the contract in a permitted local record and state that automatic next-session adoption is unestablished. Validate content, actual delivery, and fresh-session use separately under Section 11.3; a filename establishes none of them.

### [S146] docs/usage.md:75–106

## 3. Set up the project

Installing copies files; it cannot ask anything. Setup runs automatically only
when a project has neither a usable regenerative operating contract in its entry
instructions nor a current checkpoint; when either is present, normal work
proceeds without automatic setup. You can always ask for it directly:

```text
Use regenerative-software setup.
```

The agent first inspects the project (empty or existing code, current
`AGENTS.md`/`CLAUDE.md`/other entry files, checkpoint, build and test commands,
visible skills and plugins), reuses any answers you already supplied in the
request or session, and asks only for the consequential missing ones, with
detected defaults:

| Question | Effect |
| --- | --- |
| New project or existing repository? | Continues with the architecture topic (new) or the adoption topic (existing) |
| Companion workflows, such as Superpowers? | Adds an explicit role binding so both methods do not compete for the same steps |
| Which agent harnesses? | `AGENTS.md` stays canonical; other harnesses get thin adapters, for example a `CLAUDE.md` containing `@AGENTS.md` |
| What may agents do? | Records commit, branch/worktree, delegation, and merge/push authority |

It also proposes where intent, architecture, and the checkpoint live and lets
you correct that. It writes no entry instructions, harness adapters, or
checkpoint until you answer; while answers are pending those writes pause, but
independent work the session is already authorized to do continues. The result
is the merged operating contract with a *Project setup* block, the adapters,
and a checkpoint. Setup verifies links and existing commands but does not claim
that a harness loads the files automatically; check that in a fresh session.

### [S147] docs/usage.md:107–136

### Working alongside Superpowers

[Superpowers](https://github.com/obra/superpowers) and this skill both describe
how an agent should work, and both would otherwise claim the plan, verification,
and completion steps. Setup writes an explicit role binding into `AGENTS.md`
from the [Superpowers template](../assets/templates/companion-superpowers.md),
adapting the step names to the installed Superpowers version:

- **Superpowers owns the inner loop:** brainstorming, the spec and plan,
  test-driven execution, review, and finishing the branch.
- **Regenerative software owns the outer loop:** accepted intent, the frozen
  gate, evidence claims, the checkpoint, and harvest.
- Brainstorming's context step reads the checkpoint and contract first. The
  spec carries the slice fields (why, promises, boundary, oracle, exact gate
  commands); the plan's global constraints carry the gate and end with harvest.
- A ruling during plan execution that changes accepted intent or the gate
  pauses the affected tasks and their dependents for a decision; completed
  verified work is harvested, the checkpoint is updated, and independent
  authorized work continues. Every ruling that affects intent, the gate, or the
  next action is harvested before the plan workspace is deleted.
- Delegation, worktrees, commits, merges, and pushes follow the authority
  recorded during setup.

The template requires no plugin and does not prove that either workflow is
installed, loaded, or used in a fresh session. Without Superpowers (another
harness or a teammate without the plugin), the operating contract works on its
own. For any other process skill, setup records the same role split explicitly:
one owner per role, and regenerative software keeps intent, gate, claims,
checkpoint, and harvest.

### [S148] docs/usage.md:137–196

## 4. Put it to work

Start a session in the project and state the objective. The skill's entry point
declares six modes; name the one you want when it matters:

| Mode | Finish with |
| --- | --- |
| `translate` (default) | Verified product or enabling improvement and durable knowledge |
| `assess` | Evidence-backed findings, boundaries, obstacles, prioritized next work |
| `regenerate <unit>` | Evaluated candidate behind an explicit, ready boundary |
| `rehearse <unit>` | Isolated reconstruction experiment with honest context records |
| `compact <scope>` | Verified removal/consolidation of eligible complexity |
| `setup` | Confirmed setup answers, bound entry instructions and adapters, checkpoint, next action |

Typical engagements:

**Adopt in an existing repository**

```text
Use regenerative-software to improve this repository. Discover the important
journeys and current working state, choose a valuable bounded slice, preserve
supported behavior, implement a justified improvement, and verify it. Embed the
seven-primitive operating loop in our actual agent entry points and leave a
replayable checkpoint for the next session.
```

**Start a new project**

```text
Use regenerative-software to build this new project: <product and constraints>.
Design around user outcomes, coherent state ownership, independently changeable
boundaries, and behavioral evaluations. Build a working vertical slice and retain
the intent, architecture decisions, exact checks, and next step in the repository.
```

**Continue previous work**

```text
Continue from <checkpoint>. Reconcile current changes, contracts, and evidence.
Implement <next requested outcome>, preserve existing promises, record
intentional changes, run the affected gate, and harvest what the next agent
needs to know.
```

On resume, load the current checkpoint and changed inputs first, then only the
affected guidance not already in context. Keep one current checkpoint and link
predecessor evidence instead of copying campaign history into each continuation.

**Report only** — add *"assess mode: report only, do not implement"* to any of
the above. Assess offers setup when the project lacks one; it never writes
instructions silently.

What to expect from a healthy engagement: the agent states mode, scope, and
intended evidence claim before working; preserves untracked and unrelated work;
implements a bounded slice instead of a repository-wide rewrite; verifies with
the project's own commands; and leaves a checkpoint (intent, decisions, exact
checks, next step) that the next session can resume from. Use `assess` when you
want findings without implementation; a repository-wide request becomes a
multi-slice campaign, and the first successful slice is a checkpoint.

### [S014] SKILL.md:52–99

## Set up a project

Installing a skill copies files; it asks nothing and configures nothing. Setup
happens on first use in a project, or whenever the user asks for it.

1. **Detect before asking.** Inspect whether the repository is empty or holds
   product code and history; which entry instructions exist (`AGENTS.md`,
   `CLAUDE.md`, `GEMINI.md`, harness rule directories); any checkpoint or
   canonical intent, architecture, and evidence owners; real build and test
   commands; and which other skills or plugins the session or project shows
   (available-skill lists, `skills-lock.json`, their records in the tree).
2. **Ask once, with detected defaults.** Use the harness's structured question
   tool when it has one; otherwise ask plainly in one bundled message. If the
   user already supplied answers, reuse them and ask only the consequential
   choices that remain unresolved. Skip questions the evidence already settles,
   but let the user confirm the result:
   - Starting point: a new project, or adding the method to an existing one?
   - Companion workflows: will Superpowers or other process skills run alongside?
   - Harnesses: which agents work here (for example Claude Code, Codex)?
   - Authority: may agents commit, create branches or worktrees, delegate to
     subagents, and merge or push?

   Propose canonical owners and the checkpoint location (existing records first;
   for a new project, one architecture record and one checkpoint) and let the
   user correct them. Waiting for answers pauses only the instruction, adapter,
   and checkpoint writes; independent already-authorized work continues.
3. **Write the setup.** Merge the
   [operating contract](assets/templates/operating-contract.md) into `AGENTS.md`,
   or into the project's existing canonical entry, preserving its rules, and fill
   its project setup block with the confirmed answers. For each other harness,
   add only a thin adapter that delivers the canonical file through that
   harness's supported import (for Claude Code, a `CLAUDE.md` containing
   `@AGENTS.md`); keep existing adapter content. When Superpowers runs
   alongside, check the installed Superpowers version's step names, then merge
   the [Superpowers binding](assets/templates/companion-superpowers.md); for any
   other companion, apply the rule in
   [Embed the operating loop](#embed-the-operating-loop). Create the
   [checkpoint](assets/templates/checkpoint.md). Bind commands that do not exist
   yet as unknown rather than inventing them. Record no authority the user did
   not grant.
4. **Verify and hand off.** Follow every new link and run the bound commands
   that exist. Record loader delivery only where the harness shows it; otherwise
   keep the explicit-read fallback and claim no autoload. Commit only as
   authorized. Setup does not complete adoption: continue with
   [Architecture](regenerative-architecture/SKILL.md) for a new project or
   [Adoption](regenerative-adoption/SKILL.md) for an existing one, unless the
   user asked for setup only.

### [S017] SKILL.md:148–176

## Embed the operating loop

Where edits are permitted, merge the
[operating contract](assets/templates/operating-contract.md) into the target
repository's real instruction entry point early, then refine it from actual work.
Actions for all seven primitives must be present: intent, compilation,
evaluations, provenance, pace, deletion, and compaction. Bind navigation and checks
to real product paths. Keep one canonical owner per rule and scoped guidance for
local boundaries. Preserve useful preexisting instructions.

When another process workflow runs alongside, such as Superpowers, keep one
owner per role. Its steps may own the design dialog, plan, execution, review, and
branch completion; this method keeps accepted intent, the frozen gate, evidence
claims, the checkpoint, and harvest. Name the binding in the canonical entry,
carry slice fields and gate commands into the companion's records, and harvest
records the companion deletes by design before they disappear. A companion
decision that changes accepted intent or acceptance semantics pauses only the
affected task and its dependents: harvest completed verified work, update the
checkpoint, and ask the existing decision owner about the consequential
unresolved change; independent authorized work continues. For Superpowers,
merge the [Superpowers binding](assets/templates/companion-superpowers.md).

Discover the intended harness's actual loading rules. Keep content/navigation,
loader observation, and ordinary fresh-session use as three separate checks.
Provide explicit read fallbacks when loading cannot be observed. Skill
installation alone does not establish ongoing adoption, schedule future agents,
or authorize unattended changes. Continue through the existing task/release
system; any automation must have explicit scope, ownership, and stop conditions.

### [S163] regenerative-adoption/SKILL.md:54–98

## Bind the method into everyday work

Find existing owners for purpose, architecture, contracts, evaluations, operations,
and current evidence. Reuse them. A small repository may need only a README
section, one decision note, existing tests, and a short checkpoint.

Merge the [operating contract](assets/operating-contract.md) into the canonical
session entry early. Preserve existing rules and make all seven primitives
actionable with real paths, checks, and constraints. Root guidance requires
applicable scoped reads; a scoped-only entry requires the root contract. Avoid
competing copies and pointer cycles. Harness adapters should deliver canonical
rules rather than duplicate them.

When another process workflow runs alongside, keep one owner per role: it may
own design dialog, plan, execution, review, and branch completion; this method
keeps accepted intent, the frozen gate, claims, checkpoint, and harvest. Record
the binding and the confirmed authority in the entry. A companion decision that
changes accepted intent or acceptance semantics pauses only the affected task
and its dependents: harvest completed verified work, update the checkpoint, and
ask the existing decision owner about the consequential unresolved change while
independent authorized work continues. For Superpowers, verify its installed
version's step names and merge the
[Superpowers binding](assets/companion-superpowers.md); for another workflow,
name the same roles explicitly. Harvest records a companion deletes by design.

Keep a small load map:

```text
entry directory / harness + version → delivered files → canonical rule owner
                                   → scoped read fallback → evidence or unknown
```

Validate three things separately:

1. **Content/navigation:** explicitly follow links and verify commands.
2. **Loader delivery:** inspect context or diagnostics in the named harness and
   root/subtree entry paths actually claimed.
3. **Fresh-session use:** give an ordinary task without telling the session which
   instructions to read; observe whether it finds the owner, applies the gate,
   preserves work, and harvests its result.

A manually supplied skill or Markdown link proves neither autoload nor repeated
future adoption. If instruction edits are unavailable, retain a permitted local
record and explicit read prompt, with the narrower claim.

## Wie verhindern wir plausible, aber falsche Agenten-Änderungen?

### [S189] regenerative-reconstruction/SKILL.md:34–60

## Freeze a surviving knowledge pack

Adapt the [survival manifest](assets/survival-pack.md). Classify:

1. Removed implementation: source, private helpers, compiled copies, bundles,
   source maps, cached/installed implementations, and runtime artifacts.
2. Surviving knowledge: accepted intent/delta, public and neighbor contracts,
   state formats, independent cases/oracles, examples, and reasons.
3. Execution support: recipes, adapters, generators, configuration, fixtures,
   setup/cleanup, and evaluation commands.
4. Declared dependencies: retained libraries, neighboring capabilities, services,
   contribution to the behavior, and exclusions from the claim.
5. Access and identity: frozen versions, allowed implementer/evaluator inputs,
   actual environment, and candidate-resolution checks.

Validate that a substitute can build and be judged without importing removed
code. Colocated tests can survive only when explicitly retained and independent.
A surviving helper that still implements the capability narrows the claim or
belongs in the removal scope. Preserve genuine contract algorithms; a renamed
source dump is not extracted intent.

For reconstruction, use a genuinely fresh context supplied only the allowlisted
pack and declared dependencies. Exclude old source in history, caches, previous
conversation, installed packages, bundles, and transcripts. A request to ignore
readable source is weaker than input separation; report actual access limits.
Path scans alone are not a sandbox. Delegate only when separately authorized.

### [S105] REGENERATIVE-SOFTWARE.md:1352–1367

### 15.2 Manifest the survival pack

Distinguish actual paths or versioned references for:

1. **Removed implementation:** source, private helpers, bundles, compiled copies, and runtime artifacts within the replacement unit.
2. **Surviving knowledge:** accepted intent/delta, public and neighbor contracts, state formats, independent cases/oracles, examples, and rationale.
3. **Surviving execution support:** harness/adapters, recipes, generators, configuration, fixtures, dependency identities, setup and cleanup.
4. **Declared dependencies:** retained libraries, neighbors, services, or substitutes; their contribution and the claim's exclusions.
5. **Access and identity:** what implementer/evaluator may access, frozen versions, environment, and candidate-resolution checks.

Verify that the pack builds and evaluates a substitute without importing the removed tree. Tests colocated with old source can survive when explicitly retained and independent. A contract generator inside the removed unit needs a surviving authoritative output or independent generator. If a retained helper still implements the capability, include it in removal scope or narrow the claim.

Freeze the consumed manifest separately from the broad preservation snapshot. Retained run outputs are not immutable input declarations. Accepted knowledge changes between attempts require new manifests and recorded transitions, leaving history intact.

For reconstruction, prefer an allowlisted export into a fresh context over instructions to ignore readable source. Exclude old implementations in history, caches, installed packages, bundles, source maps, prior session context, and transcripts. Required algorithms and domain rules can be genuine contract knowledge; a relabeled source dump does not test extraction. Record actual access limits and exceptions. Path scans alone are not a sandbox.

### [S186] regenerative-reconstruction/SKILL.md:1–8

---
name: regenerative-reconstruction
description: "Exercise implementation replaceability through isolated substitution or fresh-context reconstruction. Use for regenerative survival packs, deletion rehearsals, independent replacements, or claims that another agent can rebuild a unit from retained intent, contracts, state rules, and evaluations. Distinguish source-assisted replacement from pack-only reconstruction."
metadata:
  version: "0.2.0"
  playbook-version: "3.0.1"
---

### [S166] regenerative-evaluations/SKILL.md:1–8

---
name: regenerative-evaluations
description: "Build meaningful behavioral evaluations that survive implementation changes. Use for regenerative acceptance gates, independent oracles, contract and consumer tests, async lifecycle checks, evaluation failure diagnosis, or runtime model and agent quality assessment. Separate product correctness from test machinery validity and probabilistic quality from hard constraints."
metadata:
  version: "0.2.0"
  playbook-version: "3.0.1"
---

### [S018] SKILL.md:177–195

## Make claims match evidence

- **Verified:** the defined improvement passed all applicable required checks on
  the final candidate, with durable knowledge and retrievable evidence.
- **Replacement-demonstrated:** an alternate implementation passed the surviving
  gate with the old runtime unavailable and no required consumer change.
- **Reconstruction-demonstrated:** additionally, a fresh implementer used only a
  frozen survival pack and declared dependencies. Reading old source disqualifies
  that attempt from the additional reconstruction claim.
- **Operationally-observed:** an identified deployment met a representative runtime
  observation policy. Local tests do not establish this.
- **Retired-and-compacted:** the named path and eligible temporary machinery were
  removed after consumer, state, and recovery obligations were satisfied.
- **Cheaper future change:** measured on a real subsequent requested change;
  otherwise keep the benefit as a hypothesis.

Mark unestablished claims `not-attempted`, `blocked`, `failed`, or `inconclusive`;
mark evidence stale when relevant inputs change. Do not use a regenerative score.

### [S064] REGENERATIVE-SOFTWARE.md:683–711

### 9.1 Separate the oracle from the implementation adapter

An evaluation is an executable claim about an obligation that remains meaningful across implementations. A public-function unit test can qualify; an HTTP test tied to accidental internals may not. Preserve useful implementation-specific tests too.

```text
versioned cases / properties / workload
                  ↓
public-boundary driver or implementation adapter
                  ↓
raw outputs + observable state + attempted effects + measurements
                  ↓
independent oracle + frozen acceptance policy
```

Adapters may handle launch details, transport, and implementation-specific scheduling. They MUST NOT fabricate expected output, swallow failures, discard inconvenient events, or silently change semantics. Version their bytes, bindings, assumptions, and limits alongside the oracle. A replacement with another valid schedule may need another adapter under the same public value/state obligations.

Name the actual evidence boundary, not merely the deepest real dependency:

| Boundary exercised | What it establishes | What it does not establish by itself |
|---|---|---|
| Source/structural inspection | Declared shape, wiring, plausible mechanism | Executed behavior |
| Real query/request builder through recording transport | Actual predicates, scope, and requests at that seam | Database execution, planner semantics, returned data, live isolation |
| Extracted actual callback with controlled bindings | That expression under the simulated state/schedule | Framework lifecycle, user interaction, replacement-independent behavior |
| Real route/auth context and disposable store with test driver | Route, authority, storage, and driver's protocol | Product UI orchestration |
| Actual UI journey | Interaction, lifecycle, selected state, reload in that environment | Production parity or external-service quality |
| Identified deployment under representative traffic | Named operational claims and observed population | Untested consumers, workloads, or future correctness |

For source-extracted probes, retain original expression identity, fail on ambiguous extraction or unbound dependencies, and distinguish simulated transitions from product-executed ones. A driver-imposed queue cannot prove the product queues work. Bind immutable request snapshots at the real creation point, not from later mutable state. These probes can expose a defect but are not surviving reconstruction gates.

### [S137] REGENERATIVE-SOFTWARE.md:1789–1817

### 22.2 Match the completion claim to its evidence

To call a slice **verified**, it MUST have a defined objective, justified changes, relevant durable knowledge and documentation, all applicable required checks satisfied on the final integrated candidate, and retrievable evidence. Name the change type and the stage qualified. An evaluation improvement may be verified while the product defect it reveals remains explicitly failed.

Additional claims require additional evidence:

| Claim | Required basis |
|---|---|
| `replacement-demonstrated` | Surviving intent/target/oracle, identified alternate implementation, supported consumers and relevant state/effects preserved, no required consumer change, old runtime implementation unavailable, valid substitution gate |
| `reconstruction-demonstrated` | All substitution evidence plus actual fresh-context, survival-pack-only reconstruction inputs |
| `operationally-observed` | Identified deployed artifact/environment and representative runtime evidence meeting the observation policy |
| `retired-and-compacted` | Named obsolete runtime path and eligible temporary machinery removed, with consumer/state/recovery obligations accounted for and removal verified |
| Improved future-change cost | A real subsequent change and scoped cost observations; otherwise retain it as a hypothesis |

These are scoped demonstrations, not exhaustive correctness guarantees. Preserve statuses and evidence for unresolved work rather than using “not applicable” to hide an unperformed stage.

Before closure, check:

- Objective, scope, benefit, preserved promises, and accepted deltas are explicit.
- All seven primitives have proportionate decisions/evidence; required session rules are usable to the extent claimed.
- Canonical knowledge survives the claimed removal scope and identifies consumers, state, effects, and important journeys.
- Oracles have justified authority; controls reached intended assertions; no gate was lowered to fit the candidate.
- Required selection, input identities, execution outcomes, runtime error channels, retention, and cleanup reconcile for the integrated claim.
- State compatibility, recovery, release, observation, and retirement are evidenced where claimed.
- Final on-disk guidance and current pointers agree with authoritative receipts, including failures and corrections.
- Remaining locally actionable work, actual blockers, owners, and next success criteria are explicit.

A conditional review is satisfied only after its stated supplements/checks are actually supplied and bound in the final record. Do not manufacture tests, rewrites, or unused paperwork to fill this list.

### [S167] regenerative-evaluations/SKILL.md:9–21

# Evaluate promises independently

Read [evaluation rules](references/playbook-09.md) before designing the gate.
Use [pace](references/playbook-08.md) for consequence-based depth,
[probabilistic behavior](references/playbook-10.md) only when the product runtime
is probabilistic, [templates](references/playbook-19.md) for full records,
[the streaming example](references/playbook-20.md) for multi-boundary cases, and
[failure modes](references/playbook-21.md) for diagnosis.

Follow repository rules, preserve unrelated work, and use its existing runners.
Choose checks for important promises and plausible failures; avoid tests that
merely repeat a reversible low-impact edit.

### [S168] regenerative-evaluations/SKILL.md:22–44

## Freeze an honest gate

1. Name stable obligations, supported consumers, accepted deltas, stage, and actual
   evidence boundary. Distinguish source inspection, helper probes, real transport,
   store integration, UI journeys, and representative production observation.
2. Justify expected results from accepted intent, independent examples, domain
   properties, or supported consumer contracts. The old implementation is a
   differential reference, not sole authority. Candidate decision logic cannot
   supply its own expected answers without an independent check.
3. Separate cases/workload and oracle from the adapter that launches or drives
   implementations. Adapters must preserve failures and observations; they cannot
   fabricate outputs or normalize away a promised difference.
4. Record exact required selection, comparison policy, invocation, environment,
   baseline, candidate and gate identities, retention, and limitations. Use the
   [evaluation template](assets/evaluation.md) within existing records.
   Retain retrievable gate bytes before edits. Track preserved, added and
   corrected checks separately; a baseline for an earlier selection cannot
   establish rejection of later additions.
5. Include positive progress and healthy controls as well as forbidden outcomes.
   Demonstrate sensitivity to an important plausible violation in an isolated
   fixture. A behavioral mutant must load and reach the intended assertion;
   an import/setup crash establishes something narrower.

### [S187] regenerative-reconstruction/SKILL.md:9–20

# Earn a scoped reconstruction claim

Read [replacement and reconstruction](references/playbook-15.md) fully before an
experiment. Use [target and economics](references/playbook-02.md),
[independent gates](references/playbook-09.md), [state](references/playbook-13.md),
[templates](references/playbook-19.md), and [claim criteria](references/playbook-22.md)
as needed for its prerequisites and conclusion.

Follow repository instructions and actual authority. Keep the working baseline
and other writers' changes intact. Do not delete shared source to demonstrate
replaceability; use an isolated allowlisted export and owned mutable resources.

### [S190] regenerative-reconstruction/SKILL.md:61–83

## Execute with the frozen gate

1. Establish or legitimately inherit a reference run and accepted differences.
2. Show healthy behavior and meaningful violation detection. Distinguish absence
   wiring failure from a loaded mutant reaching the behavioral assertion.
3. Record source-assisted or fresh pack-only context before generation.
4. Produce a coherent substitute; retain questions and missing-knowledge requests.
5. Make old runtime code unavailable in the owned environment, identify actual
   loaded/transitive paths, and evaluate unchanged supported consumers, relevant
   state/effects, and affected journeys against the independent gate.
6. Retain candidate source, pack, input and gate identities, commands, failures,
   observations, cleanup, and conclusion. Use a
   [receipt](assets/receipt.json) or existing equivalent.
7. Recover the owned environment unless an authorized adoption path proceeds.
8. Harvest gaps at their canonical owner and keep a [slice record](assets/slice.md).
   Repeat only for a newly resolved obstacle or justified new experiment.

If solving a question requires old source, the attempt becomes source-assisted.
Repair the pack and use a new fresh attempt to test it. If consumers must change,
report migration, not replacement across an unchanged boundary. An evaluated
compatibility adapter can belong to the replacement unit; account for its state,
effects, lifecycle, and any temporary exit condition.

## Wie führen wir diese Arbeitsweise ohne Papierflut und Rewrite-Programm ein?

### [S016] SKILL.md:120–147

## Execute a complete slice

1. **Choose:** name outcome, boundary, why now, and a falsifiable benefit hypothesis.
   Compare a patch, seam repair, replacement, architecture migration, and retention.
2. **Understand:** trace actor → entry → authority → orchestration → state →
   dependencies → visible result → failure/recovery. Find actual consumers and
   writers, not just imports. Label accepted, observed, proposed, and demonstrated
   knowledge separately.
3. **Specify:** preserve stable obligation IDs, accepted behavior deltas, ownership,
   freedoms, justified oracle, exact required checks, baseline, and recovery needs.
   Freeze the gate before judging the candidate. Resolve consequential unknowns;
   continue independent work while a decision or environment is unavailable.
4. **Change:** implement the smallest complete useful change, including affected
   consumers, state, and documentation. Keep candidate changes separate from
   changes to acceptance semantics. A corrected gate may justify retaining code.
5. **Verify:** identify the artifact actually exercised. Run applicable required
   checks and affected journeys on the integrated candidate. Missing, skipped,
   invalid, or inconclusive required evidence is not passing. Diagnose product,
   oracle, adapter, environment, and reporting failures separately.
6. **Harvest:** update canonical knowledge and owning instructions; retain reasons,
   actual commands/results, limitations, and recovery/retirement conditions. Remove
   eligible temporary complexity. Reconcile the checkpoint and continue the next
   in-scope slice.

Use the [minimum slice template](assets/templates/slice.md) in an existing record.
It answers why, promises, boundary, verification, result, and next action. Add
only the information required by the selected consequence and claim.

### [S194] regenerative-evolution/SKILL.md:22–44

## Advance the next useful slice

1. Reconcile requested outcome, mode, capability inventory, current evidence, and
   ownership. Choose a bounded useful change and why it earns its cost.
2. Resolve preserved intent and acceptance delta, architecture/consumer impact,
   state compatibility, justified oracle, and required selection.
3. Establish the baseline and freeze a gate before judging the candidate. Implement
   the smallest justified change or retain correct code under an improved gate.
4. Verify structural properties and integrated behavior on the actual candidate.
   Diagnose failures as product, intent, boundary, machinery, environment, or
   budget issues. Do not weaken acceptance to complete the pipeline.
5. Introduce only under the existing release process and actual authority. Identify
   the tested artifact and compatible recovery inputs. Define success/recovery
   signals and representative volume before exposure.
6. Observe where authorized and available; harvest evidence into canonical intent,
   evaluations, rationale, documentation, and operating instructions. Continue
   through the requested campaign rather than repeatedly polishing a leaf pilot.

Use a [slice record](assets/slice.md) for local work and the
[campaign inventory](assets/campaign.md) for broader scope. Track each capability's
actual stage and disposition separately. Missing live evidence does not excuse
missing deterministic checks that can run locally.

### [S047] REGENERATIVE-SOFTWARE.md:462–471

### 5.5 Select a valuable first slice

Prefer a meaningful leaf capability or recently changed unit with clear value, observable behavior, a usable environment, natural ownership, bounded consumers, and recoverable effects. Fewest lines is a poor selection rule: a tiny serializer can define every stored session.

Name a likely follow-up change to test the proposed seam's usefulness. If no unit is ready, choose an enabling slice: capture an incident regression, formalize a protocol, introduce narrow ownership, or build a real integration fixture.

**Discovery exit:** a product map sufficient for the slice, a baseline, a boundary/state hypothesis, concrete unknowns, and a reasoned selection. Complete product archaeology is not required before useful local work.

---

### [S133] REGENERATIVE-SOFTWARE.md:1737–1744

### 20.6 Test the next useful change

Suppose the next requested feature adds an optional progress event between visible completion and auxiliary state. Confirm the extension policy and old-client behavior first. Update the acceptance delta and examples, implement the bounded change, and extend the gate while retaining late-state persistence checks.

Measure whether unrelated persistence/server-state internals needed changes and whether the packet supplied the knowledge. If the work fits the predicted seam, that supports the benefit hypothesis. If not, revise the seam or hypothesis. The original successful replacement alone could not establish cheaper future evolution.

---

### [S137] REGENERATIVE-SOFTWARE.md:1789–1817

### 22.2 Match the completion claim to its evidence

To call a slice **verified**, it MUST have a defined objective, justified changes, relevant durable knowledge and documentation, all applicable required checks satisfied on the final integrated candidate, and retrievable evidence. Name the change type and the stage qualified. An evaluation improvement may be verified while the product defect it reveals remains explicitly failed.

Additional claims require additional evidence:

| Claim | Required basis |
|---|---|
| `replacement-demonstrated` | Surviving intent/target/oracle, identified alternate implementation, supported consumers and relevant state/effects preserved, no required consumer change, old runtime implementation unavailable, valid substitution gate |
| `reconstruction-demonstrated` | All substitution evidence plus actual fresh-context, survival-pack-only reconstruction inputs |
| `operationally-observed` | Identified deployed artifact/environment and representative runtime evidence meeting the observation policy |
| `retired-and-compacted` | Named obsolete runtime path and eligible temporary machinery removed, with consumer/state/recovery obligations accounted for and removal verified |
| Improved future-change cost | A real subsequent change and scoped cost observations; otherwise retain it as a hypothesis |

These are scoped demonstrations, not exhaustive correctness guarantees. Preserve statuses and evidence for unresolved work rather than using “not applicable” to hide an unperformed stage.

Before closure, check:

- Objective, scope, benefit, preserved promises, and accepted deltas are explicit.
- All seven primitives have proportionate decisions/evidence; required session rules are usable to the extent claimed.
- Canonical knowledge survives the claimed removal scope and identifies consumers, state, effects, and important journeys.
- Oracles have justified authority; controls reached intended assertions; no gate was lowered to fit the candidate.
- Required selection, input identities, execution outcomes, runtime error channels, retention, and cleanup reconcile for the integrated claim.
- State compatibility, recovery, release, observation, and retirement are evidenced where claimed.
- Final on-disk guidance and current pointers agree with authoritative receipts, including failures and corrections.
- Remaining locally actionable work, actual blockers, owners, and next success criteria are explicit.

A conditional review is satisfied only after its stated supplements/checks are actually supplied and bound in the final record. Do not manufacture tests, rewrites, or unused paperwork to fill this list.

### [S029] REGENERATIVE-SOFTWARE.md:199–226

### 2.4 Invest where it improves useful change

Protect knowledge before removing its container. Make correctness external to the candidate. Preserve state separately from code. Treat boundary changes as architectural decisions. Exercise replaceability rather than inferring it from diagrams, and pair introduction with retirement.

The relevant cost is:

```text
knowledge recovery + boundary work + implementation + evaluation
+ migration + observation + retirement + ongoing knowledge/tooling upkeep
```

Cheap generation changes one term. Prioritize frequent or costly changes, fragile integrations, and consequential unknowns. Stable, low-stakes code can remain ordinary maintained code. Some strong coupling intentionally protects an invariant; a consistent ledger may belong in one replacement unit.

Before an architectural investment, write a falsifiable hypothesis: **which likely change becomes easier, which obstacle disappears, and what observation would support the claim?** Use actual backlog work, incidents, or recent changes. Compare with a normal patch or deliberate retention. Estimates can select a pilot; label them separately from measured savings.

| Evidence | Useful operation |
|---|---|
| Local defect understood; boundary sound | Patch and preserve the lesson |
| Useful boundary obscured by implementation | Refactor enough to expose the seam |
| Strong intent and oracle; costly or unsuitable implementation | Compare a replacement behind the boundary |
| Ownership or communication no longer fits | Deliberate architecture change with migration |
| Behavior or consumers poorly understood | Observe, characterize, and extract knowledge first |
| Full cost exceeds likely benefit | Retain; record a revisit trigger if useful |

Reassess scope when a repair introduces a new intermediary, state owner, dependency, or long-lived resource. Successive failures that reveal a new protocol or lifecycle call for revisiting the target, not an indefinite chain of local patches. Demonstrate a useful local cycle before building a regeneration platform.

---

### [S131] REGENERATIVE-SOFTWARE.md:1723–1730

### 20.4 Change, verify, and preserve the evidence

Repair the contradictory contract and examples, then freeze the gate. Use a patch if it solves the issue coherently; replace the reader only if the lifecycle or maintenance cost justifies it. Run preserved obligations plus the accepted delta, and inspect every difference.

Exercise a real service-to-application journey: stream, acknowledge persistence, consume retained state without a repairing re-fetch where relevant, reload, and verify continuity. Retain commands, actual loaded artifacts, raw safe observations, execution status, and product verdict. A driver failure should be repaired as evaluation machinery, not by changing correct product semantics.

Update SDK examples and agent instructions, verify the supported integration workflow, and name remaining external-client or production uncertainty.

### [S024] REGENERATIVE-SOFTWARE.md:111–125

### 1.3 Execute the next useful action

For each slice:

1. **Choose:** name the product outcome, boundary, and reason to invest. Keeping the implementation is a legitimate choice.
2. **Understand:** trace the affected journey, consumers, state, and checks; resolve the uncertainties this slice depends on.
3. **Specify:** record preserved promises and intentional changes; identify the oracle, required checks, baseline, and recovery needs before judging a candidate.
4. **Change:** implement the smallest complete patch, seam repair, replacement, migration, or knowledge improvement, including affected consumers and documentation.
5. **Verify:** evaluate the identified integrated candidate and affected journeys. Diagnose failure rather than lowering the gate.
6. **Harvest:** retain reasons and evidence, remove justified temporary complexity, update the owning instructions and packet, state the exact outcome, and continue to the next in-scope slice.

The minimum packet answers **why, what must hold, where change belongs, how to verify, what happened, and what comes next**. Existing documents and tests can supply most of it. Use the six-line template in Section 19.1.

Add an evaluation for an important uncovered promise, not merely to mirror a reversible, low-impact edit. If a corrected gate accepts the unchanged implementation, preserve that implementation and record the verified evaluation or knowledge improvement.

### [S121] REGENERATIVE-SOFTWARE.md:1521–1533

### 19.1 Minimum slice record

```text
Why: <objective, mode, scope, expected benefit, completion criterion>
Promises: <canonical obligations, preserved behavior, accepted delta>
Boundary: <unit, state/effect owners, consumers, permitted changes>
Verify: <asserting cases/oracles, required stage, baseline, exact commands/environment>
Result: <candidate/gate identities, execution and product verdicts, evidence, limits>
Next: <current stage, exact action, prerequisite/decision, retirement condition>
```

Beside this packet or in the engagement record, identify current revision/working snapshot, applicable instructions, budgets, ownership, and the canonical index. A campaign adds capability dispositions; adoption adds instruction load/behavior evidence; replacement adds the survival manifest. Six lines are a navigation aid, not a limit on necessary evidence.

### [S013] SKILL.md:15–51

## Begin

1. Read [REGENERATIVE-SOFTWARE.md](REGENERATIVE-SOFTWARE.md) completely on initial
   adoption, continuing beyond truncated output. It is the foundation. On resume,
   reconcile its version, the checkpoint, and changed inputs; reread affected
   sections rather than repeating product discovery.
2. Follow the engagement's instruction hierarchy and repository rules. Inspect
   staged, unstaged, untracked, generated, and externally managed work. Preserve
   other writers' changes and use existing commands and canonical knowledge.
3. If the project has neither a usable regenerative operating contract nor a
   current checkpoint, or the user asks for setup, run
   [Set up a project](#set-up-a-project) first. If the user declines, continue
   the requested work and state that the project remains unconfigured. In
   report-only `assess`, offer setup and record that the project remains
   unconfigured instead of writing instructions uninvited.
4. State mode, scope, environment, intended evidence claim, and the next useful
   outcome. Default to `translate`: discover, implement justified improvements,
   and verify locally. Without a wider objective, choose one valuable capability.
5. For an empty repository, use the architecture workflow below to establish
   intent and a working vertical slice. Do not invent a historical baseline.
6. For a repository-wide objective, inventory capabilities and important journeys,
   prioritize slices, and continue through the requested scope. Give every
   capability an evidenced disposition; a pilot does not complete the campaign.

| Mode | Finish with |
| --- | --- |
| `translate` | Verified product or enabling improvement and durable knowledge |
| `assess` | Evidence-backed findings, boundaries, obstacles, prioritized next work |
| `regenerate <unit>` | Evaluated candidate behind an explicit, ready boundary |
| `rehearse <unit>` | Isolated reconstruction experiment with honest context records |
| `compact <scope>` | Verified removal/consolidation of eligible complexity |
| `setup` | Confirmed setup answers, bound entry instructions and adapters, checkpoint, next action |

New-project work is a `translate` starting condition, not an excuse to skip
implementation when the user asked for a build. An architecture-only request may
finish in `assess` with a concrete design and implementation handoff.

### [S018] SKILL.md:177–195

## Make claims match evidence

- **Verified:** the defined improvement passed all applicable required checks on
  the final candidate, with durable knowledge and retrievable evidence.
- **Replacement-demonstrated:** an alternate implementation passed the surviving
  gate with the old runtime unavailable and no required consumer change.
- **Reconstruction-demonstrated:** additionally, a fresh implementer used only a
  frozen survival pack and declared dependencies. Reading old source disqualifies
  that attempt from the additional reconstruction claim.
- **Operationally-observed:** an identified deployment met a representative runtime
  observation policy. Local tests do not establish this.
- **Retired-and-compacted:** the named path and eligible temporary machinery were
  removed after consumer, state, and recovery obligations were satisfied.
- **Cheaper future change:** measured on a real subsequent requested change;
  otherwise keep the benefit as a hypothesis.

Mark unestablished claims `not-attempted`, `blocked`, `failed`, or `inconclusive`;
mark evidence stale when relevant inputs change. Do not use a regenerative score.