docs(agents): record the #517 tracker-of-record rule in root AGENTS.md and the workflow claim protocol

@0monish

Generated by an AI agent (Claude Code) on behalf of @0monish during the 2026-10-07 repair of the Electron compatibility map. Planning only — no implementation is authorized by this issue.

Parent

Map #391 · Program unit X06 (program structure) · Kind: task (agent-instruction change) · Milestone: first-proof · Implements the owner decision #517 (X06-D7, closed 2026-10-07)

What to build

An agent that follows the repository's own instructions can claim, work and hand off a ticket whose tracker of record is a GitHub issue, without contradicting root AGENTS.md or docs/agents/workflow.md.

Today both files assume Linear is the only tracker (FACT, origin/main b4b907c):

Root AGENTS.md, Ground truth: "Features require an approved docs/agents/spec-template.md spec plus Linear (KELD)."
docs/agents/workflow.md, loop step 1: "Fetch the Linear issue (team KELD, current milestone first)"; "The earliest claim by Linear's own createdAt wins".
docs/agents/workflow.md, Agent claim: "Ownership is therefore declared in Linear before work starts"; worktree and branch names use kel-<n>.

The owner decided on #517 that new work which no live Linear issue covers is tracked on its GitHub issue, because the workspace is at its Free-plan issue cap, and that the nearest live Linear issue carries a link to it. Until the instructions say so, an agent that follows workflow.md must refuse a GitHub claim. That gates every GitHub-tracked ticket on this map that writes to the repository. Each such ticket carries a native blocked-by link to this issue, either directly or through one of its blockers.

Proposed exact text (draft for owner approval; the PR may tighten wording, not scope)

Root AGENTS.md, Ground truth (replaces the "Features require" sentence):

