Shared code law

Locks with a TTL, orch:export as the publish contract, a native symbol index, and a clone gate on the way in.

What it is#

Four rules that apply inside a registered shared folder.

1. Lock before you edit. A shared path is taken by one holder at a time:

orch lock acquire shared/go/billing --holder <session>
orch lock status
orch lock release shared/go/billing --holder <session>

The TTL defaults to fifteen minutes (--ttl-min, or ttl_min on the MCP tool), so a killed terminal cannot hold a folder hostage forever. Agents use lock_acquire / lock_release / lock_status / lock_check; a release also reindexes the path and notifies peers.

2. Publish with a tag. A symbol enters the shared registry only when its source carries one comment line, in any language:

orch:export <Name> — <purpose>

No tag means not in the registry, and search_shared_symbols answers with shared-scope symbols only. The tag is the contract.

3. The index sees everything anyway. orch parses every file in a language it knows — Go through go/ast, twenty-nine languages in total through their langspec rules — and stores each declaration as shared (tagged) or local (everything else). No external symbol tool is involved; every hit is labelled source: registry. Search still answers shared only, while graph queries read both, so an untagged function is no longer invisible to the tooling whose job is to stop you writing it twice.

4. The clone gate reads what you are about to write.

orch guard dup <file>

It reports function bodies the workshop already has elsewhere, and separately denies a file that duplicates a shared symbol. Its mode is yours to pick in orch.yaml:

guard.dup.window, guard.dup.min_tokens and guard.dup.max_files tune how hard it looks.

Why it exists#

Two agents editing the same shared file at the same time produce a merge you get to untangle at midnight. Two agents writing the same helper in two folders produce a duplicate nobody notices for six months. Locks solve the first; the tag, the index and the clone gate solve the second, at three different moments — when you publish, when you search, and when you write.

How it relates to the rest#

• Outside a bound workshop all of this soft-skips. Loose mode returns a skip message, not an error.
• orch shared add <path> seeds tags and indexes the folder as it registers it, reporting seeded tags=… files=… scanned=… skipped_no_ast=… indexed=….
• orch symbols seed writes missing orch:export tags from the language AST, to bootstrap an existing codebase.
• orch guard comment <shared-file> denies an exported symbol that has no one-line purpose, and orch guard add-all denies a blanket git add -A inside a shared repo, where it would steal another session's work in progress.
• What the index enables is the subject of Code graph.

Nothing to run here#

The law applies whether or not you run anything: the registry is populated by registration and indexing, and the guards fire from hooks once you wire them.