Adoption help: bring an existing project, Spec Kit workspace, or OpenSpec repository

[0xLeif]

Use this Q&A thread when adopting SpecSync in an existing codebase. Include your language(s), repository shape, current SDD tooling, the command you ran, and sanitized output from specsync change adopt --dry-run or specsync check --format github. Please remove credentials and private source before posting.

[0xLeif]

Six things a day of real 6.0 adoption turned up, in the order they bite

All of this came out of adopting 6.0.0-rc.2 on an existing repository and driving about ten changes through the lifecycle. Each item is a trap someone hit, with the escape they found. Issue numbers are linked so you can check the state rather than trust this post.

---

1. Check your merge strategy before you adopt anything

Run this first:

gh api repos/<owner>/<repo> --jq '{merge:.allow_merge_commit,squash:.allow_squash_merge,rebase:.allow_rebase_merge}'

If squash is the only one enabled, know going in that verification evidence recorded against a commit hash does not survive your own pull request. On rc.2 through rc.5 that made a change read as unverified the moment its PR landed, and clearing it forces a full re-verify plus a fresh independent review, which is the one step in the lifecycle that structurally requires a human. It was observed three times on a single change in one day.

This is not an exotic configuration. spec-sync's own repository is squash-only, and measured across its own archives, 19 of 178 archived changes have a verification commit still reachable from origin/main.

Two follow-ups worth knowing:

• The readiness half now has a fix merged in fix(change): ship readiness is a content question, not a history one (#689) #695, on main and not yet in a tagged release candidate (verification.commit ancestry is incompatible with squash-only repositories, and there is no available workaround #689). Measured there across squash, rebase, and merge-commit, all three reach ready to finalize.
• The ship side is still open as the scoped-review descendant walk fails closed forever after a squash, and its guarantee is unavailable rather than violated #694, and ship-status advertises check --commit from accepted, where check's own state machine rejects it #690 is the wedge it produces: ship-status can advertise change check <id> --commit from accepted, a state check itself refuses.
• Reported on docs: adopting a repo needs the merge strategy warning first #692: gh pr merge --rebase falls back to squash silently when rebase-merge is disabled at the repository level. So following advice to "use rebase-merge" is not sufficient. Check the setting itself.

---

2. If you upgraded from 5.x, confirm which lifecycle you are actually on

specsync init on a fresh repository writes policy version: 2 and you get the current lifecycle without doing anything. On an upgraded repository the policy carries version: 1, and re-running init short-circuits on "config.toml already exists" without raising it. Every change you then create is workflow v1, and before rc.3 nothing said so until ship refused several verbs later.

The verb you want is specsync change adopt. It is listed under specsync change --help, not top-level specsync --help, which is where people look for it and fail to find it.

The loop to avoid: create a change before adopting, and adopt then refuses because of that change. The escape works and is correct, but you have to already understand the trap to derive it: commit and integrate (or archive) the v1 change first, then rerun specsync change adopt.

adopt is genuinely non-destructive. Existing v1 records keep their workflow_version absent rather than being rewritten.

As of 6.0.0-rc.3 (#678), both init and change new announce the legacy lifecycle when you are on it, and a workflow-v2 repository stays completely silent.

---

3. --spec and --no-spec-change coexist, and that pairing is what you want for behaviour-only work

The flag names suggest they are alternatives. They are not. For production source that changes no spec text, use both:

specsync change new "<summary>" --kind fix \
  --spec change --spec cmd_change \
  --path src/change.rs --path src/commands/change.rs \
  --no-spec-change --rationale "behaviour only, no spec text changes"

Using --no-spec-change with no owning specs is refused at ship, several stages after it can be cheaply fixed. Scope freezes at approval and there is no withdraw verb (#554), so the exit is resetting the branch and redoing the whole lifecycle. That cost roughly 25 minutes of verification twice, in this repository, to the person writing the fixes.

To find a path's owning spec, grep the files: list in specs/<module>/*.spec.md. A path with no owner at all is itself the defect to fix first. Documented in docs/ADOPTING.md as of 6.0.0-rc.4 (#682).

---

4. Merge only after finalize, and the cost is larger than one record

The warning text through rc.5 said merging first orphans verification evidence and strands the change. That prices the loss as one record: yours, local, recoverable.

The measured cost is bigger. An unfinalized change never reaches accepted or archived, so it never becomes an accepted or archived successor, and every earlier accepted change sharing any delivery input with it can no longer archive:

specsync change archive <predecessor>
error: delivery input `specs/<module>/<module>.spec.md` (owner `<module>`) changed after
acceptance and no accepted or archived successor change covers it; run
`specsync change reopen <predecessor>`

On the affected repository the coupled set on one spec was 13 changes. Each merge-early decision looks small and locally recoverable; the aggregate is a lifecycle that cannot drain.

The wording is corrected (#687, merged in #691) but landed after 6.0.0-rc.5 was tagged, so it is on main and not in any release candidate yet. The behaviour was always this way.

Related and still open: #688, where the predecessor and the successor each name the other as the thing that must move first, and neither says the counterpart is blocked too.

---

5. Two state traps whose escapes are not derivable from the error text (#685)

check --commit then accept never converges on a reopened workflow-v1 change. The verification-recording commit always leaves HEAD one ahead of the evidence it just recorded, so accept reports the verification as stale, and re-running check --commit recreates the condition it is trying to clear.

Escape: run check without --commit. It records against the current HEAD, and accept then succeeds.

ship refuses a stale review while review refuses to run in accepted. Committing anything between review and ship stales the review's workspace digest. By the time you find out, the change is accepted, and record_scoped_review requires Verifying, so the verb that would fix it is unreachable from the state you discover the problem in.

Escape: finalize rather than ship.

ship-status prints both verbs without indicating that only one is reachable.

---

6. db_tables when your schema lives in application code

If your schema is defined in Go, TypeScript, or anything that is not .sql migration files, there is nothing to point schema_dir at, and schema_dir is not a spec frontmatter field so it cannot be scoped per module. Through rc.4 that left a permanent warning, and warnings escalate to errors under --strict:

DB table validation skipped: `db_tables` is declared but `schema_dir` is not configured

The only ways to clear it were deleting truthful db_tables documentation or abandoning strict and giving up drift gating everywhere else.

As of 6.0.0-rc.5 (#684) this is a notice. It still prints, it no longer gates:

⊘ DB table validation skipped: `db_tables` is declared but `schema_dir` is not configured

Note also that the gate was scoped to the effective contract, not the repository. Changes whose contract excludes the declaring spec verified clean throughout.

If you do have .sql migrations, 6.0.0-rc.4 (#672) fixed a related cascade: an unparseable migration previously reported every declared table as missing, including tables created correctly in unrelated files.

---

If you are posting your own adoption here

The most useful thing you can include, and the thing that changed several of these diagnoses today, is a measurement of your own repository rather than a symptom. Counts by state, which archives are anchored, which paths are present on your default branch. Three explanations of one coupling were wrong today and each was killed by someone running a command instead of reading source.