Repository links may require access. Source inspection is separate from a clean public-package installation.
AN INTERACTIVE READING MAP
Get the shape of this guide.
Move through the ideas, inspect their relationships, or make a focused reading path. The complete guide stays below.
⌘↗
READING SEQUENCEUnderstand how the ideas connect
Choose a point to look closer ↓
01 / Guide section
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.
Read the supporting context ＋
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.
Explore a section, then continue with the complete article below.
1 / 4
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.
↳A change has an owner and a set of consequences.Trace the mechanism · 3 ways to look closer＋
A report export now needs a reason. Follow the change through authored meaning, derived output and a caller that still uses the old input.
Which part are you changing?
A CONCRETE SITUATION
The requirement becomes part of declared behavior.
A required reason is added to the operation input.
01 / Author
Change the declaration that owns the required input.
What changes
Callers must now supply the new field for that contract version.
What stays explicit
The handler still decides how the reason affects the business work.
FOLLOW THE CONSEQUENCE
Plan compatibility for existing consumers. A required input can be a behavioral break even if the handler’s main implementation is unchanged.
Inspect the walkthroughBehavior · proof and limits · source checks＋
Follow the source behavior
A fixture release removes billing.invoices.createLegacy and identifies two affected consumer files. The reference separates impact analysis, migration, and independent verification, then produces governed patch and draft-PR evidence without contacting GitHub.
Compile the application
The source compiles the release-steward filesystem application and inspects required approvals for patching, draft PR creation, and selected delegation tools.
Inspect the migration scope
The fixture calculates an immutable source digest and identifies the affected billing files. Subagent evidence records permitted tools and denied effects, including auto-merge.
Bind approval and apply once
Tests assert that approval is bound to migration digests, changed material invalidates it, and the patch invocation occurs once even when replayed.
Read the remaining qualification
The fixture's PR URL is under github.example.test, its PR is a draft, and autoMerge is false. Adapter and deployment composition results explicitly remain candidate with unresolved live requirements.
What this example establishes＋
Source demonstrates
The inspected source asserts separate subagent authority and digest-bound approval.
Tests assert one application invocation, replay evidence, a draft result, and no auto-merge.
Candidate readiness retains unresolved requirements for exact live environments.
Does not demonstrate
A real patch applied to a user's repository or an actual GitHub PR.
Successful CI in a production repository; this fixture reports deterministic CI evidence.
Production isolation or deployment qualification merely because a topology composes.
Look inside the guideOpening context · complete reading path＋
Give each test one question
An operation has several boundaries, and one green check cannot answer every question about them. Separate declaration validity, business behavior, adapter behavior and external consumption so failures tell you where to look.
Look inside the guideOpening context · complete reading path＋
Know which version you mean
A contract's version identifies a particular declared behavior. A package version identifies a distribution artifact. A website or application revision identifies a deployment. Those numbers can change independently.
Look inside the guideOpening context · complete reading path＋
Choose the reference that answers your question
Guides explain how to accomplish a task; reference records explain a particular surface. Start with the layer that owns your question so a package catalogue does not become your learning path.
