Legatura

Legatura is a local, agent-independent strong Harness for 1+n software development. A master supplies a Change Plan; Legatura turns durable repository structure into isolated, single-Module Works and returns a bounded account of what actually changed and which minimum Gates passed.

Project Model + Change Plan
            ↓
     inspectProject / runChange
            ↓
isolated Worktrees → replaceable Workers
            ↓
actual diffs → scope → minimum Gates
            ↓
       bounded Artifact

The product contract and acceptance criteria are in docs/PRD.md. Delivery status is tracked in PLAN.md, and canonical language lives in CONTEXT.md.

What the Harness owns

• a bounded, source-free Master Brief;
• Change Plan validation and topological execution waves;
• one Git worktree and immutable Work Baseline per Work;
• bounded Work Packs containing primary-Module Context and declared Contracts;
• actual Git diff observation and Module scope enforcement;
• automatic minimum-Gate routing and exact-diff freshness;
• retained Patches/workspaces and a bounded Change Artifact.

Workers remain free inside their Module's owned paths. They do not write proofs, select tests, or establish success by reporting it. Legatura is not an OS sandbox, application runtime, auto-merger, confidence scorer, or Crashbench system.

Install and import

Requires Node.js 22 or newer.

npm install
npm link

The package exports the Core and reference Adapters separately:

import { inspectProject, runChange } from "legatura";
import { createLocalCommandWorkerAdapter } from "legatura/adapters";

const brief = inspectProject("/path/to/repository");
const result = await runChange("/path/to/repository", changePlan, {
  worker: createLocalCommandWorkerAdapter({
    command: ["codex-worker", "--stdio"],
  }),
});

readChange re-observes retained workspaces before projecting prior results. verifyIntegration explicitly materializes all current Patches in a separate Integration Candidate, runs budget-deferred minimum Gates followed by full Gates, and never changes the default branch.

The Workspace Adapter contract in this MVP is deliberately local-path and Git-compatible. Replaceable Workspace Adapters must return a durable local directory, Git Work Baseline, observable diff, and repository-relative sealed Patch; opaque remote persistence is a later Interface, not an accidental promise of this release.

Four-command CLI

Inside an existing Git repository:

legatura init --module app=app --module apk=apk --module relay=relay

Edit and commit .legatura/project.json, then use:

legatura check
legatura inspect --json > master-brief.json

legatura run change-plan.json \
  --worker-command-json '["codex-worker","--stdio"]' \
  --json

LEGATURA_WORKER_COMMAND_JSON may replace the CLI option. run --integrate explicitly runs full Gates in an Integration Candidate after all minimum-verified Works pass. inspect --change <id> rechecks freshness before rendering a retained Change.

The low-level prototype commands atlas, plan, context, verify, and show are intentionally gone; Hosts call the Core lifecycle rather than reconstructing it.

Change Plan

A Change Plan contains intent and Work relationships, never compiled policy or results:

{
  "schemaVersion": 1,
  "expectedBaseline": "0123456789abcdef0123456789abcdef01234567",
  "intent": "Show relay reconnecting state in app and apk",
  "works": [
    {
      "id": "relay-status",
      "module": "relay",
      "goal": "Expose and implement reconnecting",
      "dependsOn": [],
      "focusPaths": ["relay/src/state.mjs"],
      "contractChanges": ["relay/CONTRACT.md"]
    },
    {
      "id": "app-status",
      "module": "app",
      "goal": "Render reconnecting",
      "dependsOn": ["relay-status"],
      "focusPaths": ["app/src/view.mjs"],
      "contractChanges": []
    }
  ]
}

expectedBaseline binds the plan to the Master Brief. focusPaths only hint which owned Implementation is relevant. contractChanges explicitly authorizes intended public Contract changes. Set observationOnly: true only when an empty diff is expected.

Project Model

The versioned syntactic schema is schemas/project-model.v1.schema.json. Core remains authoritative for repository-dependent and cross-reference rules such as ownership overlap, Contract existence, and dependency closure. A minimal model declares Modules, owned paths, Contracts, dependency edges, and reusable Gates:

{
  "schemaVersion": 1,
  "name": "sample",
  "budgets": {
    "masterBriefBytes": 16384,
    "contextBytes": 32768,
    "contextFiles": 64,
    "artifactBytes": 12288,
    "gateOutputBytes": 4096,
    "minimumGateMs": 600000,
    "parallelWorks": 4
  },
  "modules": [
    {
      "id": "app",
      "summary": "User-facing application",
      "owns": ["app/**"],
      "context": ["app/README.md", "app/src/**"],
      "contracts": ["app/CONTRACT.md"],
      "dependsOn": [
        { "module": "relay", "contract": "relay/CONTRACT.md" }
      ],
      "minimumGates": [
        {
          "name": "app behavior",
          "run": ["node", "--test", "app/gates/behavior.mjs"],
          "appliesTo": ["app/**"]
        }
      ]
    }
  ],
  "fullGates": [
    { "name": "integrated product", "run": ["npm", "test"] }
  ]
}

The app/apk/relay walking fixture is in examples/app-apk-relay. It demonstrates a relay Work followed by concurrent app/apk Works, updated Contract delivery, minimum Gates, and an explicit full integration Gate.

Stdio JSON Host

legatura-host accepts newline-delimited JSON and emits one response per request:

{"id":"1","method":"inspectProject","repository":"/repo"}
{"id":"2","method":"runChange","repository":"/repo","changePlan":{},"workerCommand":["worker"]}

The Host only translates transport. Project Model, scope, Gate, freshness, and Artifact semantics remain in Core.

Worker Adapters

The stable Worker seam and needs-context retry protocol are documented in docs/worker-adapters.md. A Worker receives a normal Git worktree as its working directory; Context exclusion controls deliberate delivery, not hostile-process file access.