git:20260405.2f8d9a2 to git:20260423.b0aeb97

25 added, 194 removed. Audit A to A.

---

name: development-contract-system

description: Build a portable change-contract system for any repository. Use when creating or porting a repository workflow based on tracked feature records, lifecycle directories, a policy file, a checker, a lifecycle transition helper, and aligned docs/tests.

---

# Development Contract System

Use this skill when a repository needs a deterministic, reviewable workflow for

tracking substantive work through repo-owned feature records instead of ad hoc

notes.

This skill is self-contained on purpose so it can be moved into another repo or

skill collection without depending on the smaller contract skills from this

frame at runtime.

When the target repo already uses local skills, also generate a thin repo-local

process overlay that applies `development-contract-process` against the repo's

concrete policy path and helper commands.

## What this skill builds

A complete repository-local contract system with these parts:

- a repo-owned policy file

- a `feature_records/` directory with lifecycle subdirectories

- a Markdown template for new records

- a root `feature_records/README.md`

- a checker script that validates record structure and changed-path coverage

- a lifecycle transition helper script

- direct shell tests for the checker and lifecycle helper

- repo docs that explain how maintainers should use the system

- optionally, a repo-local process overlay skill that points at the concrete

policy file, checker command, helper command, and validation profiles

Recommended default layout:

```text

config/change-contract-policy.sh

feature_records/

README.md

TEMPLATE.md

planned/

active/

done/

superseded/

scripts/check-change-contracts.sh

scripts/set-feature-record-lifecycle.sh

scripts/test-change-contracts.sh

scripts/test-feature-record-lifecycle.sh

```

+ Detailed policy fields, feature-record template sections, checker behavior,

+ helper behavior, test cases, and docs examples live in

+ [references/contract-system-implementation-details.md](references/contract-system-implementation-details.md).

## Use this skill when

- a repo needs tracked change contracts for substantive work

- maintainers need to see what is active, planned, done, or superseded at a glance

- the team wants explicit implementation and verification evidence

- the repo should remain deterministic even if agent-specific folders disappear

- you are porting this workflow from one repo to another

## Do not use this skill when

- the repo only needs a simple issue tracker or TODO list

- the team does not want repo-tracked process artifacts

- there is no appetite for maintaining a checker and template contract

## Core outcome

After this skill is applied, the repository should support this flow:

1. Substantive work requires a feature record update.

2. Feature records live under lifecycle folders:

`planned/`, `active/`, `done/`, `superseded/`.

3. The record's folder must match its `## Lifecycle` `State`.

4. A checker validates structure, ownership, evidence, and lifecycle placement.

5. A helper script moves records between lifecycle folders and updates the

lifecycle fields deterministically.

6. Repo docs explain the system clearly enough for maintainers who never use an

AI assistant.

## Build order

Implement in this order to avoid drift:

1. Discover the repo's real substantive-change surface.

2. Create the repo-owned policy file.

3. Create the `feature_records/` tree and template.

4. Implement the checker against the policy file.

5. Add lifecycle example records or seed records.

6. Add the lifecycle transition helper.

7. Add shell tests for the checker and helper.

8. If the repo uses local skills, add a thin repo-local process overlay that applies the portable process skill to the concrete repo policy.

9. Update README, AGENTS-style docs, and release/hygiene docs.

10. Run the checker and hygiene lanes and fix drift.

## Phase 1: Ground in the repo

Before adding anything:

- read the repo's main README and agent or maintainer guidance if present

- identify the directories and top-level files that count as substantive

- identify existing validation commands

- identify whether the repo already has a tracked plans folder or release

checklist

- identify whether the repo is CMake-first, Makefile-based, Cargo-based, npm,

or another ecosystem so command examples fit the repo

Do not guess substantive paths if the repo already has clear boundaries in docs,

workflows, or layout.

- ## Phase 2: Create the policy file

- Create one repo-owned policy file in a neutral location such as:

- - `config/change-contract-policy.sh`

- - `repo_meta/change-contract-policy.sh`

- Do not place it under `.agents/` if repo scripts, CI, or humans depend on it.

- The policy file should declare:

- - plan directory

- - template basename

- - substantive path patterns

