跳转至

简体中文

Recipe: Existing-Repository Read-Only Adoption Inventory

1. Scenario and Non-Scenario

Applicable: you need to judge whether an existing repository can adopt Foundation, and obtain the exact write set, conflicts, and legacy-implementation exit list, without changing any bytes.

Not applicable: needs to auto-rewrite the existing repository (writing files is forbidden, auto-migration is forbidden); needs to publish to a remote (→ release-skill).

2. Architecture Choice and Capability ID

Preferred capability: foundation.kit.adopt-plan (strictly read-only inventory and completion judgment). It only outputs, writes no files, runs no git write commands.

3. Preconditions and Trust Boundary

  • The target repository exists and is read-only accessible.
  • Trust boundary: adopt-plan makes zero byte changes to the input repository; legacy-implementation deletion is the caller's responsibility, and the tool never deletes on its behalf.

4. Minimal Command

npm install --save-dev skill-family-engineering-kit@0.3.0
npm exec -- skill-family-kit adopt-plan --root <repo>

5. Expected Output and Evidence

The output includes the current state (target), target Profile and traceability (project/traceability), read-only Git pre-state (git), exact write set (writeSet), conflicts (conflicts), risks (risks), migration state machine (migration), and acceptance command sequence (verificationPlan). Evidence from packages/skill-family-engineering-kit/test/adopt-plan.test.mjs and test/migration.test.mjs.

6. Safety / Failure Negative Case

Before and after running adopt-plan on a dirty repository, the input repository's bytes must be exactly identical (provable by hash walk-through); the tool writes no temp files and touches no remote. If the migration manifest is missing a required exceptions field, the plan fails directly (completion false), and the tool does not renew.

7. Copy-Paste Verification Command

# Positive case: read-only inventory of a public fixture existing-repository
npm exec -- skill-family-kit adopt-plan --root fixtures/m0-consumer

# Read-only diagnostics, no fix
npm exec -- skill-family-kit check --root fixtures/m0-consumer

8. Business Logic the Caller Continues to Own

  • Whether the legacy implementation exits, and when to delete it (the tool only evaluates existence and lists the exit manifest).
  • business-logic-to-keep and legacy-removal-recovery are always INCOMPLETE and must be provided by a human owner.

9. Upgrade and Rollback Notes

  • adopt-plan is read-only, has no write risk, and needs no rollback.
  • Actual disk writes are performed by scaffold/projection; rollback relies on the dual-digest binding of adoptionProof and foundationPlanDigest; an overwrite action that does not declare the expect.sha256 pre-state is refused at the projection stage.
  • When adopting the Quickstart Profile candidate, pin all three packages to one profile: 0.3.0 for v2 or 0.2.1 for v1. Do not mix them.