Skip to content

docs: correct loop-control subsystem descriptions in ARCHITECTURE.md/PRODUCT.md - #620

Merged
TheGreatAxios merged 2 commits into
mainfrom
cl-7003-docsarchitecturemd-and-productmd-describe-the-loop-control
Aug 24, 2026
Merged

docs: correct loop-control subsystem descriptions in ARCHITECTURE.md/PRODUCT.md#620
TheGreatAxios merged 2 commits into
mainfrom
cl-7003-docsarchitecturemd-and-productmd-describe-the-loop-control

Conversation

@TheGreatAxios

@TheGreatAxios TheGreatAxios commented Aug 24, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • docs/ARCHITECTURE.md and docs/PRODUCT.md described a loop-control subsystem (repetition detection, tool-fingerprint thrash/backstop, requireEdit, never-acted/never-edited/no-progress/repetition stop classes, hard-blocked re-dispatch, default 30-turn leaf cap) that was deleted in a recent release. Rewrote those sections to describe current behavior, verified line-by-line against the tree.
  • No code changes.

What changed and why

ARCHITECTURE.md

  • SubAgentDirector paragraph: removed never-acted/never-edited/no-progress/repetition/requireEdit; described the surviving stops (complete, incomplete-report/incomplete-report-stop, turn-budget only when maxTurns is finite, report-forced, cancelled) and that requireEvidence only checks reads (shell reads included via shell-evidence.ts), with no write-evidence requirement.
  • Same-brief ledger: it counts dispatches and gives advisory hints (retry with higher maxTurns, then suggest a different approach after 3 same-brief turn-budget salvages) but never refuses a re-dispatch — the hard-block is gone.
  • Model-family policy / main-session loop protection: removed the entire tool-fingerprint exact-period thrash detector, hard-pause, and turns-since-user-message backstop description (with its fleet-heavy exemption) — none of it exists in src/agent/director.ts anymore. Main-session loop protection is now the one-shot toolOnlyNudgeFired check-in nudge only; there is no automated stop for the primary session.
  • Sub-agent stall paragraph: stalled now compares itself to turn-budget/cancelled, not to the deleted stop classes.
  • Precedence paragraph: stall sits below turn-budget only (no-progress no longer exists).
  • Watchdog exemption (~line 377): rewrote to say the task tool exemption is unconditional, not because the leaf is otherwise bounded — maxTurns is unbounded by default, deadlineMs is opt-in, and there is no no-progress/thrash stop.
  • Removed the "hard cap 4 workers" line from the Skywalker system-prompt description — CL-7001 is removing the same claim from the actual prompt text (src/agent/prompts.ts, skywalker/package.ts) since no concurrency cap exists in code; landing both changes keeps prompt and doc consistent.

PRODUCT.md

  • Removed the "hard cap 4 workers" claim (line 145) — no concurrency cap exists anywhere in src/; it survived only as prompt wording, not enforcement.
  • Rewrote the worker hard-stop paragraph (line 162) to remove the "2 consecutive identical tool calls" / no-progress claim and describe the actual leaf stops (incomplete-report-stop, turn-budget only when finite, stalled, cancelled/deadlineMs).
  • Rewrote the same-brief fingerprint paragraph (line 163): it's an advisory parent hint after repeated turn-budget salvage, not a refusal.

Found beyond the listed scope

  • src/subagent/intervention-log.ts has a stale doc comment citing IDENTICAL_REPEAT_MIN and TURNS_SINCE_USER_MESSAGE_BACKSTOP (both deleted). Not fixed here: this PR stays docs-only, and an in-session request to fix it mid-review was blocked by the harness's own src/-write guard, which is correctly enforcing that boundary while other lanes touch src/subagent/. Flagging for a follow-up.
  • ARCHITECTURE.md's "fix for four prior mechanisms" claim (fleet authority tiers section) was checked against current code and is still accurate as written — left unchanged.

Test plan

  • bun run check (lint/typecheck/build/test) — all green, 5340 tests passed, 0 failures.

No CHANGELOG entry — docs-only change.

@linear-code

linear-code Bot commented Aug 24, 2026

Copy link
Copy Markdown

CL-7003

…trol subsystem

repetition.ts, period-detection.ts, the tool-fingerprint thrash/backstop
checks, requireEdit, never-acted/never-edited/no-progress/repetition stop
classes, the hard-block re-dispatch refusal, and the default 30-turn leaf
cap are gone. Describe the leaf stops, the fleet dispatch ledger, the
task-tool watchdog exemption, and the primary-session nudge as they
actually behave today instead of citing deleted files and thresholds.
CL-7001 is removing the same claim from the actual prompt text
(src/agent/prompts.ts, skywalker/package.ts) since no concurrency cap
exists in code. Removing it here too so the two land consistent.
@TheGreatAxios
TheGreatAxios force-pushed the cl-7003-docsarchitecturemd-and-productmd-describe-the-loop-control branch from b3e70ba to 5486df0 Compare August 24, 2026 13:46
@TheGreatAxios
TheGreatAxios merged commit c9140b1 into main Aug 24, 2026
5 checks passed
TheGreatAxios added a commit that referenced this pull request Aug 27, 2026
…PRODUCT.md (#620)

* docs: correct ARCHITECTURE.md and PRODUCT.md for the deleted loop-control subsystem

repetition.ts, period-detection.ts, the tool-fingerprint thrash/backstop
checks, requireEdit, never-acted/never-edited/no-progress/repetition stop
classes, the hard-block re-dispatch refusal, and the default 30-turn leaf
cap are gone. Describe the leaf stops, the fleet dispatch ledger, the
task-tool watchdog exemption, and the primary-session nudge as they
actually behave today instead of citing deleted files and thresholds.

* docs: drop the stale hard-cap-4-workers prompt description

CL-7001 is removing the same claim from the actual prompt text
(src/agent/prompts.ts, skywalker/package.ts) since no concurrency cap
exists in code. Removing it here too so the two land consistent.
TheGreatAxios added a commit that referenced this pull request Aug 27, 2026
…PRODUCT.md (#620)

* docs: correct ARCHITECTURE.md and PRODUCT.md for the deleted loop-control subsystem

repetition.ts, period-detection.ts, the tool-fingerprint thrash/backstop
checks, requireEdit, never-acted/never-edited/no-progress/repetition stop
classes, the hard-block re-dispatch refusal, and the default 30-turn leaf
cap are gone. Describe the leaf stops, the fleet dispatch ledger, the
task-tool watchdog exemption, and the primary-session nudge as they
actually behave today instead of citing deleted files and thresholds.

* docs: drop the stale hard-cap-4-workers prompt description

CL-7001 is removing the same claim from the actual prompt text
(src/agent/prompts.ts, skywalker/package.ts) since no concurrency cap
exists in code. Removing it here too so the two land consistent.
@TheGreatAxios
TheGreatAxios deleted the cl-7003-docsarchitecturemd-and-productmd-describe-the-loop-control branch August 28, 2026 00:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant