Skip to content

projection: repo-harness/v1 renders 20 agent-context regions into root AGENTS.md and CLAUDE.md #580

New issue
New issue
Closed
#588
Closed
projection: repo-harness/v1 renders 20 agent-context regions into root AGENTS.md and CLAUDE.md#580
#588

Description

@Ancienttwo
Ancienttwo
opened on Nov 13, 2026

Problem

Under repo-harness/v1, archctx 0.14.0 renders one agent-context region for each capability into the files that its extensions.contractFiles names (#563, ADR-0056 §9). In aimpact-inc/repo-harness, 20 capabilities name the root AGENTS.md and CLAUDE.md. Every agent session loads these two files.

The v4 re-baseline (archctx docs apply --approved --profile repo-harness/v1) adds 20 regions to each root file:

File 0.13.0 0.14.0
AGENTS.md 60 lines 306 lines (+246)
CLAUDE.md 60 lines 306 lines (+246)

Text outside the markers stays byte-identical. Each region is about 12 lines: id, kind, summary, source.include, extensions.lspProfile, extensions.verification and an extensions digest. The data duplicates the architecture model and docs/architecture/modules/. In root files it costs context on each session. repo-harness has the root rule "keep root context concise", so it cannot accept this growth.

Evidence: branch wip/2686-archctx-0-14-option-a at e0b328d9a in aimpact-inc/repo-harness (#2686), on main 844d59141.

No fix in the consumer

  • parseRepoHarnessNodeProfile (bin/archctx.mjs about line 14763) requires contractFiles.agents and contractFiles.claude on every repo-harness/v1 capability. If one node has no contractFiles, docs apply fails (AC_UNCLASSIFIED_FAILURE). The capability profile read then fails with native-context-profile-incomplete for the whole repository.
  • agentContextTargetPaths makes a target for each contractFiles path, the repository root included. A model has no way to name a contract file and get no region in it.
  • Capability-local contract files for the 20 capabilities need about 36 new AGENTS.md/CLAUDE.md files in 18 directories. Two capabilities share src/cli/mcp, and one capability has no source directory. That is a new contract-file layout that only exists to hold generated regions.

Requested change

Under repo-harness/v1, root contract files get no agent-context region. The capability still names them in contractFiles for routing, and the profile still accepts them. Capability-local contract files keep their regions as in 0.14.0.

One direction: agentContextTargetPaths skips a contractFiles path that is the repository root AGENTS.md or CLAUDE.md. The re-baseline then removes the root rows, and no root region is written. A model-level setting is another direction, if the root behavior must stay configurable. The arch-context owner selects the design.

Acceptance:

  • docs apply --approved --profile repo-harness/v1 on aimpact-inc/repo-harness main leaves root AGENTS.md and CLAUDE.md byte-identical.
  • The regions in assets/AGENTS.md, scripts/AGENTS.md and src/cli/hook/AGENTS.md (capability-local) still render.
  • The capability profile read still accepts root contractFiles.
  • No compatibility code: no second writer and no alias.

repo-harness #2686 (archctx 0.14.0 bump) waits for a release with this change. Related: #579 (the v3 manifest refusal on the same re-baseline).

Seat: orchestrator t7

Activity

  1. Ancienttwo commented on Nov 13, 2026

    @Ancienttwo
    Ancienttwo
    on Nov 13, 2026
    OwnerAuthor

    Decision (owner → advisor, pane t12, 2026-11-13; the owner delegated the fix of #579 and #580 to the advisor). Tier High: one GPT review plus one Opus review of each head. The ADR-0056 §9 amendment goes in the same PR. Part of archctx 0.14.1.

    Seat: orchestrator t7

  2. Ancienttwo
    added a parent issue on Nov 13, 2026

  3. Ancienttwo commented on Nov 13, 2026

    @Ancienttwo
    Ancienttwo
    on Nov 13, 2026
    OwnerAuthor

    Claim: writer and head owner is the Pi worker seat t2k6 (magpie Opus 5.5). Phase 1, a read-only plan, starts now. Implementation starts from main after #579 merges, because both write changeset-engine. High tier: one GPT review plus one Opus review of each head.

    Seat: orchestrator t7

  4. Ancienttwo commented on Nov 13, 2026

    @Ancienttwo
    Ancienttwo
    on Nov 13, 2026
    OwnerAuthor

    Joint decision (orchestrator + advisor), 2026-11-13, on the seven open points of the #580 phase-1 plan. This works inside the owner-delegated decision 580#issuecomment-6842534344.

    1. The root skip is a required profile parameter on agentContextTargetPaths. Only the repo-harness/v1 layout passes repo-harness/v1. The default derivation keeps the root: the agent-context command, derive, validateRootWrite, projectionOwnedPaths and the worktree-digest ignore list. A parameter is not a model-level setting.
    2. The feat(projection): agent-context contract files are manifest rows with one writer (#563) #572 root-create branch is removed. The projection is its only designed caller. The two reachable but undesigned callers return to the pre-feat(projection): agent-context contract files are manifest rows with one writer (#563) #572 refusal: default-profile agent-context apply on an absent root, and a raw render_agent_context ChangeSet. The PR lists all three.
    3. Retire scope: option B. A region is retired only when its path is still in the model-derived write scope. Every other case is human-review. This keeps ADR-0056's "the projection never writes a path the current model does not designate". Option A would add a trust edge from manifest rows to the write allowlist.
    4. The retire removes exactly the region bytes [start, end). The projection never removes the blank line before the region. In this repository the PR may delete the leftover blank line in root CLAUDE.md and AGENTS.md, as an ordinary human edit in the same commit, keeping the siblings aligned.
    5. A retire that empties a file writes the empty body. Deletes stay render_projection-only.
    6. The profile refusal applies when the committed manifest is v4 and either its profile is repo-harness/v1 or it records an agent-context row. A v3 manifest keeps the pre-re-baseline behavior.
    7. No verify-pr change. The ADR-0056 amendment states that a repository that ran 0.14.0 with root rows gets one human-merged retire PR. repo-harness never ran 0.14.0 with root rows, so its acceptance stays "root files byte-identical".

    Timing. Implementation starts now, on branch feat/580-no-root-agent-context, stacked on PR #587's head (#579), the way slice B stacked on #556. The worker rebases onto main after #587 merges and opens the PR then. One writer per file holds in time order.

    Seat: orchestrator t7

  5. Ancienttwo commented on Nov 13, 2026

    @Ancienttwo
    Ancienttwo
    on Nov 13, 2026
    OwnerAuthor

    Claim update: writer and head owner is Pi seat t2k6. Branch: feat/580-no-root-agent-context, stacked on PR #587 head ac16cc7. It rebases onto main after #587 merges, then opens the PR.

    Seat: orchestrator t7

  6. Ancienttwo commented on Nov 13, 2026

    @Ancienttwo
    Ancienttwo
    on Nov 13, 2026
    OwnerAuthor

    Joint decision (orchestrator + advisor), 2026-11-13, replacing 580#issuecomment-6846935087. It follows the owner's direction in pane t12 the same day: "不要写兼容性代码，仓库是我的，必要时请干净重构" (no compatibility code; the repository is the owner's; refactor cleanly where needed).

    A. No retire machinery (this withdraws the former points 3, 4, 5 and 7).

    • The only state a retire would serve is root rows from 0.14.0. The only repository that ran 0.14.0 under repo-harness/v1 with root rows is this one. repo-harness pins 0.13.0 and never ran 0.14.0. A general retire path for that one-time state would be migration code left in steady state.
    • Instead, the projection: repo-harness/v1 renders 20 agent-context regions into root AGENTS.md and CLAUDE.md #580 PR removes this repository's root agent-context regions from CLAUDE.md and AGENTS.md as an ordinary edit, keeping the siblings aligned. The docs apply --approved in the same PR writes the v4 manifest without root rows.
    • The hand removal is this joint decision, made under the owner's general rule. It is not an explicit owner instruction to hand-edit. With the new code the root is not a target, so after the change those bytes are plain file content that no row owns. The same PR's docs apply writes a consistent v4 manifest.
    • ADR-0056's Non-goal "The projection does not remove an orphaned contract region" stays as it is.

    B. One rule for archctx agent-context plan|preview|apply, with no version branch (replaces the former point 6). The command reads the committed manifest the way every projection command does:

    • a superseded v1-v3 manifest refuses with projection-manifest-upgrade-required, so the re-baseline runs first;
    • a v4 manifest whose profile is repo-harness/v1 refuses with agent-context-owned-by-projection;
    • with no manifest, or with a v4 default-profile manifest, the command runs as today.

    If the profile check makes #572's per-row check redundant, the per-row check is removed. The two are not kept side by side.

    C. The former points 1 and 2 stand.

    D. Clean refactor is in scope where it removes duplication or a structure that is in the way, inside #580's files. The PR body states what was refactored. One writer per file still applies across #579 and #580.

    The ADR-0056 §9 amendment in the same PR covers only the root skip, the agent-context refusal by profile and the removal of root-create. Acceptance on repo-harness is unchanged: root AGENTS.md and CLAUDE.md are byte-identical, and the three capability-local regions render. The timing is unchanged: the branch is stacked on #587, rebases after #587 merges, and the PR opens then.

    Seat: orchestrator t7

  7. Ancienttwo
    added a commit that references this issue on Nov 13, 2026

    fix(contracts): re-baseline a superseded manifest that carries floors (…

    ee3eaf3

  8. Ancienttwo commented on Nov 13, 2026

    @Ancienttwo
    Ancienttwo
    on Nov 13, 2026
    OwnerAuthor

    repo-harness issue claim status
    Claim: #580 (comment)
    Status: ready for review; claim remains active
    PR: #588 head bbde62d
    CI: pending
    Next: coordinator starts the Tier High review (one GPT plus one Opus); the worker answers findings on #588.

    Seat: t2k6

  9. Ancienttwo
    added a commit that references this issue on Nov 13, 2026

    fix(runtime-daemon): refuse every root contract write under repo-harn…

    4f8d9a2
  10. Ancienttwo
    closed this as completedin 5804c21on Nov 13, 2026
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