Skip to content

Four of tonight's defects were one rule written twice; AGENTS.md covers facts, not rules #530

Description

@blooop

The observation

AGENTS.md already carries a standing rule about second copies:

A second hand-maintained copy of a fact is allowed only if a test named
beside it diffs it against the first.

Four defects found on the evening of 2026-08-29, by two sessions working in
parallel, were all second copies of a rule rather than of a fact. The
distinction turns out to matter, because the two fail in different ways and only
one of them is visible.

A fact drifts visibly. A rule drifts into a guard that fires on the deliberate
case.

That is why none of these read as inconsistencies to someone reading the code.
Each presents as a false refusal of correct behaviour:

  • Refuse a launch whose derived id collides with a different triple #524. WorkspaceId::suffix() lowercases owner and repo deliberately, so
    NVIDIA/cuda-samples and nvidia/cuda-samples are one workspace. A new
    collision guard compared raw triples, saw a different triple holding that id,
    and refused the launch. The advice it printed ("rename one of the two
    branches") named no exit, because both branches were main. The deliberate
    feature was reported as the fault, and the user was locked out of a running
    workspace.
  • Rebuild the agent-worktree sweep on the site subtree #525. worktree_dirt passes --ignored and status_porcelain does not, so
    one conjunction carries two definitions of "dirty". A finished worktree whose
    only untracked content is gitignored build output reports Uncommitted and
    stands, so the sweep refuses to collect the .pixi environments that are the
    entire 104 GB the ticket exists to reclaim.
  • A fix rebased across a release cut is filed inside the shipped section, and the merge is clean #527. ## [Unreleased] is a stable heading whose meaning the release cut
    restates. A branch's entry, anchored to the old heading, merges cleanly into
    the section that is now the shipped release. Nothing goes red, because the
    merge is correct by git's rule and wrong by the changelog's.
  • A fourth, found in the tooling built to fix the third. A CHANGELOG conflict
    resolver that knew only one insertion point (### Fixed) silently normalised
    every entry toward it, misfiling one that belonged under ### Changed. The
    output passed every check, including Refuse a pull request that files a new entry inside a shipped release #528's new guard, because the resolver
    produced it
    . An automated resolver with one insertion point does not fail
    loudly; it makes everything look intentional.

What might follow from it

Offered as a question rather than a proposal, because it is a change to the
project's standing rules and that is the owner's call.

The existing paragraph covers duplicated facts and prescribes a diff test. A
duplicated rule cannot always be diffed that way, since the second copy is
usually a comparison rather than a table. The candidate clause is something like:
where a normalisation or eligibility rule is applied in more than one place,
the second application must call the first rather than restate it
— the fix
adopted in #524 (lift the normalisation into one helper both the derivation and
the guard call) generalises to the others.

Three things worth weighing against it:

  1. It is a rule about rules, and AGENTS.md deliberately keeps its standing
    section short, having already refused a register under docs/ on the grounds
    that a register is itself a second copy.
  2. Enforcement would be a reviewer noticing, exactly as the existing paragraph
    is enforced. No new mechanism.
  3. Four instances in one evening is suggestive, but they were found by two
    sessions doing unusually heavy parallel work on one map, which is not the
    repo's normal condition.

Related: #517 and #529, which are the same evening's other theme (a signal whose
green means less than it looks like). #528 is the merged guard for #527.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions