Retire #237 from startup; run orientation and mechanical top-five selection in parallel #520

Closed
opened 2026-07-21 01:04:17 +02:00 by timothy · 3 comments
Owner

Problem

The ChicoryTV arc tracker #237 is closed, but the current handoff and docs still tell fresh agents—and the fallback selector path—to read its body and recent comments during normal startup.

That is now both clunky and unsafe:

  • #237 is historical, not a current queue.
  • old session comments contain stale forward-looking statements;
  • scripts/select-queue.sh already performs the live mechanical selection correctly;
  • startup currently preloads a large standing documentation corpus before the task is known;
  • newer lore says to trust the deterministic script while older retained lore still says to re-derive selector results.

This issue comes from a bounded knowledge-retrieval audit in timothy/adversarial-reviewer.

Decision

Normal maintenance-mode startup has two concurrent tracks:

  1. Orientation: read the repository instructions and a compact knowledge map.
  2. Selection: run scripts/select-queue.sh 5.

After both finish, resolve only the selected shortlist's judgment flags, choose/claim the top eligible issue, and retrieve a focused task-specific knowledge packet.

#237 remains closed archival history. It is not required reading and is not consulted for normal ranking. If a future ordered arc is created, it gets an explicit new active tracker/mechanism instead of silently reactivating #237.

Target startup flow

When the user names an issue

  • Skip queue selection.
  • Verify that issue's live state/claimability.
  • Use its title, body, labels, affected paths, and acceptance criteria to retrieve relevant knowledge.

When the user does not name an issue

Start these concurrently:

  • read AGENTS.md, CLAUDE.md, and the compact docs/README.md knowledge map;
  • run scripts/select-queue.sh 5.

Then:

  1. Trust the script's dependency filtering, tiering, priority ordering, label exclusions, and top-five ordering.
  2. Inspect issue body/comments only for CLAIM? and UMBRELLA? rows and for the eventual winner.
  3. Recheck the winner's live state immediately before claiming.
  4. Claim it.
  5. Build a focused knowledge packet:
    • current authoritative decisions;
    • relevant convention sections;
    • historical issue/PR evidence;
    • source/test anchors;
    • conflicts or unresolved questions.
  6. Read/recon only the task-specific delta.

Knowledge retrieval rules

  • Project Markdown remains authoritative for current conventions and decisions.
  • MemPalace, when available, is candidate discovery—not authority. Verify retrieved passages against their cited Markdown/Gitea source.
  • If MemPalace is unavailable or stale, use the task map and bounded exact search.
  • Never derive live queue state from MemPalace, #237, historical comments, or prose.
  • Do not read every convention document at startup. docs/README.md should map task signals to the minimum relevant sections.

Infrastructure work to mirror Gitea history—including #237—into MemPalace is tracked by timothy/server-management#642. This issue must remain usable before that dependency lands by documenting the exact-search fallback.

Structured future closing record

Agents keep posting the closing record on the issue they actually worked. Do not introduce a second manually maintained per-session Markdown ledger.

Standardize a concise close-comment shape suitable for humans and later MemPalace export:

## Closing record
**Outcome**:
**Root cause**: <required for bugs/incidents; otherwise n/a>
**Decisions/conventions changed**:
**Reusable knowledge**:
**Verification**:
**Deferred/follow-ups**:
**Docs updated**:

Durable decisions still go into the decision/convention Markdown in the same PR. The issue comment is evidence and implementation history, not the only home of an engineering rule.

Scope

  • Rewrite the standing kickoff and current-phase text around the flow above.
  • Remove #237 from normal startup, normal selector fallback, and normal session-end instructions.
  • Update docs/README.md from a mandatory full reading order to a compact authority/task map.
  • Update CLAUDE.md docs-first guidance to require the map plus relevant sections, not the whole corpus.
  • Update scripts/select-queue.sh comments/output so its active tiers begin with open milestones/review/priorities and no longer say "read #237."
  • Remove or clearly archive contradictory selector lore that predates the deterministic script.
  • Update task-completion guidance with the structured per-issue closing record.
  • Retain #237 links only where explicitly labeled historical/archive.
  • Add a small deterministic check or test that prevents active kickoff text from reintroducing "#237 is the queue/source of truth" language.
  • Validate the revised kickoff with a cold agent simulation.

