Showcase: how are you using SpecSync?

[0xLeif]

Share a project, workflow, CI gate, agent integration, or migration powered by SpecSync. Helpful details include repository size, languages, which artifacts you keep, drift caught before merge, and lessons for other adopters. Public repositories and screenshots are welcome.

[0xLeif]

Field report: one day of adoption on an existing site repository, and the shape underneath the defects

Not a showcase of a working setup. This is what happened when SpecSync 6.0.0-rc.2 was driven in anger against CorvidLabs/site, an existing Astro repository with 17 pre-existing workflow-v1 records, over a single working day. Six fixes came out of it: five across three release candidates, and one that is on main and not yet in any tagged release. Posting it here because the interesting part is not the individual bugs, it is that most of them were the same bug.

What the day produced

release	fix
rc.3	The archive anchor predicate asked for a path a squash-merge guarantees is absent (#677)
rc.3	An orphaned verification commit had no forward verb: check refused on reachability, reopen refused on content, and reachability is not something reopen could observe (#673)
rc.3	A repository upgraded from 5.x silently stayed on the legacy lifecycle and only found out at ship (#678)
rc.4	One unparseable SQLite migration reported every declared table as missing, including tables created correctly in unrelated files (#672)
rc.5	db_tables without a configurable schema_dir was a permanent strict-gating warning with no workaround (#684)
on main	The merge-before-finalize warning priced its own consequence at one record when the measured cost is every earlier accepted change sharing a delivery input (#687)

Plus #695 (for #689), since merged to main and not yet in a tagged release and one open design decision (#694).

The shape

Four of those six, and both open items, are the same defect:

A category is empty for want of input, and the code reads it as a verdict.

• Schema validation rejects the standard SQLite idempotent ADD COLUMN back-fill, failing the whole spec #672. build_schema_snapshot failed, Err(_) => return HashSet::new(), and the caller read an empty table set as proof that no tables exist. The error was not even inspected. One bad migration therefore condemned every table in the spec.
• 6.0 regression: orphaned verification evidence is reported as AuthenticatedHistory — the anchor check is unreachable on workflow-v2 #677. accepted_change_is_recorded_in_ref looked for .specsync/changes/<id>/state.json on the default branch. A workflow-v2 change is created, verified, and archived in one pull request, so a squash-merge means that path never appears there. Absent for structural reasons, read as "not recorded". Measured: active path 83 of 178, archive path 178 of 178.
• db_tables cannot be satisfied when the schema lives in code: declaring it is a permanent strict-blocking warning with no workaround #684. db_tables declared with no schema_dir to point at emitted a warning, and warnings gate under --strict. "I could not check this" was rendered as "your spec is wrong", and the only escapes were deleting truthful documentation or abandoning strict mode entirely.
• verification.commit ancestry is incompatible with squash-only repositories, and there is no available workaround #689 and the scoped-review descendant walk fails closed forever after a squash, and its guarantee is unavailable rather than violated #694. A squash rewrites the commit an ancestry walk needs, so the walk cannot run. Unavailable, reported as violated. Measured on spec-sync's own repository: 19 of 178 archived changes have a reachable verification commit, and 0 of 107 passing (2 reachable) archived reviews have a reachable implementation commit.

I want to be precise rather than tidy: this is not "nearly every defect". #687 does not fit the shape at all, it is a wording defect where the tool understated a real and correctly-computed cost. #678 fits only loosely, in that silence ("config.toml already exists") got read as "nothing to do here". Four clean instances and two open ones is still a pattern worth naming, but it is not all of them.

Why the shape matters more than the individual fixes

Every one of these is invisible from the inside. The code is not wrong locally: returning an empty set on error is a defensible line, and so is warning about an unconfigured schema_dir. The defect only exists at the join, where a caller reads absence as evidence. That is why they survived to a release candidate with tests green, and why grepping for them is hard.

The fix that generalises is not "relax the check". It is to make cannot answer a first-class result, distinct from answered no, and to say which one occurred. #694 is the live test of that principle: the cheapest option there is to fall back to the checks that can run and state plainly that the guarantee was unavailable, on the grounds that an unavailable guarantee reported as a satisfied one is worse than the current hard failure.

The other lesson, which is about method rather than code

Three separate explanations of one change-coupling were advanced during that day. All three looked right. All three were wrong, and each was killed by somebody running a command:

1. finalize cascades forward into siblings. Refuted by an archive run in which the first change failed immediately.
2. Finalizing the four verifying successors will clear the blocked predecessor. Refuted by running it: the successor could not archive either.
3. The archived path has no anchor check at all. Refuted by following the calls: it anchors through validate_finalization_evidence on a different commit.

The corrected mechanism, which is measured rather than inferred: merging before finalize leaves a change in verifying, so it never becomes an accepted-or-archived successor, so every earlier accepted change sharing that delivery input cannot archive. Not forward cascade. Backward blocking.

If you are adopting and something surprises you, the highest-value thing you can post is the command output, not the theory. On this evidence the theories have a poor record and the measurements have a perfect one.

For anyone about to adopt

The traps and their escapes are written up in Q&A #336. Start with the merge-strategy check at the top of it, before anything else.