Skip to content

[process·P1] Issue lifecycle and context hygiene: active queue ≠ open backlog #538

Description

@atomchung

Status

Implementation / process hardening — authority split recorded; one bounded docs leaf remains.

The lifecycle/context-loading contract and first stale-issue cleanup pass are complete. On 2026-07-30 the current M1 chain was restructured so routing, implementation, acceptance, roadmap, and future release history no longer share one issue body.

This work is non-blocking for M1. It must not interrupt #583 or #544.

Milestone

None — repository operating model.

Current product milestone remains M1. This issue owns context-loading efficiency, issue authority boundaries, and the bounded cleanup that proves them.

User outcome

A maintainer or coding agent can enter the repository, identify the current milestone and executable owner, and begin a bounded implementation without scanning the whole repository, replaying the open backlog, or relying on a host-specific instruction file for shared repository rules.

Current repository truth

Completed

Still true

  • The long-tail backlog remains intentionally large. That is acceptable only while it stays outside the default execution capsule.
  • Truth-critical changes still require targeted caller/route inventory because the codebase has real contract fan-out. “Do not scan the whole repository” does not mean “trust one issue body without searching affected production paths.”
  • CLAUDE.md is currently 122 lines and mostly host-neutral maintainer material; [process·docs] Shared maintainer contract must not live in CLAUDE.md #587 is not yet implemented.

Decision

1. Separate four information lifecycles

Information Authority Must not contain
Product roadmap and scope decisions #475 while it remains owner-ratified Per-PR history, implementation instructions, active-queue bookkeeping
Implementation handoff and current evidence Owning implementation issue and active PR Other milestones, release marketing, unrelated completed work
Acceptance ledger #486 / #488 and their eligible evidence Implementation design owned elsewhere, speculative roadmap
Execution routing #27 Release history, detailed design, copied roadmap, full dependency narrative

Release notes belong in a GitHub Release and/or CHANGELOG.md when an actual version/tag is cut. They do not belong in the default implementation context.

2. Use a bounded execution capsule

For substantive work, load and stop when sufficient:

  1. latest main and AGENTS.md;
  2. the directly affected current contract/reference;
  3. tracking: current context index — milestone, critical path, what an agent may pick up #27 for current routing;
  4. the owning implementation issue;
  5. its direct acceptance gate;
  6. the current PR, when one exists.

Search wider only for a named symbol, production-route inventory, duplicate, prior decision, or direct dependency. A repository-wide architecture review is a separate task.

3. Split by invariant or user outcome, not file

#583 remains one issue across price_feed, ValuationFrame, PortfolioBasis, review, both consider routes, and revisit because those are consumers of one price/share-basis invariant. Splitting by file would make partial fixes and semantic drift more likely.

#544 remains separate because it owns a different result: proof that the TradeEvaluation challenge actually reached the user.

4. Host-specific files are adapters, not shared authorities

#587 owns the correction:

  • shared repository-maintenance guidance moves to a host-neutral maintainer guide;
  • CLAUDE.md becomes a thin adapter containing pointers and actual Claude Code-only tooling behavior;
  • AGENTS.md remains a thin cross-agent router;
  • a small structural gate prevents CLAUDE.md from regrowing shared test, privacy, PR, architecture, or mirrored-surface sections.

A new rule may enter CLAUDE.md only when its owning issue/PR names the Claude-only mechanism it supports. “Claude may benefit from seeing this” is not sufficient.

Remaining scope

Non-goals

  • Closing every old issue.
  • Treating is:open as the execution queue.
  • Splitting a coherent invariant into one issue per file/helper/test.
  • Using one issue as release note + implementation summary + roadmap.
  • Expanding AGENTS.md or CLAUDE.md into another complete project database.
  • Adding GitHub Projects, complex lifecycle bots, or a generated roadmap before a repeated measurable failure requires them.
  • Changing M1 scope or product behavior through process cleanup.

Acceptance criteria

  • tracking: current context index — milestone, critical path, what an agent may pick up #27 contains only current execution-routing facts and links.
  • Current implementation owners expose executable handoffs without requiring backlog replay.
  • Roadmap, implementation, acceptance, and release-history facts have distinct authorities.
  • Normal development does not load all open issues or scan unrelated repository areas.
  • Cross-cutting correctness work still performs targeted production-route/caller inventory.
  • [process·docs] Shared maintainer contract must not live in CLAUDE.md #587 moves shared maintainer guidance out of CLAUDE.md, leaves a thin Claude adapter, and adds a bounded regression gate.
  • A fresh maintainer can name the milestone, active front, acceptance gate, contention, next step, and stop boundary from the bounded capsule.
  • M1 implementation is not delayed by this process work.

Dependencies

Privacy boundary

Use only public repository metadata, public issues/PRs, synthetic fixtures, and generic examples. No real trade, holding, amount, date, thesis, source path, private-repository content, or private QA text may enter process evidence.

Rollout / compatibility / recovery

Issue-body edits and documentation moves are reversible through GitHub history. No runtime, schema, or user data change is owned here. If a thinner routing surface omits a necessary pointer, restore the pointer at its authority; do not restore copied history or design prose.

Historical first-pass result

The 2026-07-29 pass updated seven issue bodies/titles, marked #12 superseded, closed no issue, preserved historical bodies, and landed PR #541 with the lifecycle authority. Full per-candidate evidence remains in this issue's comments and GitHub revision history.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions