stores: no lockfile or commit pin

[aisamu]

Hi!

I was reading the stores-beta user guide and wanted to check one assumption about how teammates stay in sync.

A code repo points at a store by id (store: team-plans in openspec/config.yaml), and each machine maps that id to a local checkout with openspec store register. The guide is clear that "OpenSpec never clones, pulls, or pushes": teammates move the store around with plain git themselves.

The part I could not find is anything that records which version of the store a code repo expects. There is no lockfile, and the registry entry stores only a path. So when two teammates have the store checked out at different commits, the same store: team-plans could resolve to different specs on each machine, and nothing flags the divergence.

Concretely, this means that two people can legitimately read directly opposite requirements from what is nominally the same spec.

Reproduction

Version

openspec --version

1.4.1

We'll use scoped XDG folders to emulate the store and three separate users - the author and two consumers:

Shared Store

Let's create a straightforward shared store and commit a spec.

export XDG_DATA_HOME=/tmp/openspec-store-drift/author/data
export XDG_CONFIG_HOME=/tmp/openspec-store-drift/author/config

export STORE=/tmp/openspec-store-drift/store

# New store
openspec store setup team-plans --path $STORE

# New change
openspec new change add-auth-tokens --store team-plans

mkdir -p $STORE/openspec/changes/add-auth-tokens/specs/auth-tokens/
cat <<'EOSPEC' >$STORE/openspec/changes/add-auth-tokens/specs/auth-tokens/spec.md
## ADDED Requirements
### Requirement: Token lifetime
Access tokens MUST remain valid for 24 hours and MAY be reused.

#### Scenario: A token issued an hour ago is replayed
- **WHEN** a client presents a token issued 1 hour ago
- **THEN** the API accepts it
EOSPEC

# Archive change
openspec archive add-auth-tokens --store team-plans --yes

# Commit
git -C $STORE add -A
git -C $STORE commit -qm "auth-tokens: 24h, reusable"

Store ready: team-plans
Location: /private/tmp/openspec-store-drift/store
OpenSpec root: ready
Registry: already registered
Note: Store 'team-plans' is already registered at this path.

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-plans
Share this store by committing and pushing it like any Git repo.
Created change 'add-auth-tokens' at /private/tmp/openspec-store-drift/store/openspec/changes/add-auth-tokens/
Schema: spec-driven
Next: openspec status --change add-auth-tokens --store team-plans
Task status: No tasks

Specs to update:
  auth-tokens: update
auth-tokens ADDED failed for header "### Requirement: Token lifetime" - already exists
Aborted. No files were changed.

Project

Let's also create a project to consume said shared spec:

mkdir -p /tmp/openspec-store-drift/project/openspec/

cat <<'EOSPEC' >/tmp/openspec-store-drift/project/openspec/config.yaml
store: team-plans
EOSPEC

User 1 - Alice

Alice sets up the store as it stands today - clone it, register it, read the spec:

export XDG_DATA_HOME=/tmp/openspec-store-drift/alice/data
export XDG_CONFIG_HOME=/tmp/openspec-store-drift/alice/config

# Clone and register the shared store
git clone -q /tmp/openspec-store-drift/store /tmp/openspec-store-drift/alice/store
openspec store register /tmp/openspec-store-drift/alice/store --id team-plans

cd /tmp/openspec-store-drift/project
openspec show auth-tokens --type spec

Store registered: team-plans
Location: /private/tmp/openspec-store-drift/alice/store
OpenSpec root: ready
Registry: registered

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-plans
Share it: teammates clone /tmp/openspec-store-drift/store and run openspec store register <path>.
# auth-tokens Specification

## Purpose
TBD - created by archiving change add-auth-tokens. Update Purpose after archive.
## Requirements
### Requirement: Token lifetime
Access tokens MUST remain valid for 24 hours and MAY be reused.

#### Scenario: A token issued an hour ago is replayed
- **WHEN** a client presents a token issued 1 hour ago
- **THEN** the API accepts it

Spec change

We then radically change one requirement: tokens become single-use, 60s:

export XDG_DATA_HOME=/tmp/openspec-store-drift/author/data
export XDG_CONFIG_HOME=/tmp/openspec-store-drift/author/config

export STORE=/tmp/openspec-store-drift/store

# New change
openspec new change tighten-tokens --store team-plans

mkdir -p $STORE/openspec/changes/tighten-tokens/specs/auth-tokens
cat <<'EOSPEC' > $STORE/openspec/changes/tighten-tokens/specs/auth-tokens/spec.md
## MODIFIED Requirements
### Requirement: Token lifetime
Access tokens MUST be single-use and expire 60 seconds after issuance.

#### Scenario: A token issued an hour ago is replayed
- **WHEN** a client presents a token issued 1 hour ago
- **THEN** the API rejects it with 401
EOSPEC

openspec archive tighten-tokens --store team-plans --yes