- - substantive top-level files

- - required section headings

- - allowed lifecycle values

- - allowed uncertainty/cost values

- - allowed evidence statuses

- - allowed yes/no values when evidence entries track impact

- - allowed implementation/verification status values when ownership notes are enforced

- - evidence lane names

- - checker command

- - named validation profiles

- Good default values:

- - plan directory: `feature_records`

- - template basename: `TEMPLATE.md`

- - lifecycle values: `planned`, `active`, `superseded`, `done`

- - evidence lanes: `Tests`, `Docs`, `Analyzers`, `Install validation`,

- `Release hygiene`

- ## Phase 3: Create `feature_records/`

- Create this structure:

- ```text

- feature_records/

- README.md

- TEMPLATE.md

- planned/

- active/

- done/

- superseded/

- .gitignore

- ```

- The root `README.md` should explain:

- - what the directory is for

- - what each lifecycle folder means

- - that folder and lifecycle state must match

- - that `superseded/` records must set `Superseded by`

- - how to use the lifecycle transition helper

- The template should require sections similar to:

- - `Motivation`

- - `Proposed Behavior`

- - `Lifecycle`

- - `Contract`

- - `Uncertainty And Cost`

- - `Responsibilities`

- - `Evidence Matrix`

- - `Implementation Notes`

- - `Verification Notes`

- - `Waivers`

- - `Files to Add/Modify`

- - `Testing Strategy`

- The template should say that records belong in the lifecycle folder matching

- their `State`.

- The `.gitignore` should:

- - ignore everything by default

- - keep `.gitignore`, `README.md`, and `TEMPLATE.md`

- - keep lifecycle directories

- - keep Markdown files inside lifecycle directories

- ## Phase 4: Implement the checker

- Create a repo-owned checker script, typically

- `scripts/check-change-contracts.sh`.

- The checker should:

- - load the policy file

- - detect changed files from:

- - an explicit env var override

- - a git diff range when available

- - local modified/untracked files otherwise

- - decide whether a substantive repo-owned change occurred

- - fail if substantive changes exist without a non-template feature record update

- - scan feature records recursively under `feature_records/*/*.md`

- - ignore `feature_records/README.md` and `feature_records/TEMPLATE.md`

- - validate required sections

- - validate lifecycle fields

- - validate evidence lanes and allowed statuses

- - validate implementation owner versus responsibilities implementer

- - validate verification owner versus responsibilities verifier

- - validate self-validation and waiver rules

- - validate that the parent lifecycle directory matches the `Lifecycle` state

- - require `Superseded by` when the state is `superseded`

- Prefer a lightweight shell checker with `awk` if the repo already uses shell for

- workflow enforcement. If the repo is strongly standardized on another scripting

- language, it is acceptable to implement the checker in that language instead.

- ## Phase 5: Add lifecycle examples

- Seed the system with at least one valid example record in each lifecycle folder:

- - one `planned`

- - one `active`

- - one `done`

- - one `superseded`

- The `superseded` example must point to a real replacement record.

- These examples make the workflow browseable immediately and help humans

- understand the intended shape without reading the template first.

- If the repo already has real records ready to migrate, real records are better

- than synthetic examples.

- ## Phase 6: Add the lifecycle transition helper

- Create a repo-owned helper such as:

- - `scripts/set-feature-record-lifecycle.sh`

- It should:

- - accept `<record-path> <target-state>`

- - optionally accept `--repo-root`

- - require `--superseded-by <path>` for `superseded`

- - validate that the record exists

- - validate that it lives under the feature-records tree

- - reject the root `README.md` and `TEMPLATE.md`

- - update the `Lifecycle` `State`

- - update `Superseded by`

- - move the file into the correct lifecycle directory

- Good default transition usage:

- ```bash

- bash scripts/set-feature-record-lifecycle.sh feature_records/planned/<record>.md active

- bash scripts/set-feature-record-lifecycle.sh feature_records/active/<record>.md done

- bash scripts/set-feature-record-lifecycle.sh \

- --superseded-by feature_records/done/<replacement>.md \

- feature_records/active/<record>.md superseded

- ```

- ## Phase 7: Add tests

