Week 2 of 4 · Arcs 4, 6 and 7

Handoffs, a work list, docs for agents

As of Oct 23, 2026 · W. Burch

By the end of week two a lane outlasts its context window, keeps working after a task ends, and keeps its own docs true. It covers Arc 6, the single-agent form of Arc 7, and Arc 4. The cards use the layer table in Week one; a harness hook, a script the agent tool runs on an event such as session start or turn end, sits in the same layer as the permission file. The cards say what to build and why; the bootstrap prompt below has your agent build them, and you check its work against the cards.

The cards

Card 1

State outlives the context window

Enforce it, strongest first

  1. Harness hook at session start: when a session starts, or its context is cleared or compacted, a hook prints the handoff's CURRENT section into the new context. A 40-line shell script is enough.
  2. Harness add-ons, about 100 lines each: a context gauge above the prompt; a nudge appended to tool results (stale from 180K tokens, wrap from 200K, urgent from 230K); a fresh-start tool that refuses a handoff older than 20 minutes, otherwise clears the context and resumes from CURRENT.
  3. Rules file: the agent owns a handoff file with a CURRENT section above a marker line, about 6,000 characters, rewritten in place at every checkpoint (ticket filed or closed, run landed, commit made, before a long edit). CURRENT holds only what is true now, plus a working set: file paths and line ranges, each with the conclusion already reached. History goes to an archive file, newest first. Both files stay out of git.

Set the thresholds from measurement, not from the setting. Here 30 of 38 compactions fired between 256K and 274K tokens, not the configured 300K. A nudge that fired only on a stale handoff let diligent lanes hit compaction 15 times out of 29, so the wrap band triggers on size alone.

markdown
# HANDOFF: <lane>

## CURRENT
Now: <the one task in flight and its next step>
State: <SHAs, run ids, gates; each line true now>
Waiting on: <person or lane, and for what>
Working set:
- src/ingest/parse.py:120-188, the retry loop; bug is the off-by-one at 151
<!-- END CURRENT -->

Card 2

Finishing a task isn't a stop

Arc 7one agent

Enforce it, strongest first

  1. Harness hook at turn end: refuses a turn whose last sentence announces work the agent didn't start ("next I'll…", "continuing with…"), and tells it to make that work's first call or name the blocker. It matches wording, not intent.
  2. Rules file: a keep-going rule. Finishing a ticket isn't a reason to stop; the only stops are a blocker that needs a person, or the context budget.
  3. A tracked file: an ordered work list the agent reads when a task ends. For one agent this is enough; move to the tracker in week four, when a second agent or person needs to see it.
