repo/ops: .work gitignore hides the multi-machine control surface — track loop prompts + operating procedures, codify the state boundary

[kyle-sexton]

Category: structural · Source: control-tower work-quality audit 2026-07-19 (Opus auditor)

Problem — the multi-machine control surface is gitignored

.work/.gitignore = * makes everything under .work/ local scratch — including leave-week-priorities/loop-prompts/terminal-*.md (the canonical lane prompts) and operating-procedures.md (roles/rituals/protocols). But these are the durable control surface for a MULTI-machine pipeline (#502 MACHINE-BEHAVIOR confirms lanes on melo-lap-001 while the files live on the desktop). The documented ritual "laptop git pull + restart with current canonical prompts" cannot actually work: git pull carries none of these files.

Proposed boundary rule

Anything a second machine, a fresh session, or an auditor must read = tracked repo or GitHub. .work/ = disposable per-session scratch only.

Concretely: move loop prompts + operating procedures to a tracked path (e.g. ops/loop-prompts/, ops/operating-procedures.md — naming open), leave session-scoped artifacts (handoffs, interview ledgers, day plans) in .work/. Decide per file at move time; default tracked when in doubt about multi-machine need.

Consequences

• Prompt-versioning ritual gains real distribution (file change → commit → laptop pull → restart) instead of the current copy-paste-only path.
• Prompt changes become PR-able and reviewable — the same pipeline that ships skill changes can ship prompt changes (dogfood; interacts feat(claude-ops or session-flow): loop-prompt authoring skill — generate and maintain standing loop-lane prompts #480 loop-prompt authoring skill and loops/autonomy: lanes cannot consume their own merged plugin fixes — need plugin sync + reload path (or documented restart cadence) #514 self-update).
• Telemetry/audit artifacts referenced from GitHub comments must never point at local scratch paths (loops: script the deterministic lane mechanics — machine-behavior block, #502 telemetry upsert, wire script-the-deterministic-work into prompt ritual #538's dead-pointer finding is the same boundary violated in the other direction).

Relations

#496 (context economy — GitHub-externalized state principle, this is its filesystem corollary), #480, #514, #538.

---

Operator decision (2026-07-19 interview)

Move approved as INTERIM ONLY. The destination path used for the interim move is explicitly temporary — a momentum measure, not a convention. Before any final location/convention is locked:

1. Run the full convention gauntlet: melodic-software/standards (engineering philosophy, review + design criteria), the plugin philosophy + plugin migration guide (if this lands in a plugin, it must be extensible/configurable/modular per those docs), and external research into prior art for agent-agnostic prompt-file conventions (e.g. a .prompts/ directory, AGENTS.md-ecosystem conventions) — official/authoritative sources, cited.
2. Present options + RECOMMENDED to the operator; the convention locks only on explicit human approval. Conventions are expensive to pull back; automated convention-setting is prohibited.
3. Until then the interim path carries a marker note declaring it temporary and pointing here.

This decision pattern (interim unblock + tracked convention decision + human sign-off) is the template for all future convention-shaped choices.

[kyle-sexton]

This was generated by AI during triage.

Pre-planning enrichment — convention gauntlet run (final location NOT decided; needs human sign-off)

Per the operator decision in the body: the INTERIM move is approved, but the FINAL location/convention locks only on explicit human approval. This comment runs the full convention gauntlet (standards + PLUGIN-PHILOSOPHY + external prior art, cited) and presents options with a RECOMMENDED. The recommendation is not a decision — per the standing rule that convention-shaped choices require human sign-off and automated convention-setting is prohibited.

Interim-move status: NOT yet executed (verified 2026-07-19)

Code search confirms no tracked operating-procedures.md, no terminal-*.md, no ops/, and zero tracked references to leave-week-priorities anywhere in the repo. .work/ is still fully gitignored. So the interim relocation has not happened yet — see the "ready-shaped interim work" note at the end.

---

Decision brief (2-minute read)

Problem. The durable multi-machine control surface (canonical lane prompts loop-prompts/terminal-*.md, operating-procedures.md) lives under .work/ whose .gitignore = * makes it local scratch. A second machine's git pull carries none of it, so the documented "laptop pull + restart with current canonical prompts" ritual cannot work. Where these files should durably live — and under what convention — is open.

Today. This repo is a dual-hat repo: it is both the plugin-marketplace publisher and a consumer project that runs /loop lanes. It already tracks consumer-hat agent config at the root — AGENTS.md, CLAUDE.md, .claude/settings.json — but the loop prompts and operating procedures sit in gitignored .work/, so they are the one part of the control surface that does not travel with a clone.

The decisive discriminator (from our own standards). The loop-prompt instances and operating-procedures.md are org/machine/week-specific operational content (they name lanes, machines like melo-lap-001, week directives). docs/PLUGIN-PHILOSOPHY.md is explicit on where that class belongs:

• Config-ownership table: "Tracked repository convention or rich team policy → A documented file under the consumer project." That is exactly this class.
• Plugin design boundary: a plugin "must work outside the repository and organization that produced it… runtime behavior must not depend on publisher names, organization-specific environment variables, repository names, absolute machine paths." Org/machine/week-specific prompt content structurally cannot live inside a distributable plugin without violating this.
• standards code-organization: "One consumer — co-locate the code with its consumer. No shared location." These prompts have exactly one consumer (this repo's own operation), so they co-locate here rather than being promoted into the distributable plugin tier.

Keep the #480 distinction intact. #480 (loop-prompt authoring skill) is plugin-appropriate — a reusable capability. The prompt instances this issue moves are consumer-project config. Tooling → plugin; content → repo. Do not conflate.

External prior art (official sources, verified 2026-07-19).

• AGENTS.md is the one agent-agnostic, cross-tool standard, stewarded by the Agentic AI Foundation under the Linux Foundation, adopted by 20+ tools (Codex, Cursor, VS Code, Copilot, Jules…). But it is a single file at the repo root (nearest-wins in monorepos) — it does not sanction a directory of prompt files. https://agents.md/
• Directory-of-prompt conventions exist but are all tool-specific: .github/prompts/*.prompt.md (VS Code/Copilot, https://code.visualstudio.com/docs/agent-customization/prompt-files), .cursor/rules/*.mdc (Cursor, version-controlled, https://cursor.com/docs/rules), .claude/{rules,commands,agents,skills}/ (Claude Code, https://code.claude.com/docs/en/claude-directory). There is no authoritative agent-agnostic directory convention to inherit for a multi-file prompt set.
• Tracked-vs-gitignored boundary (official git): a .gitignore is for "files that all developers will want to ignore… version-controlled and distributed"; shared config that every clone must read is simply tracked. https://git-scm.com/docs/gitignore . Note the failure mode this issue fixes: a dot-directory (.work/) got gitignored and hid the surface.

Options (RECOMMENDED first)

• RECOMMENDED — Repo-root plain ops/ directory, tracked (ops/loop-prompts/terminal-*.md, ops/operating-procedures.md). Consumer-project config placed under the consumer project, per the PLUGIN-PHILOSOPHY config-ownership row — the on-point internal standard. A plain, non-dot directory is unambiguously tracked and visible; it structurally cannot repeat this bug's failure mode (a dotdir silently swept into gitignore). No authoritative agent-agnostic directory convention is overridden by choosing this, since AGENTS.md is single-file and every dir-of-prompts convention is tool-specific. Reversible: it is a path move under version control. Sub-option for the operator: the "how agents operate here" portion of operating-procedures.md overlaps AGENTS.md's purpose; folding that specific file (or a pointer) into the existing root AGENTS.md — the agent-agnostic standard — instead of ops/ is a legitimate variant, operator's call.

• Tracked dot-directory — .claude/ (tool-native) or a new .prompts/ (AGENTS.md-adjacent). Aligns with the tool-specific conventions above and keeps agent config together under .claude/. Against: the bug being fixed is precisely a gitignored dotdir hiding the surface; another dotdir reintroduces the exact tracked-vs-ignored ambiguity a plain ops/ avoids. .prompts/ has no authoritative backing (AGENTS.md is single-file, not a .prompts/ dir). Viable but carries the ambiguity that caused this.

• Plugin-owned reference docs (claude-ops / session-flow / autonomy). REJECTED on the plugin design boundary: the content is org/machine/week-specific, so placing it inside a distributable plugin violates PLUGIN-PHILOSOPHY's "must work outside the repository and organization that produced it" and its ban on repo-name/machine-path/org-specific runtime dependencies. (This is the home for feat(claude-ops or session-flow): loop-prompt authoring skill — generate and maintain standing loop-lane prompts #480's authoring skill, not for the prompt instances — see the feat(claude-ops or session-flow): loop-prompt authoring skill — generate and maintain standing loop-lane prompts #480 distinction above.) Named and evaluated so the boundary is on record, not silently dropped.

Decision asked. Approve the final convention: RECOMMENDED = repo-root plain ops/ (with the AGENTS.md sub-option for the procedures file), or pick the dot-directory alternative, or send back for more options. Accept / modify / reject — the convention locks only on your explicit sign-off.

---

Ready-shaped interim work (already operator-approved, independently actionable now)

The INTERIM move itself is already approved in the body and does not wait on the convention decision above. A picker can execute it now: relocate .work/leave-week-priorities/loop-prompts/terminal-*.md and operating-procedures.md out of gitignored .work/ to a tracked interim path, carrying a marker note that declares the path temporary and points back to this issue (per body item 3). That path is a momentum measure, not the convention — whoever executes it must not treat the interim location as the locked convention, and this comment does not lock it. The final convention above remains gated on human sign-off.

Recommendation only — not a decision. Convention-setting requires explicit human approval.

[kyle-sexton]

Curation pass 2026-07-20 confirms the concern: .work/.gitignore = * hides the entire control surface (loop-prompts/, operating-procedures.md, priorities-summary.md, back-at-work-runbook.md). Recommend this issue own the keep/track boundary before any .work archive sweep runs, so tracked-worthy control files graduate to git rather than being archived as scratch. (Two untracked docs/topics Briefs found at risk in the same pass were committed via PR #776.)