Out of scope

  • Implementing the MemPalace/Gitea exporter (server-management#642).
  • Changing the selector's established dependency/tier/priority algorithm unless a test exposes a bug.
  • Reopening #237.
  • Creating a new standing session-log issue.
  • Creating a manually maintained session-history Markdown file.

Done-when

  • A fresh agent can start without reading #237.
  • Orientation and scripts/select-queue.sh 5 are explicitly concurrent when no issue is named.
  • Named-issue startup skips selection and goes directly to focused retrieval.
  • The selector returns and documents a deterministic top five with only judgment flags requiring focused reads.
  • docs/README.md maps task signals to minimal authoritative reading instead of requiring the full corpus.
  • MemPalace candidate discovery + canonical verification + exact-search fallback are documented.
  • #237 appears only as clearly labeled archival history.
  • Contradictory pre-script selector instructions are removed or archived outside the active path.
  • Per-issue structured closing comments are the future history record; no duplicate manual ledger is required.
  • The active kickoff cannot regress to treating #237 as live state without tripping a check.
  • Cold-agent simulation produces the expected top-five → focused-retrieval → claim flow.
  • Relevant docs are updated in the same PR.
  • Independent adversarial review passed.
## Problem The ChicoryTV arc tracker #237 is closed, but the current handoff and docs still tell fresh agents—and the fallback selector path—to read its body and recent comments during normal startup. That is now both clunky and unsafe: - #237 is historical, not a current queue. - old session comments contain stale forward-looking statements; - `scripts/select-queue.sh` already performs the live mechanical selection correctly; - startup currently preloads a large standing documentation corpus before the task is known; - newer lore says to trust the deterministic script while older retained lore still says to re-derive selector results. This issue comes from a bounded knowledge-retrieval audit in `timothy/adversarial-reviewer`. ## Decision Normal maintenance-mode startup has two concurrent tracks: 1. **Orientation:** read the repository instructions and a compact knowledge map. 2. **Selection:** run `scripts/select-queue.sh 5`. After both finish, resolve only the selected shortlist's judgment flags, choose/claim the top eligible issue, and retrieve a focused task-specific knowledge packet. #237 remains closed archival history. It is not required reading and is not consulted for normal ranking. If a future ordered arc is created, it gets an explicit new active tracker/mechanism instead of silently reactivating #237. ## Target startup flow ### When the user names an issue - Skip queue selection. - Verify that issue's live state/claimability. - Use its title, body, labels, affected paths, and acceptance criteria to retrieve relevant knowledge. ### When the user does not name an issue Start these concurrently: - read `AGENTS.md`, `CLAUDE.md`, and the compact `docs/README.md` knowledge map; - run `scripts/select-queue.sh 5`. Then: 1. Trust the script's dependency filtering, tiering, priority ordering, label exclusions, and top-five ordering. 2. Inspect issue body/comments only for `CLAIM?` and `UMBRELLA?` rows and for the eventual winner. 3. Recheck the winner's live state immediately before claiming. 4. Claim it. 5. Build a focused knowledge packet: - current authoritative decisions; - relevant convention sections; - historical issue/PR evidence; - source/test anchors; - conflicts or unresolved questions. 6. Read/recon only the task-specific delta. ## Knowledge retrieval rules - Project Markdown remains authoritative for current conventions and decisions. - MemPalace, when available, is candidate discovery—not authority. Verify retrieved passages against their cited Markdown/Gitea source. - If MemPalace is unavailable or stale, use the task map and bounded exact search. - Never derive live queue state from MemPalace, #237, historical comments, or prose. - Do not read every convention document at startup. `docs/README.md` should map task signals to the minimum relevant sections. Infrastructure work to mirror Gitea history—including #237—into MemPalace is tracked by `timothy/server-management#642`. This issue must remain usable before that dependency lands by documenting the exact-search fallback. ## Structured future closing record Agents keep posting the closing record on the issue they actually worked. Do not introduce a second manually maintained per-session Markdown ledger. Standardize a concise close-comment shape suitable for humans and later MemPalace export: ```markdown ## Closing record **Outcome**: **Root cause**: <required for bugs/incidents; otherwise n/a> **Decisions/conventions changed**: **Reusable knowledge**: **Verification**: **Deferred/follow-ups**: **Docs updated**: ``` Durable decisions still go into the decision/convention Markdown in the same PR. The issue comment is evidence and implementation history, not the only home of an engineering rule. ## Scope - Rewrite the standing kickoff and current-phase text around the flow above. - Remove #237 from normal startup, normal selector fallback, and normal session-end instructions. - Update `docs/README.md` from a mandatory full reading order to a compact authority/task map. - Update `CLAUDE.md` docs-first guidance to require the map plus relevant sections, not the whole corpus. - Update `scripts/select-queue.sh` comments/output so its active tiers begin with open milestones/review/priorities and no longer say "read #237." - Remove or clearly archive contradictory selector lore that predates the deterministic script. - Update task-completion guidance with the structured per-issue closing record. - Retain #237 links only where explicitly labeled historical/archive. - Add a small deterministic check or test that prevents active kickoff text from reintroducing "#237 is the queue/source of truth" language. - Validate the revised kickoff with a cold agent simulation. ## Out of scope - Implementing the MemPalace/Gitea exporter (server-management#642). - Changing the selector's established dependency/tier/priority algorithm unless a test exposes a bug. - Reopening #237. - Creating a new standing session-log issue. - Creating a manually maintained session-history Markdown file. ## Done-when - [x] A fresh agent can start without reading #237. - [x] Orientation and `scripts/select-queue.sh 5` are explicitly concurrent when no issue is named. - [x] Named-issue startup skips selection and goes directly to focused retrieval. - [x] The selector returns and documents a deterministic top five with only judgment flags requiring focused reads. - [x] `docs/README.md` maps task signals to minimal authoritative reading instead of requiring the full corpus. - [x] MemPalace candidate discovery + canonical verification + exact-search fallback are documented. - [x] #237 appears only as clearly labeled archival history. - [x] Contradictory pre-script selector instructions are removed or archived outside the active path. - [x] Per-issue structured closing comments are the future history record; no duplicate manual ledger is required. - [x] The active kickoff cannot regress to treating #237 as live state without tripping a check. - [x] Cold-agent simulation produces the expected top-five → focused-retrieval → claim flow. - [x] Relevant docs are updated in the same PR. - [x] Independent adversarial review passed.
timothy added the enhancementpriority: mediumreview labels 2026-07-21 01:04:17 +02:00
timothy added the in-progress label 2026-07-21 01:18:33 +02:00
Author
Owner

Claiming (Claude Code, Opus 4.8). Working #520 + #521 together as one knowledge-retrieval arc: build #521's keyed decision-lifecycle schema + generated active catalog (docs/decisions/README.md) + lifecycle validator (replacing the append-only line guard while keeping its spirit; retiring the [decisions-edit] token), then rewire #520's startup/kickoff to point at the compact active view + parallel select-queue.sh, with a regression check that blocks re-treating #237 as live state. Full entry migration fanned out to subagents. Single [decisions-edit]-tagged PR.

Claiming (Claude Code, Opus 4.8). Working #520 + #521 together as one knowledge-retrieval arc: build #521's keyed decision-lifecycle schema + generated active catalog (docs/decisions/README.md) + lifecycle validator (replacing the append-only line guard while keeping its spirit; retiring the [decisions-edit] token), then rewire #520's startup/kickoff to point at the compact active view + parallel select-queue.sh, with a regression check that blocks re-treating #237 as live state. Full entry migration fanned out to subagents. Single [decisions-edit]-tagged PR.
Author
Owner

Machinery for the retrieval side landed in PR1 (#526, merged f4bebd77) — the generated active catalog (docs/decisions/README.md) + archive/ wing that the #520 orientation block will point agents at.

#520 itself stays open — its startup/kickoff rewrite is PR2: retire #237 from normal startup, parallel orientation ‖ select-queue.sh, the check-kickoff-guard.sh regression guard, the ## Closing record template, and the Knowledge-retrieval orientation block carrying the four bullets coordinated with server-management#642 (catalog-first; Gitea-ErsatzTV = evidence-not-authority; the breadcrumb rule — a file path named in a historical comment is a breadcrumb, not a live pointer, resolve by concept; catalog→rg fallback, MemPalace never authority). #642 confirms its 283-issue export is live + tiered and is retrievable-but-unreached until this block ships.

**Machinery for the retrieval side landed in PR1** ([#526](http://192.168.1.95:3000/timothy/ersatztv/pulls/526), merged `f4bebd77`) — the generated active catalog (`docs/decisions/README.md`) + `archive/` wing that the #520 orientation block will point agents at. **#520 itself stays open — its startup/kickoff rewrite is PR2:** retire #237 from normal startup, parallel orientation ‖ `select-queue.sh`, the `check-kickoff-guard.sh` regression guard, the `## Closing record` template, and the **Knowledge-retrieval orientation block** carrying the four bullets coordinated with server-management#642 (catalog-first; `Gitea-ErsatzTV` = evidence-not-authority; the **breadcrumb rule** — a file path named in a historical comment is a breadcrumb, not a live pointer, resolve by concept; catalog→`rg` fallback, MemPalace never authority). #642 confirms its 283-issue export is live + tiered and is retrievable-but-unreached until this block ships.
Author
Owner

Closing record

Outcome: Shipped via PR #527 (merged 063017584d7f09619162e818f2db922776bbbdd4). Normal startup no longer reads the closed tracker #237: two concurrent tracks when no issue is named (orientation ‖ scripts/select-queue.sh 5), named-issue skips selection → focused retrieval. docs/README.md is a task-signal map (not a mandatory 1–10 read); the kickoff carries the four server-management#642 knowledge-retrieval bullets (catalog-first; Gitea history = evidence-not-authority; the breadcrumb rule; catalog→rg fallback). ## Closing record standardized as the per-issue durable artifact. scripts/check-kickoff-guard.sh (wired to CI) blocks any regression to treating #237 as live state.
Root cause: n/a (enhancement). The underlying problem — status/queue-state asserted in append-only prose that drifts — is the same throughline as #521.
Decisions/conventions changed: docs.queue-state-gitea-tracker (#237) superseded by startup.parallel-orientation (reciprocal links; archived to docs/decisions/archive/startup.md). Pre-script selector lore demoted to a labeled archival section.
Reusable knowledge: The load-bearing artifact for making mined knowledge reached is the startup orientation block — the export is inert without it (the #642 seam). A file path named in a historical comment is a breadcrumb, not a live pointer.
Verification: Startup cold-agent sim PASSED — a fresh agent with live Gitea access chose not to read #237, ran select-queue.sh, went catalog-first, understood the breadcrumb rule. kickoff-guard non-vacuity proven (fails pre-rewrite, passes post). Whole-branch adversarial review confirmed complete+correct.
Deferred: MEMORY.md queue-protocol-gitea-tracker note update (operator auto-memory, not repo — done this session).
Docs updated: docs/handoffs/chicorytv-issue-queue.md, docs/README.md, CLAUDE.md, scripts/select-queue.sh, docs/decisions.md + docs/decisions/archive/startup.md.

## Closing record **Outcome:** Shipped via PR #527 (merged `063017584d7f09619162e818f2db922776bbbdd4`). Normal startup no longer reads the closed tracker #237: two concurrent tracks when no issue is named (orientation ‖ `scripts/select-queue.sh 5`), named-issue skips selection → focused retrieval. `docs/README.md` is a task-signal map (not a mandatory 1–10 read); the kickoff carries the four server-management#642 knowledge-retrieval bullets (catalog-first; Gitea history = evidence-not-authority; the breadcrumb rule; catalog→`rg` fallback). `## Closing record` standardized as the per-issue durable artifact. `scripts/check-kickoff-guard.sh` (wired to CI) blocks any regression to treating #237 as live state. **Root cause:** n/a (enhancement). The underlying problem — status/queue-state asserted in append-only prose that drifts — is the same throughline as #521. **Decisions/conventions changed:** `docs.queue-state-gitea-tracker` (#237) superseded by `startup.parallel-orientation` (reciprocal links; archived to `docs/decisions/archive/startup.md`). Pre-script selector lore demoted to a labeled archival section. **Reusable knowledge:** The load-bearing artifact for making mined knowledge *reached* is the startup orientation block — the export is inert without it (the #642 seam). A file path named in a historical comment is a breadcrumb, not a live pointer. **Verification:** Startup cold-agent sim PASSED — a fresh agent with live Gitea access chose not to read #237, ran select-queue.sh, went catalog-first, understood the breadcrumb rule. kickoff-guard non-vacuity proven (fails pre-rewrite, passes post). Whole-branch adversarial review confirmed complete+correct. **Deferred:** MEMORY.md `queue-protocol-gitea-tracker` note update (operator auto-memory, not repo — done this session). **Docs updated:** `docs/handoffs/chicorytv-issue-queue.md`, `docs/README.md`, `CLAUDE.md`, `scripts/select-queue.sh`, `docs/decisions.md` + `docs/decisions/archive/startup.md`.
timothy removed the in-progress label 2026-07-21 18:06:07 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#520