Skip to content

footprint

Provenance

  • Source: .spec/spexcode/spec-cli/footprint/spec.md
  • Source SHA-256: 87b454f8c980e931300588aa5dfb97f75075f1f79581b0140741289c6eaa13f4

raw source

SpexCode claims software engineering's HEAD — the recording of intent — and its TAIL — the storage of measurement — and deliberately leaves the MIDDLE, construction, to the harness/agent/test framework; freshness stitches the two ends into a closed loop. That position sizes the footprint: what SpexCode plants in a host is the head+tail ASSET (the spec tree and its readings, tracked like any source) plus the derived wiring that reaches an agent — and nothing of the middle.

SpexCode is always a guest — on a user's machine, in an existing repo, inside an agent the user launched themselves. A guest's footprint must be one deliberate lifecycle: arrive as a single installable unit, plant only identifiable artifacts, be able to prove the delivery actually reached the agent, and back out leaving nothing behind. Read flat, these look like unrelated commands; read together they are one contract: SpexCode never silently pollutes an environment it does not own.

expanded spec

The lifecycle's stations, each owning its own detail:

  • [[packaging]] — arrival on a machine: one npm package puts one spex on PATH, carrying the runtime subset with the monorepo layout preserved, no build step on the user's box.
  • [[spex-init]] — adoption by a repo: the seed spec tree, git hooks, and starter config, planted as copied data (never code-embedded strings), additive and never destructive.
  • [[residence]] — residence in the repo, vote-less: spec data always tracked, machine facts never, run residue out-of-tree, materialized artifacts NEVER tracked (per-clone exclude; the clean/smudge filter for a mixed contract file). Every planted artifact's visibility follows its KIND — and a contract file's kind is a live content fact. History is guarded and freshness anchored by [[commit-surgery]]'s git-native hooks; no harness event ever triggers a materialize.
  • [[doctor]] — the project-wide read-only diagnosis surface; this lifecycle contributes its delivery audit: is this agent actually governed, or silently running free? Under-delivery and double-delivery are both caught, with the repair printed.
  • [[spex-uninstall]] — departure: materialize(∅) plus the store — every generated artifact removed by its identity stamp, the user's own .spec/.plugins data and prose never touched.

The shared invariant that makes this one node: every footprint artifact is stamped, visible, and reversible — planted as data, diagnosable in place, and removable only by proof of our own authorship. A concern about what the tool does belongs elsewhere; a concern about where the tool lives belongs here.