git -C $STORE add -A
git -C $STORE commit -qm "auth-tokens: reverse to 60s, single-use"

Created change 'tighten-tokens' at /private/tmp/openspec-store-drift/store/openspec/changes/tighten-tokens/
Schema: spec-driven
Next: openspec status --change tighten-tokens --store team-plans
Task status: No tasks

Specs to update:
  auth-tokens: update
Applying changes to /private/tmp/openspec-store-drift/store/openspec/specs/auth-tokens/spec.md:
  ~ 1 modified
Totals: + 0, ~ 1, - 0, → 0
Specs updated successfully.

User 2 - Bob

Bob sets up the store in the exact same way:

export XDG_DATA_HOME=/tmp/openspec-store-drift/bob/data
export XDG_CONFIG_HOME=/tmp/openspec-store-drift/bob/config

# Clone and register the shared store
git clone -q /tmp/openspec-store-drift/store /tmp/openspec-store-drift/bob/store
openspec store register /tmp/openspec-store-drift/bob/store --id team-plans

cd /tmp/openspec-store-drift/project
openspec show auth-tokens --type spec

Store registered: team-plans
Location: /private/tmp/openspec-store-drift/bob/store
OpenSpec root: ready
Registry: already registered
Note: Store 'team-plans' is already registered at this path.

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-plans
Share it: teammates clone /tmp/openspec-store-drift/store and run openspec store register <path>.
# auth-tokens Specification

## Purpose
TBD - created by archiving change add-auth-tokens. Update Purpose after archive.
## Requirements
### Requirement: Token lifetime
Access tokens MUST be single-use and expire 60 seconds after issuance.

#### Scenario: A token issued an hour ago is replayed
- **WHEN** a client presents a token issued 1 hour ago
- **THEN** the API rejects it with 401

Investigation

The only thing I found that differs between the two "machines"/users is the local checkout path. There is no commit, tag, or hash recorded anywhere.

git diff --no-index /tmp/openspec-store-drift/alice/data/openspec/ /tmp/openspec-store-drift/bob/data/openspec/

diff --git a/tmp/openspec-store-drift/alice/data/openspec/stores/registry.yaml b/tmp/openspec-store-drift/bob/data/openspec/stores/registry.yaml
index e392408..f374350 100644
--- a/tmp/openspec-store-drift/alice/data/openspec/stores/registry.yaml
+++ b/tmp/openspec-store-drift/bob/data/openspec/stores/registry.yaml
@@ -3,5 +3,5 @@ stores:
   team-plans:
     backend:
       type: git
-      local_path: /private/tmp/openspec-store-drift/alice/store
+      local_path: /private/tmp/openspec-store-drift/bob/store
       remote: /tmp/openspec-store-drift/store

branch field

I also tried setting a SHA on the optional branch field to verify if openspec would warn us that the stored branch and the store's state had diverged

export XDG_DATA_HOME=/tmp/openspec-store-drift/alice/data
export XDG_CONFIG_HOME=/tmp/openspec-store-drift/alice/config

# Pin Alice's registry to Bob's branch via the branch field
B=$(git -C /tmp/openspec-store-drift/bob/store rev-parse HEAD)
sed -i "s#^      type: git#      type: git\n      branch: $B#" /tmp/openspec-store-drift/alice/data/openspec/stores/registry.yaml

cd /tmp/openspec-store-drift/project
openspec show auth-tokens --type spec | grep -A1 '^### Requirement'

### Requirement: Token lifetime
Access tokens MUST remain valid for 24 hours and MAY be reused.

Alice still resolves to the original checkout (24h), different from the explicitly pinned "branch" - and behind latest. There were no alerts.

Did I miss a setting somewhere? How would we uniquely determine exactly against which shared/parent spec was a given derived spec/feature built?

Thanks for OpenSpec!

[mc856]

Confirmed on main (546224e). Traced the root cause: the git store backend only persists local_path / remote / branch, and branch is never used at resolve time — nothing checks it out or validates HEAD, so a SHA there is silently ignored (matches your repro). doctor only compares canonical remote vs origin, never commit drift.

I've started on a narrow, read-only fix and will open a PR shortly: an openspec doctor check that warns when a store checkout's local branch is ahead/behind its upstream tracking ref. It's a staleness signal only — it doesn't touch the "OpenSpec never clones/pulls/pushes" contract.

A true reproducible pin (recording the expected store commit per code repo) is a separate design question; I'll leave that as a follow-up proposal rather than fold it in here. Let me know if you'd rather scope the doctor check differently.

[aisamu]

A follow up proposal makes sense for the reproducible pin - if you'd like me to do it, just let me know exactly the medium!

A couple questions:

1. Re: "warns when a store checkout's local branch is ahead/behind its upstream tracking ref" and "OpenSpec never clones/pulls/pushes"
   Will openspec fetch origin?
   I'm thinking that, if not, we'd risk being locally consistent but still behind the shared source.