text
Turn-end hook, in words:
  read the agent's final message
  if its last sentence names work ahead (next, then, continuing, I'll)
     and the turn made no tool call for that work:
       refuse the stop: "Start it now, or name the blocker."
  otherwise allow the stop

Card 3

Agent docs stay true to the code

Enforce it, strongest first

  1. Git pre-push hook: a git tag marks the last commit where docs matched code, and the hook refuses a push to the shared branch that carries runtime changes past it; other branches push freely. Only the close step (card 4) moves the tag.
  2. Rules file: a one-page README contract for a docs/architecture/ folder. Three tiers: always in context, read on demand, never documented. A terse register written for agents, roughly 80% why and gotchas to 20% what, and one owning doc per concept.
markdown
# docs/architecture/README.md
Tier 1, always loaded: this file, overview.md
Tier 2, read on demand: one file per subsystem, named for it
Tier 3, never documented: anything the code states plainly
Each concept has one owning doc; others link to it.
Write why and gotchas; leave what to the code.

Card 4

Nobody closes their own work unreviewed

No script enforces this yet; it lives in the rules file. A hook can check that an audit verdict exists, not that the audit was honest.

  1. Rules file: a spec lifecycle. Scope, then start (links ticket and spec), then audit: a fresh agent gets the spec and the commit range and returns ship, fix first, or review; an unused export counts as a defect. Then close: reconcile the docs, archive the spec, move the docs tag, transition the ticket last.

Specs start as numbered Markdown files with a five-line header.

markdown
# 042: Retry uploads on timeout
Status: draft | started | audited | closed
Ticket: PROJ-123
Depends: 038
Blocks: 047
Author: <lane or person>

Bootstrap prompt

This prompt carries out the four cards. Read the cards to know what good looks like, paste the prompt into your agent at the root of one repo, then check its gap report card by card. It works out which hooks your tool offers, maps the four cards onto that tool and your repo, and commits its changes on a new local branch for you to review. It never pushes, and never changes settings outside the repo, such as hooks registered in your home directory; it lists those for you.

text
Set up "week two" for running coding agents unattended in this repository:
handoffs that survive a cleared context, a keep-going rule, agent docs that
stay true to the code, and a reviewed close. Work through the steps in
order. Nothing leaves this repo and nothing is pushed.

1. Your harness. Name the agent tool you are running in and its version.
   Find its documentation (built-in help, local docs, or the official site;
   reading it online is fine). Quote only text you read word for word, label
   anything else as your own knowledge, and say "none" where it has none:
   a. hooks it runs on events: session start, after a context clear or
      compaction, and turn end (can a turn-end hook refuse the stop?);
   b. how a hook's output reaches the agent's context;
   c. where it reports context size, whether a hook can read it, and the
      token count at which it compacts automatically;
   d. the instructions file it loads at session start, and its scopes.
   If week one's rules file exists, name it; this week adds to it. If
   not, create one under the name the harness loads (from d).

2. This repo. Find any existing handoff, notes or work-list file; any
   docs folder written for agents; existing git hooks and git tags; how
   specs or design notes are kept; the ticket tracker, if one is named.
   Name the file you learned each fact from. List checks that already
   fail; don't fix them.

3. Questions. Put everything you could not find in ONE message to me:
   the lane name for the handoff file; where the work list should live;
   which directories hold runtime code (the docs gate watches only
   those); who may run an audit. If nobody answers, continue on stated
   assumptions and mark each one ASSUMED in the final report.

4. The cards. For each card, choose the strongest layer available here,
   in this order unless the card names its own: git hook or CI check;
   your harness's hooks or permission settings; the rules file. Name the
   layer and the file, and propose the change as a diff.
   Card 1: state outlives the context window. A handoff file with a
           CURRENT section above an end marker, at most about 6,000
           characters, holding only what is true now plus a working set
           (path:line-range and the conclusion reached); history in an
           archive file, newest first. Both files stay out of git: they
           are this lane's state. Strongest here: a session-start hook
           that prints CURRENT after start, clear and compaction. Then a
           nudge with stale, wrap and urgent bands below the real
           compaction point: measure that point if you can (the size at
           which a past compaction fired); otherwise take the documented
           one, mark it ASSUMED, and leave a wide margin. If no hook can
           read context size, say how the nudge would get it, or that it
           can't.
   Card 2: finishing a task isn't a stop. A keep-going rule in the rules
           file (the only stops: a blocker that needs a person, or the
           context budget) and an ordered work list in a tracked file.
           Strongest here: a turn-end hook that refuses a turn ending on
           work it announced but didn't start. It matches wording, not
           intent; list the phrasings it lets through.
   Card 3: agent docs stay true. A docs/architecture/ folder with a
           README contract (three tiers: always loaded, read on demand,
           never documented; terse; mostly why and gotchas; one owning
           doc per concept). Strongest here: a pre-push hook that refuses
           a push to the shared branch carrying runtime changes past a
           docs tag; other branches push freely. Create the tag once now
           as the baseline; after that only the close step moves it. If
           the repo has no runtime code yet, don't invent a directory:
           leave the gate's path list empty and say so.
   Card 4: nobody closes their own work unreviewed. Rules file only; say
           so in the report. A spec lifecycle (scope, start, audit by a
           fresh agent given the spec and commit range with verdict ship,
           fix first or review, close that reconciles docs, archives the
           spec, moves the docs tag, and transitions the ticket last), and
           a five-line spec header: status, ticket, depends, blocks,
           author. With no tracker, the work list stands in for it.

5. Write the files on a new local branch, inside this repo only, and
   commit. If nobody answers, that commit is your proposal; I review it
   there. Never push or merge. Create the docs tag on that commit. Run
   each hook you wrote once by hand with the input it would get (a
   session-start event, a sample final message, the refs a push would
   see); never push to trigger it. Show each output. For anything outside
   the repo (harness settings in your home directory, hooks registered
   there, tracker changes), write the exact steps for me instead.

6. End with a gap report, one row per card: card, layer used, file,
   what is still enforced only by the rules file or not at all, and
   every ASSUMED item.

Checklist

0 of 5 done

Ticks stay in this browser only.

Ready for week three when

  • A lane clears its context mid-task and resumes from CURRENT without you re-explaining anything.
  • A lane finishes a ticket and starts the next one on the list without being asked.
  • A push that changes runtime code past the docs tag is refused until the docs are reconciled.
  • A fresh agent's audit has sent at least one spec back with "fix first".