# Generation and drift: what changes, what does not

Use derived artifacts deliberately and understand the current boundary of generation plans and apply.

Source context: Source-guided
Source: https://github.com/lssm-tech/contractspec/blob/d58fa5b7de53a947811e5cc68346be028ce18528/packages/bundles/workspace/src/cli/commands/generate/index.ts

## Separate authored behavior from derived artifacts

Keep the contract and the business implementation distinct from files produced by tooling. Review the source that owns a change, then regenerate the affected output instead of patching a derived file as the permanent fix.

At the inspected snapshot, the plain generate command calls the artifact service to create documentation and supported materialized targets. This is narrower than generating and deploying an entire correct application.

## Understand the current command boundary

The source exposes separate generation, planning and apply paths. Their names do not imply equal maturity: the plan currently contains no write actions, and non-dry-run apply is deliberately refused.

| Source command | Observed implementation | How to use the result |
| --- | --- | --- |
| contractspec generate | Generates docs and supported materialized artifacts | Review the actual derived diff |
| contractspec generate plan | Builds a dry-run artifact with an empty actions list | Inspect its diagnostics; do not interpret zero actions as complete semantic analysis |
| contractspec generate apply --dry-run | Returns the current dry-run plan with zero writes | Preview only |
| contractspec generate apply | Refuses writes with exit code 3 | Do not present as a shipping write workflow |

## Read an artifact drift result correctly

The drift service generates expected artifacts in a temporary directory and compares them with the selected generated directory. It can identify missing, extra or changed files.

This answers whether the derived output matches the current source and generator. It does not prove that a handwritten handler implements every business rule or that a migration is safe for production data.

## Use a small review loop

Change one contract, regenerate only the relevant derived surface through the supported workflow, inspect the diff and run the owning checks. If the diff is unexpectedly large, first verify the source version, configuration and generator version.

Keep a deterministic example with the docs so a future release can reproduce the result. Broader reviewed repair or apply workflows should be described with their actual status until the write path is implemented and qualified.

## Related examples

- [Review an agent's migration proposal](https://lssm.co/examples/release-steward/): Follow a deterministic release migration through scoped subagents, digest-bound approval, and a draft PR receipt.