Pickup contract for agents working on HeavyMap. Read this before opening an issue or a pull request. Spreadsheet hygiene is in AGENTS-MCS.md.
Status: agent pickup source of truth. Linear NA-13. Docs only.
Product: HeavyMap — industrial intelligence for cross-border Niagara.
Control plane: Linear project Industrial Atlas (priority, status, Agent packets).
Code source of truth: this repository, niagaraassembly/heavymap.
Beta is the repository top level. The original niagara-atlas/ prototype is prior-art reference only; it is archived at first-attempts/niagara-atlas/.
Before finishing any session or pull request, every agent appends its process insights (sources found, dead ends ruled out, data quirks, method findings, effort estimates, gaps, licence notes) as new rows in Spreadsheets/19-process-insights.csv, with live-verified evidence (URLs, counts, dates checked). The rows feed HeavyMap’s published synthesized reports, so log dead ends and search scope too. Append only; never edit another session’s row except its status or linked_issue. Agents that cannot write to the repo report them in their final message under the heading Process insights so a human or Grok Bot can log them. Columns, the insight / issue / decision split and etiquette: heavymap-planning/PROCESS-INSIGHTS.md.
The product frame lives under docs/architecture/ (Linear NA-11):
| Concept | Document |
|---|---|
| Parcel Identity Spine | parcel-identity-spine.md |
| Context Band Ladder | context-band-ladder.md |
| Parcel Context Display Protocol (PCDP) | PCDP.md |
| Claim & Refusal Contract | claim-refusal-contract.md |
Under that frame, the Master Control Spreadsheet records which datasets exist, and D-5 names a dataset’s disposition: ship, simplify, derive, tile, or link. Neither is a fifth product name. The spreadsheet itself is outside this repo; see AGENTS-MCS.md.
Work an issue only when all of these are true:
agent-ready.agent:cloud, agent:claude, agent:copilot, agent:cursor, agent:kiro, or agent:codex.If any item is missing, comment on the issue and stop. Leave the scope as written. agent-ready is applied by Morgen or the Chief of Staff.
Prefer one Cloud Agent, plus follow-ups on that same run, for a documentary task. Cite the Linear ID (NA-…) in the pull request body.
Ordinary HeavyMap work stays in Linear. Open a GitHub pull request for the change. A GitHub issue is not the tracker for that work.
| Actor | Lane | Does |
|---|---|---|
| Morgen | — | Decisions, merges, secrets |
| Chief of Staff | — | Routing, packet quality, agent-ready |
| Cursor Cloud Agent | agent:cloud |
Documentary and multi-file investigation pull requests |
| Cursor interactive | agent:cursor |
Ambiguous product calls with a human in the loop |
| Claude | agent:claude |
Planning, normalize drafts, later UI |
| Copilot | agent:copilot |
A gated packet turned into a draft pull request |
| Kiro | agent:kiro |
Specialized process work |
| Codex (CLI on Deb) | agent:codex |
Individual research/writing tasks as well as technical coding tasks; run with </dev/null; output returned via files/PR/Linear comment by a human or Deb-side session; coding tasks return as a branch/PR for human review (works on a branch and opens or hands back a PR; never merges) |
Codex may not reach Linear directly, so the human (or Deb-side session) posts its pickup and result comments. It names its Linear issue and never posts, sends or merges on its own. It takes individual research/writing tasks as well as technical coding tasks. For coding tasks, Codex works on a branch and opens or hands back a PR for review; it never merges. Coding tasks return as a branch/PR for human review.
Framework labels (fw:pcdp, fw:spine, fw:bands, fw:claims) and work-kind labels (data-prep, protocol, docs, assessment) name the packet. They do not replace agent-ready or the lane.
Cite first-attempts/niagara-atlas/ and the UK atlas (babbworks/atlas) as baselines. The product root is the top level of this repository. UK geography is outside product scope. A UK capability pattern belongs in the MCS column uk_analogue, as described in AGENTS-MCS.md.
The public site stays unpublished until data is reconciled. UI chrome stays deferred. Architecture docs may still specify PCDP surfaces (selection, dossier, share, export) without shipping a map.
Never commit secrets, tokens, or credential files. If you find one, report the path and the type, and stop. A human revokes it.
Linear packets use this shape:
## Agent packet
- **Assignee agent:** Copilot | Cursor | Cloud Agent | Claude | Kiro | Codex | human
- **Lane label:** `agent:…`
- **Repo:** `niagaraassembly/heavymap` (paths: …)
- **Framework:** PCDP | Spine | Bands | Claims | (n/a)
- **Outcome:** …
- **Out of scope:** …
- **Acceptance checks:** …
- **Prior-art posture:** baseline-reference-only | allowed to modify code | docs-only
- **Links:** AGENTS-MCS.md, docs/architecture/, related issues
.cursor/environment.json runs scripts/cloud-install.sh (Python check, byte-compile, python3 -m unittest discover -s tests, python3 scripts/check_index_paths.py) and scripts/cloud-start.sh (nothing to start). Stdlib only; nothing to install.Spreadsheets/19-process-insights.csv (see Process insights above). Never pull data into the repo; the VM is disposable, so record facts not rows..agents/skills/: heavymap-pcdp, heavymap-dataset-profiling, untrusted-web-text. Rules in .cursor/rules/.