- Add direct tests for both the checker and the lifecycle helper.

- Checker tests should cover:

- - valid record passes

- - missing required section fails

- - invalid uncertainty/status values fail

- - missing verifier fails

- - waived without rationale fails

- - superseded without pointer fails

- - mismatched lifecycle folder and `State` fails

- - substantive change without record update fails

- - policy override with a different plan directory still works

+ ## Phases 2-7: Build the contract mechanics

- Lifecycle helper tests should cover:

+ Use

+ [references/contract-system-implementation-details.md](references/contract-system-implementation-details.md)

+ for the detailed policy surface, feature-record tree, template sections,

+ checker checks, lifecycle helper behavior, seed-record guidance, and direct

+ test cases.

- - moving `planned -> active`

- - moving `active -> done`

- - moving `active -> superseded` with replacement

- - rejecting `superseded` without replacement

- - checker still passes after helper-driven transitions

+ Keep these invariants in the main workflow:

- Prefer shell tests when the checker/helper are shell scripts.

+ - put the policy in a neutral repo-owned path such as `config/`, not under

+ `.agents/`, when scripts, CI, or humans depend on it

+ - make the policy the single source of truth for substantive paths, lifecycle

+ values, required sections, evidence lanes, checker command, and validation

+ profiles

+ - keep feature records in lifecycle subdirectories whose names match each

+ record's `Lifecycle` `State`

+ - make the checker validate both changed-path coverage and record structure

+ - make the lifecycle helper update fields and move files deterministically

+ - add direct tests for checker and helper behavior before calling the system

+ complete

## Phase 8: Add a repo-local process overlay when the repo uses skills

If the target repository keeps project-local skills, generate a thin overlay

that:

- names the concrete policy file path

- tells the agent to apply `development-contract-process`

- names the checker command and lifecycle helper command

- points at the repo policy's validation profiles

- avoids restating schema details already enforced by policy and checker

Do not generate this overlay when the repo does not use local skills. The repo

must remain usable for humans and scripts without any skill dependency.

## Phase 9: Update docs

Update the repo docs so a human maintainer can use the system without the skill:

- main README

- AGENTS-style maintainer guidance

- release checklist or hygiene docs

- feature-records README

- The main README should include a readable lifecycle diagram, for example:

- ```text

- start work complete + verify

- +-----------+ ----------> +----------+ -----------------> +--------+

- +-----------+ +----------+ +--------+

- |

- | replace with newer record

- v

- +---------------+

- | superseded/ |

- +---------------+

- rule: records in `superseded/` must set `Superseded by` to the replacement record

- ```

- Also document the lifecycle helper command explicitly.

+ Use the lifecycle diagram example in the implementation-details reference when

+ the README needs a concrete visual. Always document the lifecycle helper

+ command explicitly.

## Decision rules

- Prefer repo-owned files under `config/`, `scripts/`, and `feature_records/`

over agent-specific locations.

- Keep the policy file as the single source of truth for checker behavior.

- Keep the checker and lifecycle helper deterministic and local-first.

- Prefer a small explicit schema over a flexible but vague document format.

- Keep feature records as Markdown so they are easy to review in git.

- Keep lifecycle visibility obvious from the directory tree.

- Seed each lifecycle folder with an example record unless the repo already has

real records.

- When the repo uses local skills, keep the repo-local process overlay thin and aligned

with the policy, checker, template, and docs.

- If the repo has a release checklist, point it at the checker and lifecycle

docs.

## Final acceptance criteria

The system is complete when:

- the repo has a neutral policy file

- `feature_records/` exists with root docs/template and lifecycle subdirectories

- the checker enforces lifecycle and evidence rules

- the helper script performs lifecycle transitions deterministically

- direct tests exist for checker and helper

- if the repo uses local skills, the repo-local process overlay points at the concrete

policy/checker/helper without duplicating schema literals

- repo docs explain the lifecycle model and helper commands

- the repo's hygiene or validation path includes the checker

## Output expectations

When using this skill, leave behind:

- the full repo-owned contract system

- example lifecycle records or migrated real records

- tests that prove checker and helper behavior

- docs aligned with the system

- a concise summary of what was validated and what remains manual