2. Is the doctor run optional or part of the regular workflow?
   I'm considering the possibility of someone (human or agent) forgetting to run that step or ignoring a warning.
   A store drift is both risky in terms of cascading consequences (derived spec created from old parent) and simple to fix (a pull/sync), so I'd be OK with it being treated as a blocking error.

Thank you!

[mc856]

Thanks — good questions.

1. Does it fetch? No — doctor only reads local Git state, it never contacts the remote. It compares HEAD against the local @{upstream} ref, which for a normal remote-tracking branch reflects your last fetch. So it catches "fetched but not synced" drift, but not commits you haven't fetched yet — a locally-known staleness signal, not a remote-freshness or cross-machine guarantee.

2. Optional, or enforced? doctor is an explicit, opt-in check and it's read-only: findings of any severity leave the exit code at 0 (only command failures exit 1), so even bumping this to warning/error wouldn't make it blocking. I kept it info to match store_remote_divergence. Your failure mode — a derived spec built from an old parent — is real, but the place to actually enforce a version is at store-resolution time against an explicit pin, which is a bigger change I'd keep out of this read-only PR.

On the follow-up: #1273 is really about that pin, so this issue is the natural home for it. Per the contributing guide a change that size wants an OpenSpec change proposal (the recent Propose: PRs are the pattern) — worth a quick maintainer read on appetite first. The call I'd get up front: does it validate only the local pinned commit (stays offline, contract-safe), or also remote freshness (which would touch "never clones/pulls/pushes")? Happy to help draft or review.

[aisamu]

Understood, thanks for clarifying!

worth a quick maintainer read on appetite first

Should we explicitly ping them here? Or would opening a discussion be preferred?

does it validate only the local pinned commit (stays offline, contract-safe), or also remote freshness

Validating the locally pinned commit is sufficient if and only if it's done from the consuming repo's side and each repo is able to consume their own version of the specs.

Here's an attempt at a representative example:

+--------------------------------------------+
| Store git log                              |
|                                            |
| ??????? unknown commit              <------+------------------------------------------------+
| b7e9c2d [origin/main] second commit <------+--------------------------+                     |
| a1f3d9e first commit                <------+------+                   |                     |
+--------------------------------------------+      |                   |                     |
                                                    |                   |                     |
                                             +------+----------+ +------+----------+ +--------+--------+
                                             | Repo A          | | Repo B          | | Repo C          |
                                             | store: store-id | | store: store-id | | store: store-id |
                                             | ref: main       | | ref: none       | | ref: none       |
                                             | rev: a1f3d9e    | | rev: b7e9c2d    | | rev: c4d5e6f    |
                                             +-----------------+ +-----------------+ +-----------------+

The salient points are:

• The Store is referenced by multiple projects at different revisions.
  • Locally, the Store’s main is at b7e.
  • Our local view of the Store’s origin/main is also at b7e, so as far as this checkout knows, it is up to date.
  • There is no error here: unless we fetch, we cannot know whether we are behind the remote.
• Repo B targets revision b7e.
  • When working on Repo B, we should be presented with the specs from b7e.
• On the same machine, the older Repo A targets revision a1f.
  • When working on Repo A, we should only see the specs from a1f.
  • Since Repo A also has a reference, main, we can emit a notice or warning saying that a newer known Store revision is available.
  • Updating Repo A’s target revision should be a regular project change, since it can have non-trivial consequences such as changes to specs, code, tests, or generated artifacts.
• Repo C was created by someone else and we just cloned it.
  • It targets revision c4d, which we do not have in our local Store checkout.
    • This has to be a hard error, because we do not have the Store contents needed to present the specs to the user.
    • Since this probably means our Store checkout is behind the remote, we could suggest fetching or updating the Store.

Happy to help draft or review.

I'll gladly accept that offer!

[mc856]

Your example matches my read. One mapping note: the Repo A "newer known revision" notice is close to what #1287 already emits, but that check compares the store checkout's own @{upstream} to HEAD — it knows nothing about a per-repo rev. Once a pin exists, resolution should warn against the pin instead. Repo B and Repo C are the new semantics.

Repo C is the piece I'd lead with: the pinned object isn't in the local checkout, which is provable offline, so a hard error there stays inside "never clones/pulls/pushes". Whether resolution should ever check remote freshness is the one question that does touch the contract — I'd list it as an open question for the maintainers instead of settling it in the proposal.

On pinging: I wouldn't. A small Propose: PR gets a faster read here than an @-mention or a discussion, and it doubles as the appetite check — easy to say no to something concrete. #1287 already Refs this issue, so the direction is visible from the review queue either way.

So the medium is a Propose: change proposal (not an implementation PR): the per-repo rev field plus the Repo B/C resolution semantics, offline-only. The model's yours — take the draft, I'll review. Once there's appetite I can pick up the doctor/resolution side so we don't both write it.