# Engineering Change

> Run an opt-in deep, single-agent engineering review with risk analysis, bounded capture, verification claims, and a machine summary. Use when the user explicitly requests this Skill, a machine review bundle, or strict evidence for a high-risk/release change. Do not invoke automatically for routine repository work merely because Rootloom is installed.

- **Type:** Skill
- **Install:** `agentstack add skill-liyanqing90-rootloom-engineering-change`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [liyanqing90](https://agentstack.voostack.com/s/liyanqing90)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [liyanqing90](https://github.com/liyanqing90)
- **Source:** https://github.com/liyanqing90/rootloom/tree/main/plugins/rootloom/skills/engineering-change

## Install

```sh
agentstack add skill-liyanqing90-rootloom-engineering-change
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Engineering change

Run one focused engineering loop. Stay single-agent unless the user explicitly asks for delegation.

This Skill is opt-in. Plugin installation and ordinary Tier 0/1 implementation do not trigger it, and they do not require its analyzer, baseline, contract, or finalizer. Use repository evidence and proportional tests directly unless the user, repository guidance, or a high-risk/release workflow calls for the deeper bundle.

Default sequence: Evidence → Diagnosis → Change Contract → Implementation → Verification → Final Review Summary.

## 1. Route the task

For an advisory assessment, run the deterministic scanner without creating a baseline:

```bash
python3 /scripts/analyze_change.py \
  --repo /absolute/path/to/repository \
  --task 'Describe the requested behavior' \
  --path src/anticipated-owner.py
```

For intake-sealed governed evidence, create a review directory before editing:

```bash
python3 /scripts/begin_review.py \
  --repo /absolute/path/to/repository \
  --task 'Describe the requested behavior' \
  --output /absolute/path/outside-repo/run \
  --path src/anticipated-owner.py
```

`begin_review.py` requires at least one `--path`; use `--allow-all-paths` only when whole-repository scope is intentional. It normally requires a clean worktree/index, while `--allow-dirty-baseline` explicitly records pre-existing changes. `--reviewable-path exact/file` may be declared only here, with a fixed independent maximum of 64. Git resolves each declaration to the repository's actual spelling, and Intake accepts only an existing single-link regular non-symlink file whose worktree changes remain visible to Git Status and Diff. It can pin an already-reviewable environment template or public certificate and can downgrade ambiguous material such as a public `.pem` or `.der`; ignored paths, `assume-unchanged` / `skip-worktree` entries, globs, case-fold ambiguity/duplicates, hardlinks, explicit sensitive overlap, and strong material fail closed. The visibility, Index-state, spelling, type, and link checks repeat in stable capture. Every accepted declaration remains a high-risk security-domain signal and is sealed into Intake; Finalizer deliberately has no matching option. Summary revision 5 reports honest `policy_provenance`, separate `captured_files_provenance`, exact paths, policy hash, and captured identity metadata under `reviewability_policy`. If the aggregate tracked patch later changes, finalization conservatively scopes still-dirty tracked endpoints because the baseline cannot prove their per-path attribution; exact unchanged untracked fingerprints remain pre-existing and outside task scope, risk analysis, and `diff.patch`, while changed fingerprints remain conservatively attributed and a pre-existing dirty path that disappears fails closed. Intake creation uses a temporary-directory transaction followed by the platform's atomic no-replace rename, so capture/write failure leaves no final run and a concurrently created destination is never overwritten.

The intake contains `baseline.json`, editable `change-contract.draft.json`, and immutable-input `review.json`. Edit only the draft, replace every exact Rootloom contract placeholder, and then seal it:

```bash
python3 /scripts/seal_contract.py \
  --review-dir /absolute/path/outside-repo/run
```

Sealing deeply validates and normalizes the draft, then exclusively creates `change-contract.json` and `contract.seal.json`. The seal binds the canonical contract hash, raw sealed-file hash, review-manifest byte hash, baseline hash, run ID, nonce, and task hash. Do not edit the sealed contract or manifest; finalization rejects post-seal drift. If an interruption left an exact final contract without its seal, rerun with `--recover`; recovery validates the current baseline, manifest, draft-derived contract, and existing bytes and never overwrites mismatched evidence.

For an analyzer-only baseline, run it before editing and add the external baseline:

```bash
python3 /scripts/analyze_change.py \
  --repo /absolute/path/to/repository \
  --task 'Describe the requested behavior' \
  --path src/anticipated-owner.py \
  --write-baseline /absolute/path/outside-repo/baseline.json
```

The external baseline is mandatory only when the finalizer will run with `--strict` for Tier 1/2. Analyzer-created and default Intake baselines use `rootloom-change-baseline-v3` with canonical `run_id`, nonce, timestamps and hashes plus repository/Git identity; v3 names the local intake fact `intake-sealed`. An Intake with a reviewable exception uses opt-in `rootloom-change-baseline-v4` and includes the exact exception set in the sensitive-policy hash. Readers validate historical v2/v3/v4 structure and hashes without applying the current classifier; Finalizer separately applies current execution policy and returns `reintake-required` before Reviewable content capture when necessary. Do not introduce a new Baseline or Summary revision to express that policy correction. A baseline is accepted only after two consecutive bounded captures agree; strict finalization binds current HEAD, symbolic HEAD ref, and index to it and rechecks the base after verification. Both passes share one finite-positive `--max-capture-seconds` monotonic deadline (default 90). Every Git child runs through the controlled process-tree owner with closed stdin and receives the smaller of the remaining capture time and finite-positive `--max-git-seconds` (default 30). Baselines capture bounded tracked/untracked state plus metadata-only ignored secret material, symlinks, and directories. `is_sensitive_material_path()` alone controls privacy capture; `is_security_domain_path()` raises risk for reviewable security artifacts and source without suppressing their patches. Targeted discovery has an independent bounded candidate ceiling; positive `--max-sensitive-paths` (default 10,000) limits only the classified material-result union. Never recreate a missing intake baseline after implementation and present it as pre-change evidence.

Inspect every reported signal. The scanner combines task text, paths and operations, bounded tracked and non-sensitive untracked diff signals, and repository commands. It includes relevant active Project Memory only after an explicit `--include-project-memory` request. It reports a minimum Tier and verification plan; it cannot prove semantic risk. Raise the tier further when current evidence or unknown consumers require it.

Then classify the request:

- **Tier 0 Direct** — mechanical, local, reversible, and directly verifiable;
- **Tier 1 Scoped** — behavioral change or defect with a bounded ownership path;
- **Tier 2 Governed** — public or persisted contracts, schemas, migrations, security, infrastructure, destructive effects, or materially uncertain blast radius.

Use `operating-coding-change` for Tier 0/1 discipline and `operating-high-risk-change` for Tier 2. Do not use this Skill to bypass an approval gate.

## 2. Load project intelligence

Read the closest `AGENTS.md`. Project Memory is experimental: consult `.project-memory/` only when the user explicitly requests it for this review. Then use `project_memory.py context` with the task query and in-scope paths, and pass `--include-project-memory` to Analyzer and Finalizer when their assessment should include the same signal. The existence of `.project-memory/` is never opt-in by itself. Treat stale matches as history and all memory as leads; repository evidence is truth. Never create or update memory silently.

## 3. Establish evidence and diagnosis

Inspect the observable path and its owning boundary before editing. For a defect, record:

- the trigger and observed failure;
- at least two plausible causes when the root cause is uncertain;
- evidence that rejects the strongest alternative;
- the violated invariant and evidence-backed root cause;
- `ROOT_CAUSE_ALIGNMENT: PASS` before implementation.

For a feature or mechanical change, use `ROOT_CAUSE_ALIGNMENT: NOT_APPLICABLE` and state the intended invariant instead.

## 4. Form the change contract

Tier 0 may keep an internal contract. Advisory finalization may omit a machine contract. Strict Tier 1/2 finalization must provide `rootloom-change-contract-v1` and name:

- allowed files or module boundary;
- forbidden or explicitly excluded scope;
- public/persisted compatibility expectations;
- required verification for the original path, owning invariant, and an adjacent path;
- rollback and remaining risk.

Minimal machine contract:

```json
{
  "format": "rootloom-change-contract-v1",
  "allowed_paths": ["src/auth/**", "tests/auth/**"],
  "forbidden_paths": ["src/billing/**"],
  "root_cause_alignment": "PASS",
  "verification_commands": {
    "verify-primary": "python3 -m unittest tests.test_auth.AuthTests.test_login",
    "verify-invariant": "python3 -m unittest tests.test_auth.TokenTests",
    "verify-adjacent": "python3 -m unittest tests.test_auth.AuthTests.test_expired"
  },
  "verification_claims": {
    "primary": [{
      "id": "primary-behavior",
      "command_ids": ["verify-primary"],
      "target": "tests/test_auth.py::AuthTests.test_login",
      "expected_evidence": "valid login creates a session",
      "evidence_kind": "regression-test"
    }],
    "invariant": [{
      "id": "owning-invariant",
      "command_ids": ["verify-invariant"],
      "target": "tests/test_auth.py::TokenTests",
      "expected_evidence": "token invariants hold",
      "evidence_kind": "unit-test"
    }],
    "adjacent": [{
      "id": "adjacent-path",
      "command_ids": ["verify-adjacent"],
      "target": "tests/test_auth.py::AuthTests.test_expired",
      "expected_evidence": "expired login remains rejected",
      "evidence_kind": "regression-test"
    }]
  },
  "baseline_sha256": "",
  "task_sha256": "",
  "run_id": "",
  "nonce": ""
}
```

This is the editable draft shape; `seal_contract.py` adds `contract_sha256` to the immutable final contract. The hash basis is canonical JSON without that field, and `contract.seal.json` additionally binds the final file bytes.

The contract never authorizes commands by itself. Every mapped command must still be passed through `--verify`. Simple string claims and temporary `--verify-claim` values remain diagnostic declarations and cannot complete strict evidence. Only structured claims originating in the sealed contract qualify for strict claim completeness. A structured target check is still mechanical evidence, not proof that the test is semantically sufficient.

## 5. Implement once, in scope

Use existing architecture and dependencies. Preserve unrelated user changes. Fix the invariant at its owner, not a downstream symptom. Do not add a wrapper, flag, record, or approval step unless it changes a concrete decision.

Before deleting secret material, `.env`, a migration, or a database artifact, stop and obtain confirmation for the exact path. Security-domain source deletion raises risk and still requires careful diff review, but it does not invoke the privacy confirmation solely because its name contains token, credential, or secret.

## 6. Verify intelligently

Choose checks from the changed behavior, not only from convenient commands. Map each material change to:

- the original or primary behavior;
- the owning-boundary invariant;
- an adjacent negative or alternate path;
- the smallest focused test, then broader checks proportional to blast radius.

Run repository-owned commands and observe their exit status. Classify failures as introduced, pre-existing, environmental, or unverified.

Use the analyzer's `verification_plan.required_behaviors` as a checklist, not evidence. Its `suggested_commands` are repository-derived suggestions and are never executed automatically. Record only commands actually run under `tests`.

For a non-blocking machine-readable local summary, run:

```bash
python3 /scripts/finalize_change.py \
  --repo /absolute/path/to/repository \
  --output /absolute/path/to/run \
  --task 'Describe the requested behavior' \
  --verify 'python3 -m unittest tests.test_example' \
  --remaining-risk 'Describe only a material remaining risk'
```

Advisory mode exits successfully when the explicit commands pass and capture remains stable, even if no baseline/contract proves complete coverage. It reports `quality_status: UNVERIFIED` and keeps compatibility `passed: false`; default `--exit-policy bundle` means exit zero can mean "bundle generated", not "engineering sufficiency proven". Use `--exit-policy quality` or `--require-verified` in CI.

For release or other explicitly governed work, add:

```text
--strict \
--baseline /absolute/path/outside-repo/baseline.json \
--change-contract /absolute/path/outside-repo/change-contract.json \
--semantic-coverage reviewed
```

Strict mode defaults to quality exit semantics: only `REVIEW_EVIDENCE_COMPLETE` returns zero. Use explicit `--strict-bundle-only` when a non-blocking strict bundle is intentionally required. Evidence and output paths must be outside both the repository worktree and its resolved Git common directory, including for linked worktrees; output must also be absent, empty, or already carry Rootloom's ownership marker. A reused owned output invalidates its previous summary before the new run can exit early. Lexical path and parent checks reject symlink redirection before resolution. The helper recomputes the assessment, does not run a shell, and writes ordinary `diff.patch`, `test.log`, and `summary.json` files.

Ordinary untracked files receive streaming SHA-256 fingerprints and bounded applyable text patches; only task-attributed non-material text participates in risk analysis and the final patch. Binary/large files receive type, size, and hash. Secret-material discovery asks Git only for shared case-insensitive candidate pathspecs and literal declared roots, then reclassifies every returned path with `is_sensitive_material_path()`; deliberately overmatching candidates and classified results use separate bounded ceilings. Material includes `.env`, `.envrc`, non-template `.env.`, credential configuration, private-key/keystore formats, ambiguous `.pem` and `.der`, explicit roots, common key-named PEM/DER files, and common CamelCase names. Environment templates (`.env.example`, `.env.sample`, `.env.template`, `.env.dist`) and public certificate formats (`.crt`, `.cer`, `.p7b`, `.p7c`) stay content-readable while raising high-risk security signals; DER is content-unread unless explicitly declared reviewable at Intake. `.environment`, `.envelope`, and `.envoy` are ordinary. Security-domain source follows the same risk-only boundary. Material files remain content-unread and metadata-only, including device/inode or platform equivalents, link count, size, mode, modification time, and change time; symlink targets are represented only by byte length and SHA-256. Any material metadata change before or during verification, including a newly discovered ignored addition relative to the reference capture, quarantines every changed endpoint before ordinary content capture, disables additional repository-memory/command discovery, and places ignored material additions, changes, and deletions into scope. An otherwise-complete redacted review is capped at `REVIEW_REQUIRED_WITH_REDACTIONS` with `evidence_complete: false` and `passed: false`. The summary reports `sensitive_integrity: metadata-observed`; this detects ordinary same-size rewrites but is not cryptographic content integrity. Status, patch, fingerprints, command output, and memory reads all fail closed at configured bounds.

Evidence JSON rejects duplicate keys, non-standard constants, and out-of-range numbers. Every verification command is parsed before the first command executes. Evidence files, seals, the Git base, and the output target are revalidated after command execution; trust-input drift forces `FAILED`.

Verification commands run in a controlled process tree. Output is consumed incrementally and the tree is

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [liyanqing90](https://github.com/liyanqing90)
- **Source:** [liyanqing90/rootloom](https://github.com/liyanqing90/rootloom)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-liyanqing90-rootloom-engineering-change
- Seller: https://agentstack.voostack.com/s/liyanqing90
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.