# spt-pacer-tool — agent working rules

> **Canonical source of truth for how agents work in this repo.** Harness-agnostic:
> Claude Code reads it via the one-line `CLAUDE.md` (`@AGENTS.md`); other harnesses read
> this file directly. Edit working rules HERE, never in `CLAUDE.md`.

`spt-pacer-tool` is a `kind = "shell"` spt-core adapter that keeps an autonomous agent from
silently stalling: while its **pacer latch** is raised, an idle **bound endpoint** is **ping**ed
back into motion after a quiet interval — unless the agent has declared a bounded or open-ended
wait. Pure inward nudge; never reports outward.

**Orientation — read before working:** `PACER-PLAN.md` (the current milestone's build path),
`CONTEXT.md` (glossary/model, authoritative for meaning), `docs/adr/` (decisions — esp. ADR-0001,
the one spt-core dependency), `docs/KNOWN-HAZARDS.md` (invariants we must not re-break),
`docs/{DOCS-STRATEGY,TRACEABILITY}.md`.

## Requirement traceability (binding)

This project uses [`traceable-reqs`](https://github.com/BigscreenVR/traceable-reqs)
(`traceable-reqs.toml` = the authoritative `REQ-*` registry). The full contract is
`docs/TRACEABILITY.md`. The rules you must follow:

1. **Tag evidence in the same change.** When you write a function/test/doc-section that
   satisfies a requirement stage, add its tag in that same commit:
   `// [impl->REQ-FOO]` · `// [unit->REQ-FOO]` · `<!-- [doc->REQ-FOO] -->`
   Stages: `doc` / `impl` / `unit` / `int`. Tag *on or immediately above* the real
   evidence — never at file tops to satisfy coverage.
2. **Run `traceable-reqs check` before declaring work done.** Exit-1 means missing/invalid
   evidence — fix it, don't ship it.
3. **New requirement → add it to `traceable-reqs.toml` first** (with a `REQ-*` id), then
   satisfy it. No untracked work; no untagged evidence.
4. **KNOWN-HAZARDS are `REQ-HAZARD-*` requirements** — each needs a test before it's
   "covered." Treat the hazard list as a conformance checklist you must satisfy, not advice.
5. **Activate, don't pre-fail.** Requirements you aren't yet working stay
   `required_stages = []`. Activate (set real stages) only when starting the milestone that
   delivers them.

## The published docs are the contract (read them first)

- **The spt developer docs are served node-locally at `http://localhost:5474`** (`spt docs
  url`; `spt docs` opens a browser). The chapters this project lives on: `shells/overview`,
  `shells/getting-started` (a worked shell adapter, end to end), **`shells/frames`** (the
  COMPLETE wire contract — frame types, attributes, the MAC stamp, the binding entity-decode
  order, the activity frame), `harness-contract/manifest` (field-by-field), `cli/reference`.
- **Read the relevant chapter BEFORE building, filing a finding, or asking another agent.**
  `--help` text is a summary, not the contract; a peer's recollection is not the contract.
  Every wrong claim this project has made about spt-core was already answered in these docs.
- **Cross-check against a shipping adapter** before inventing a pattern — `spt-shell-notify`
  (the documented example) and `spt-progress-tool` / alchemy (a real `kind = "shell"`
  adapter), plus the registered manifests under `~/AppData/Local/spt-core/adapters/`.
- Verify on the live node before reporting, and say plainly which claims are **observed**
  versus **read**. When a finding turns out to be our own rig or our own unread doc, correct
  the record immediately and in the other party's favor.

## Other conventions

- Match surrounding code style. pacer speaks only the **published** `spt api` surface and
  copies spt-core's **EVENT envelope wire format** and **manifest schema** *verbatim* (as
  `spt-shell-notify` does) — copy those, clean-room everything else. No spt-core crates, no
  source integration: the manifest + one resident binary are the only glue.
- Honor every `docs/KNOWN-HAZARDS.md` invariant — these are real bugs already paid for once
  (or hazards you have committed to never introduce). Each is a `REQ-HAZARD-*` with a test.
- Docs are dual-audience (human + AI dev-agent) per `docs/DOCS-STRATEGY.md`; doc generation
  is CI-gated against drift.
- Commit messages end with the project's co-author trailer:
  `Co-authored by: perri` (the live agent building this repo).

## Plans and context hygiene

- **JIT plans.** Plan the next immediate body of work just-in-time (a short `*-PLAN.md`),
  not the whole project up front. A plan names scope, open design questions, tasks, and the
  gate (build + `traceable-reqs check` green).
- If you finish a significant body of work without need for user intervention, or if your
  context gets too high, you can clear your own context and keep moving:
  1. Create a JIT plan for the next immediate body of work, if it isn't already planned.
  2. As a live agent: commune immediate next steps + a broad project-status/end-goal summary,
     then clear (the spt commune-across flow).