Ley del código compartido

Locks con TTL, orch:export como contrato de publicación, un índice nativo de símbolos y un gate de clones a la entrada.

Qué es#

Cuatro reglas que rigen dentro de una carpeta compartida registrada.

1. Toma el lock antes de editar. Una ruta compartida la tiene un solo holder a la vez:

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

El TTL es de quince minutos por defecto (--ttl-min, o ttl_min en la herramienta MCP), así que una terminal muerta no puede retener una carpeta para siempre. Los agentes usan lock_acquire / lock_release / lock_status / lock_check; liberar también reindexa la ruta y avisa a los pares.

2. Publica con una etiqueta. Un símbolo entra al registro compartido solo cuando su fuente lleva una línea de comentario, en cualquier lenguaje:

orch:export <Name> — <purpose>

Sin etiqueta no está en el registro, y search_shared_symbols responde únicamente con símbolos de alcance shared. La etiqueta es el contrato.

3. El índice ve todo de todas formas. Orchemax parsea cada archivo de un lenguaje que conoce — Go con go/ast, veintinueve lenguajes en total con sus reglas langspec — y guarda cada declaración como shared (etiquetada) o local (todo lo demás). No interviene ninguna herramienta externa de símbolos; cada resultado va marcado source: registry. La búsqueda sigue respondiendo solo shared, mientras que las consultas de grafo leen ambos, así que una función sin etiqueta deja de ser invisible para la herramienta cuyo trabajo es evitar que la escribas dos veces.

4. El gate de clones lee lo que estás por escribir.

orch guard dup <file>

Reporta cuerpos de función que el taller ya tiene en otra parte, y aparte deniega un archivo que duplica un símbolo compartido. El modo lo eliges tú en orch.yaml:

guard.dup.window, guard.dup.min_tokens y guard.dup.max_files ajustan con cuánta dureza busca.

5. Todo worker despachado pasa por el mismo gate. El comando de arriba es el que corres a mano; a un worker nunca hay que pedírselo. El gate corre en tres momentos, y un CLI que no soporte ninguno de los dos primeros tampoco pasa el tercero:

El escaneo compara los árboles de los proyectos y el worktree de cada sesión que sigue corriendo, así que dos workers escribiendo el mismo bloque al mismo tiempo se detectan mientras ambos están en vuelo. El mismo archivo visto desde dos checkouts de un mismo repo nunca es un duplicado de sí mismo.

Por qué existe#

Dos agentes editando el mismo archivo compartido al mismo tiempo producen un merge que te toca desenredar a medianoche. Dos agentes escribiendo el mismo helper en dos carpetas producen un duplicado que nadie nota en seis meses. Los locks resuelven lo primero; la etiqueta, el índice y el gate de clones resuelven lo segundo, en tres momentos distintos: cuando publicas, cuando buscas y cuando escribes.

Cómo se relaciona con el resto#

• Fuera de un taller vinculado todo esto se omite en suave. El modo suelto devuelve un mensaje de omisión, no un error.
• orch shared add <path> siembra etiquetas e indexa la carpeta mientras la registra, reportando seeded tags=… files=… scanned=… skipped_no_ast=… indexed=….
• orch symbols seed escribe las etiquetas orch:export faltantes desde el AST del lenguaje, para arrancar sobre un código ya existente.
• orch guard comment <shared-file> deniega un símbolo exportado sin comentario de propósito de una línea, y orch guard add-all deniega un git add -A general dentro de un repositorio compartido, donde se robaría el trabajo en curso de otra sesión.
• Lo que el índice habilita es el tema de Grafo de código.

Aquí no hay nada que ejecutar#

La ley rige corras o no algo: el registro se llena al registrar e indexar, y los guards disparan desde los hooks una vez que los conectas.