Features require an approved docs/agents/spec-template.md spec plus a tracker of record: Linear (KELD), or the GitHub issue when no live Linear issue covers the work (owner decision #517).

docs/agents/workflow.md, new paragraph directly after the Agent claim template:

GitHub tracker of record (#517). When no live KELD Linear issue covers a work item and Linear cannot take a new issue, the item's GitHub issue is its tracker of record. Steps 1–7 apply with that GitHub issue in place of the Linear issue. The ## Agent claim block is its first work comment; the earliest claim by GitHub's comment created_at wins; progress, OS-acceptance and handoff comments go there; worktree and branch use gh-<n>-<slug>. The nearest live Linear issue carries a link to the GitHub issue, and a claim posted only on that Linear issue does not win the GitHub-tracked work.

Acceptance criteria

The single-writer designation this change needs is recorded with its comment id. Either the owner designates root AGENTS.md (shared:root-agents, which KEL-124 explicitly withholds) and docs/agents/workflow.md (shared:agent-workflow, designated to KEL-124, In Progress, unassigned; Linear, fetched 2026-10-07), or KEL-124's writer accepts the change as a scoped handoff on KEL-124.
Root AGENTS.md and docs/agents/workflow.md state the rule once, with one owner (workflow.md owns the claim mechanics; root names the tracker of record only).
The change record follows .agents/instructions.md: owner, load class, exact trigger, byte/token delta of the always chain, representative eval, rollback. just agent-context passes, with actual output reported.
just llms-check passes, regenerating with just llms only if an included source changed. Format, warning-denied workspace clippy and workspace tests are run and reported per the verification floor.
Linear stays the default tracker. No text permits creating Linear issues past the cap or claiming on two trackers at once.

Negative controls (each names the one mutation that must fail)

In the representative eval, a claim posted only on the nearest Linear issue for a GitHub-tracked ticket is accepted as winning, and the eval fails.
Deleting the new workflow.md paragraph makes the representative eval fail: the agent refuses the GitHub claim.
Raising the always-chain bytes without the recorded delta makes just agent-context fail (existing gate).

Ownership and gates

Tracker of record: this GitHub issue. Nearest live Linear issues: KEL-124 (owns shared:agent-workflow; In Progress, unassigned) and KEL-31 (Linear conventions; In Progress, GYLDLAB). Both carry a link to this issue.
Blocking edges: none, so it can start once the single-writer designation exists.
Review gates: none of the five product gates. It is an agent-instruction change under .agents/instructions.md.
Platforms: none (docs/process only).

The authoritative agent contract is the latest Agent Brief comment on this issue (triage skill); this body is the planning record.

Out of scope

Any other instruction move (KEL-124 owns the one-rule/one-owner inventory). Prompt Tracker chrome. Linear plan or capacity changes. Product code.

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Record the #517 GitHub tracker-of-record rule in root AGENTS.md and the docs/agents/workflow.md claim protocol

Current behavior:
The repository's instructions define Linear as the only tracker. Root AGENTS.md requires "an approved spec plus Linear (KELD)". The workflow loop fetches "the Linear issue", declares the ## Agent claim "in Linear", and lets the earliest Linear createdAt win. An agent that follows them must refuse to claim a ticket whose tracker of record is a GitHub issue under the owner decision #517.

Desired behavior:
The instructions state the #517 rule once. When no live KELD Linear issue covers a work item and Linear cannot take a new issue, its GitHub issue is the tracker of record, and the loop runs unchanged against that issue. The claim is its first work comment, and the earliest GitHub comment created_at wins. Progress, OS-acceptance and handoff comments go on the GitHub issue, and branches and worktrees are named gh-<n>-<slug>. The nearest live Linear issue links to the GitHub issue, and a Linear-only claim does not win GitHub-tracked work. Linear remains the default tracker.

Why this needs a human: root AGENTS.md (shared:root-agents) and docs/agents/workflow.md (shared:agent-workflow, designated to KEL-124) are single-writer files. The owner must designate them for this change, or KEL-124's writer must accept it as a scoped handoff. The owner also approves the exact always-loaded text. After that, an agent can draft and verify the PR.

Key interfaces:

The root AGENTS.md "Features require ..." sentence in Ground truth: names the tracker of record
The docs/agents/workflow.md loop step 1 and the ## Agent claim section: the GitHub-tracked variant of pick-up, claim, win and handoff
The .agents/instructions.md change record: owner, load class, trigger, byte/token delta, eval, rollback

Acceptance criteria:

The single-writer designation, or KEL-124's handoff acceptance, is recorded with its comment id
The rule appears once; workflow.md owns the claim mechanics and root names only the tracker of record
The .agents/instructions.md change record is complete, and just agent-context passes with output reported
just llms-check passes; format, warning-denied workspace clippy and workspace tests are reported per the verification floor
Linear stays the default tracker, and no text permits issue creation past the cap or dual-tracker claims
Negative control: in the representative eval, a Linear-only claim on GitHub-tracked work is not accepted as winning
Negative control: removing the new workflow.md paragraph makes the representative eval fail

Out of scope:

Any other instruction move (KEL-124's inventory)
Prompt Tracker chrome, Linear plan or capacity changes, product code

@0monish

Generated by an AI agent (Claude Code, Opus 5.5) on behalf of @0monish and posted from the @0monish GitHub account. This first work comment follows docs/agents/workflow.md step 1 on the GitHub issue, under the #517 rule that this change records.

Agent claim

Agent: claude-code
Device: CENTILLIONAIREs-Mac-mini.local (macOS 26.5.1)
Model/effort: claude-opus-5-5@max
Repo: gyldlab/keld
Worktree: .keld-work/worktrees/docs(agents): record the #517 tracker-of-record rule in root AGENTS.md and the workflow claim protocol #520-tracker-of-record
Branch: agent/docs(agents): record the #517 tracker-of-record rule in root AGENTS.md and the workflow claim protocol #520-tracker-of-record
Expected paths: AGENTS.md, docs/agents/workflow.md, .agents/index.md, docs/agents/spec-template.md, .github/PULL_REQUEST_TEMPLATE.md, tools/workspace.py, tools/test_workspace.py, tools/session_closeout.py, tools/test_session_closeout.py, .codex/hooks.json, docs/onboarding/05-development-guide.md, docs/architecture/01-overview.md, llms.txt and llms-full.txt (generator output only)
Single-writer files/keys needed: shared:root-agents and shared:agent-workflow. The repository owner @0monish designated both to this issue on 2026-10-07 with the in-session instruction "update the agents md with the new working style so that they wont hinder your work". KEL-124 holds shared:agent-workflow; its last claim expired 2026-09-03, and no claim on it is unexpired (Linear, fetched 2026-10-07). A coordination notice is posted on KEL-124.
Claim expires: 2026-10-07T20:30:00Z
OS acceptance owned: none

OS acceptance

Every criterion is CI-only: agent documentation, process contract and local tooling. No real OS/device observable applies.

Scope, non-goals, dependencies

Scope. One rule with one owner. A work item whose tracker of record is its GitHub issue (Linear owner for repo-writing Electron-compat slices (owner decision: align to nearest Linear issue, else GitHub is the tracker of record) #517) runs the same loop on that issue. The tools that enforce kel-<n> / KEL-n today accept the GitHub form for task trees (tools/workspace.py) and closeout receipts (tools/session_closeout.py). The .codex/hooks.json pins are regenerated.
Non-goals. Linear stays the default tracker. No Linear capacity change. No other instruction moves; KEL-124 owns that inventory. No change to the five review gates or the merge delegation. tools/product_status.rs stays deferred: no ledger row cites a GitHub-tracked item yet. Its fix is to accept GH-<n> beside KEL-<n>, sorting KEL first, with a GH fixture.
Dependencies. None open. Inventory: 24 sites read on origin/main 80143cd. Pin delta from the issue's b4b907c: four commits (feat(update): typed Machine-UAC recovery-required startup state (KEL-270 T4d S2) #385, feat(core): boot the authenticated Windows installed package (KEL-254 T3 Part B) #390, ci: suppress the electron-compat wayfinder prose gitleaks false positive #513, ci: allowlist the secret-store prose value in gitleaks instead of per-commit fingerprints #519), none touching these paths. Open PR docs(learnings): shared-target false green and elevated PowerShell resolution (KEL-270) #512 changes one .agents/instruction-budget.tsv row; this change does not edit that file.
First falsifiable acceptance check. At head, just work-start gh-520 probe allocates a tree in the test fixture; gh-0, GH-1 and jira-1 are rejected. At baseline, the same call exits with Invalid issue.

Decision-bearing atoms

Tracker issue definition. Owner docs/agents/workflow.md § Tracker issue. Input: Linear coverage and capacity. Output: exactly one tracker issue per item. Failure: an item claimed on two trackers, or a refused claim. Falsifier: a fresh-context eval at head claims on GitHub for an uncovered item; with the paragraph deleted, it refuses.
Root floor. Owner root AGENTS.md: "spec plus a tracker issue". Bound: 13,312 bytes. Falsifier: just agent-context.
Claim ordering. Owner workflow.md: the earliest claim by the tracker issue's own comment timestamp wins, and a claim posted only on the Linear reference issue does not. Falsifier: an eval in which a competing Linear-only claim must not win.
Task naming. Owner tools/workspace.py. Falsifier: unit tests (gh-520 accepted; gh-0, GH-1, jira-1 rejected).
Closeout receipts. Owner tools/session_closeout.py: GH-n bound to https://github.com/gyldlab/keld/issues/n. Falsifier: tests for a mismatched number, a wrong repo, and a GH id with a Linear URL.
Hook pins. Owner .codex/hooks.json. Falsifier: tools/test_session_closeout_hook.py.
Linear default preserved. Falsifier: an eval in which a Linear-covered item still claims on Linear with kel-<n>.
Pinned and budgeted text. Falsifier: just atomic-protocol, just agent-context and just llms-check.

Independence: atoms 4–6 are code with their own tests. Atoms 1, 3 and 7 share one paragraph but are falsified by separate eval scenarios. Atom 8 bounds 1–2.

Change record (`.agents/instructions.md` § Required change record)

Owner and consumers. Owner: docs/agents/workflow.md, a new § Tracker issue (routed, route:implementation-or-coordination). Consumers: root AGENTS.md (one phrase, always); the .agents/index.md trigger "Using Linear" becomes "Using an issue tracker". Every routed playbook that says Linear is covered by the owner's "here and in routed playbooks" clause, with no per-file copies. The spec and PR templates get placeholder hints only.
Bytes. AGENTS.md 13,305 → ≤13,312 (no cap change). workflow.md 16,353 → ≤16,384, offset by retiring three passages that mirror other owners: root's five-gate list, .agents/ci.md's PR-heading list, and .agents/ci.md's apt-get rule. index.md 4,056 → ≤4,096. Tokens: tiktoken 0.12.0 o200k_base, before/after in the PR. instruction-budget.tsv is unchanged.
Reused owner and rejected alternatives. Workflow already owns lifecycle and claims (.agents/coordination.md line 3). Rejected:
- (a) a GitHub copy of step 1: it duplicates atom sentences that just atomic-protocol pins as unique;
- (b) raising budgets;
- (c) rewording every Linear mention in every playbook, which would mean seven owners;
- (d) waiting for KEL-124's writer: there is none active, and the owner designated this change.
Evals. Four scenarios, each run at baseline, at head, and at head with the paragraph deleted (negative control):
- uncovered item;
- Linear-covered item;
- competing Linear-only claim;
- closeout of a GitHub-tracked finding.
Plus codex debug prompt-input at root and every nested AGENTS directory, at baseline and head.
Rollback and retirement. Revert the squash commit. The rule deactivates itself when Linear can take new issues, because its condition is false. No budget waiver is requested.

@0monish

Generated by an AI agent (Claude Code, Opus 5.5) on behalf of @0monish, posted from the @0monish GitHub account. This is the progress comment and claim refresh that docs/agents/workflow.md step 4 requires after a scope change.

Agent claim

Agent: claude-code
Device: CENTILLIONAIREs-Mac-mini.local (macOS 26.5.1)
Model/effort: claude-opus-5-5@max
Repo: gyldlab/keld
Worktree: .keld-work/worktrees/docs(agents): record the #517 tracker-of-record rule in root AGENTS.md and the workflow claim protocol #520-tracker-of-record
Branch: agent/docs(agents): record the #517 tracker-of-record rule in root AGENTS.md and the workflow claim protocol #520-tracker-of-record
Expected paths: .agents/ci.md, .agents/coordination.md, .agents/index.md, .agents/instruction-budget.tsv, .agents/review.md, .codex/hooks.json, .github/PULL_REQUEST_TEMPLATE.md, AGENTS.md, docs/agents/spec-template.md, docs/agents/workflow.md, docs/architecture/01-overview.md, docs/engineering/linear-roadmap-mapping.md, docs/engineering/product-status.md, docs/onboarding/01-project-summary.md, docs/onboarding/02-architecture-guide.md, docs/onboarding/05-development-guide.md, docs/onboarding/06-documentation-map.md, docs/onboarding/08-optional-agent-memory.md, docs/specs/kel245-local-agent-workspace.md, llms-full.txt, llms.txt, tools/llms_docs.rs, tools/product_status.rs, tools/session_closeout.py, tools/test_session_closeout.py, tools/test_workspace.py, tools/workspace.py
Single-writer files/keys needed: shared:root-agents and shared:agent-workflow. The repository owner @0monish designated both on 2026-10-07; the KEL-124 coordination notice is 69c0457d.
Claim expires: 2026-10-07T20:30:00Z
OS acceptance owned: none

Progress and scope change

Revisions after review. Four isolated adversarial review rounds ran (two lenses, one independent refuter per finding). They confirmed 8, 11, 7 and 2 findings, and all are fixed in the working tree. The rule now says:
- The tracker of record is the one the GitHub issue body declares; agents never re-derive it.
- Claims are posted and ordered only on the tracker issue, by creation time; edits never reorder them.
- A claim for the same work posted anywhere else is a conflict.
- On GitHub, only comments and changes from push-access accounts count.
- GitHub states map to Done, Canceled, Blocked, In Progress and Todo (ready-for-agent), first match wins.
- Nothing private, Linear-only or security-sensitive is posted on the public issue.
Reversals of the first comment's non-goals.
- .agents/instruction-budget.tsv is edited. The coordination.md cap goes from 4352 to 5120 bytes (4297 → 5110; o200k_base 922 → ~1125 tokens) to hold § GitHub tracker issue. Fitting it in workflow.md was impossible: workflow.md is at the 16 KiB routed hard cap (16382/16384).
- The raise closes the high-severity claim-forgery and split-arbiter findings. The before/after scenario evals cover it: forged claim, same-work conflict, undeclared issue and closed duplicate, each with a negative control that deletes both owner sections.
- tools/product_status.rs and tools/llms_docs.rs change only in generated prose. GH row support in the ledger stays deferred.
- The KEL-245 spec, the branch contract (.agents/review.md) and four onboarding guides were aligned.
Overlap. Open PR docs(learnings): shared-target false green and elevated PowerShell resolution (KEL-270) #512 edits a different instruction-budget.tsv row (learnings); no textual conflict. The branch is one commit behind origin/main (ci(update): check the keld-update fuzz workspace on ubuntu (KEL-19) #514, CI only) and must be rebased before the PR.
Blocker (owner action). Commit e972271b holds revision 1. Committing revisions 2–4 was refused by this session's auto-mode permission classifier (Self-Modification), so the working tree is uncommitted. The owner must commit, rebase onto origin/main, push and open the PR, or grant the permission. The exact commands and PR body are in the session report.

wayfinder: final repair, alignment, residual fixes and #520 instructi…

wayfinder: add round-3 review and final-check evidence for #520

docs(agents): record the #517 GitHub tracker-of-record rule

docs(agents): bind GitHub tracker claims to declarations and push access

docs(agents): record the #517 GitHub tracker-of-record rule

docs(agents): bind GitHub tracker claims to declarations and push access

docs(agents): record the #517 GitHub tracker-of-record rule

docs(agents): bind GitHub tracker claims to declarations and push access

docs(agents): record the #517 GitHub tracker-of-record rule (#599)

@0monish

Generated by an AI agent (Claude Code) on behalf of @0monish.

Done: landed in #599 (e1cf252). The tracker-of-record rule now lives in docs/agents/workflow.md § Tracker issue and .agents/coordination.md § GitHub tracker issue, and work-start and closeout accept gh-<n>/GH-n. The claim expires with this close. Follow-up for the owner: re-trust .codex/hooks.json in Codex /hooks.

Navigation Menu

Repository navigation

docs(agents): record the #517 tracker-of-record rule in root AGENTS.md and the workflow claim protocol #520

Parent

What to build

Proposed exact text (draft for owner approval; the PR may tighten wording, not scope)

Acceptance criteria

Negative controls (each names the one mutation that must fail)

Ownership and gates

Out of scope

Agent Brief

Agent claim

OS acceptance

Scope, non-goals, dependencies

Decision-bearing atoms

Change record (`.agents/instructions.md` § Required change record)

Agent claim

Progress and scope change

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

docs(agents): record the #517 tracker-of-record rule in root AGENTS.md and the workflow claim protocol #520

Description

Parent

What to build

Proposed exact text (draft for owner approval; the PR may tighten wording, not scope)

Acceptance criteria

Negative controls (each names the one mutation that must fail)

Ownership and gates

Out of scope

Activity

0monish commented on Oct 6, 2026

Agent Brief

0monish commented on Oct 6, 2026

Agent claim

OS acceptance

Scope, non-goals, dependencies

Decision-bearing atoms

Change record (.agents/instructions.md § Required change record)

0monish commented on Oct 6, 2026

Agent claim

Progress and scope change

0monish commented on Oct 7, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Change record (`.agents/instructions.md` § Required change record)