[melvincarvalho]

Closes #54.

git mark announce (and --announce, and gitmark.announce true) now publishes two events with the trail key, to the same relays:

1. the repository announcement, kind 30617, unchanged;
2. the repository state, kind 30618: d, HEAD as ref: refs/heads/<branch>, one refs/heads/<name> tag per branch with its commit, and the mark as chain, txo, commit.

The state is replaceable, so the newest one from the key says where the repo is now. That is the sync signal for mirrors: subscribe to 30618 from the pubkey, pull when it changes, and check the named commit against the mark before trusting it. Only the key-holder can replace their own state, which is the one-writer rule.

Code: buildState in lib/announce.js beside buildAnnouncement, with the NIP-01 serialise-hash-sign step shared by both. The announce command publishes the state right after the announcement, with the same created_at, and prints State: kind 30618 … (n/m relays); only failing relays are listed a second time. The console keeps reading 30617 and shows nothing different.

Tested live from a cold-run agent repo: both events accepted by 3/3 relays, and the 30618 read back from relay.primal.net carries ["refs/heads/gh-pages", <sha>], HEAD, and the chain/txo/commit tags. The ref is one commit past the marked commit, which is the trail-file commit git mark adds after marking, so the two are correctly different.

Docs: README (Announce section and command table), SKILL.md, start.html step 3 and its check, index.html command table. 70 tests pass.

Not in this PR: the mirror side, forge pulling on 30618.

[Copilot]

🟡 Changes recommended

The refactor leaves an unused, redundantly-computed pubkey declaration in buildAnnouncement that should be removed, though the feature itself is correct and well-tested.

1 open issue

• Remove unused pubkey derivation in buildAnnouncement · New

What changed in this PR

This PR implements issue #54 by extending git mark announce to publish a NIP-34 repository state event (kind 30618) immediately after the existing repository announcement (kind 30617), using the same trail key, relays, and created_at. The 30618 event carries the d tag, HEAD, one refs/heads/<branch> tag per branch with its commit, and the latest mark (chain, txo, commit), giving mirrors a replaceable "where the repo is now" sync signal they can watch and verify against the on-chain mark. The event-building logic is refactored so both kinds share a single NIP-01 serialise/hash/sign helper (signEvent).

Changes:

• Added buildState and KIND_STATE (30618) in lib/announce.js, factoring the signing step into a shared signEvent helper.
• announce() in bin/git-mark.js now publishes the state right after the announcement, listing only failing relays and printing a State: kind 30618 … line.
• Added a unit test for buildState and updated docs (README, SKILL.md, start.html, index.html).

File	Description
lib/​announce.js	Adds buildState/KIND_STATE and extracts shared signEvent; leaves a now-unused pubkey declaration in buildAnnouncement.
bin/​git-mark.js	Imports buildState and publishes the 30618 state after the 30617 announcement, printing the new State: line.
test/​git-mark.test.js	Adds coverage for buildState tags, signature, and bare-case output.
README.md	Documents the new state event in the command table and Announce section.
SKILL.md	Updates the announce command description to mention the repository state.
start.html	Updates step 3 narrative and its Check for the new State: output line.
index.html	Updates the command table entry for git mark announce.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The change touches cryptographic event signing and the keyholder "one-writer" sync protocol, where subtle correctness issues warrant final human review despite the clean, well-tested diff.

No open issues 🎉

1 resolved since last review

• Remove unused pubkey derivation in buildAnnouncement

_{Review effort: Balanced}

[melvincarvalho]

Released in gitmark 0.0.84.