From a49c572f770b541663d5ac047e5b5bf8ac42ed38 Mon Sep 17 00:00:00 2001 From: John Preston Date: Sun, 23 Aug 2026 08:21:14 +0400 Subject: [PATCH] [ai] Keep task review and testing focused and convergent --- .agents/shared/test-loop.md | 53 ++- .agents/skills/continue/SKILL.md | 11 + .agents/skills/perform-task/SKILL.md | 47 ++- .../perform-task/references/phase-prompts.md | 308 +++++++++++++----- .../perform-task/references/pipeline.md | 243 +++++++++----- .agents/skills/process-inbox/SKILL.md | 22 +- 6 files changed, 486 insertions(+), 198 deletions(-) diff --git a/.agents/shared/test-loop.md b/.agents/shared/test-loop.md index de0a099a8c..8cde4898cc 100644 --- a/.agents/shared/test-loop.md +++ b/.agents/shared/test-loop.md @@ -26,7 +26,9 @@ assessment, recovery, and reporting. already-satisfied outcome; - available commands, toolchains, targets, executables and UI-driver capabilities; -- MAX_ATTEMPTS and MAX_TEST_RUNS. +- MAX_ATTEMPTS, MAX_TEST_RUNS, and MAX_TEST_CAMPAIGNS. The default campaign + bound is two total: one normal campaign and at most one focused recovery + campaign. No instrument is globally mandatory. Its prerequisites become mandatory only after assessment selects a check that needs it. @@ -46,8 +48,10 @@ TEST_FLAW: IMPL_BUG: a sound check exposed a defect; fix the implementation, run targeted general - and affected-specialist review, retain the next implementation attempt, then - rerun only invalidated checks. + and invalidated-specialist review while carrying prior approvals forward, + retain the next implementation attempt, then rerun only invalidated checks. + Use the perform-task convergence gate after two non-converging bug fixes or + any architectural/scope expansion. UNRECOVERABLE: a required subject or capability cannot be reached safely after independent @@ -103,16 +107,20 @@ surface. Record before each recovery: - next direct instrument; - why it executes the changed surface and preserves an independent oracle. -When the flaw's cause is the instrument idiom rather than this task's fixture, -repair the harness in the same run, not only the overlay: add the missing -helper to `Telegram/SourceFiles/test/`, tighten an existing contract so the -failed technique becomes unreachable, or add the symptom to that directory's -README failure-diagnosis table. Prefer making the technique impossible over -documenting that it is forbidden — the repair that retired the unbounded probe -accessor also exposed a check that had been passing vacuously in two earlier -runs, which a written rule would not have caught. A diagnosis left in one -task's notes is rediscovered by the next task at full campaign cost, and this -is the mechanism that stops it. +When the flaw's cause is a reusable instrument idiom rather than this task's +fixture, do not silently expand a product task's retained implementation into +shared harness work. Recover the current proof with a safe inventoried +disposable overlay/helper when possible, and record a concrete discovered +workflow follow-up to add or tighten the shared helper and its self-test. That +follow-up gets its own implementation, review, evidence, and `[ai]` commit +intent. If no safe disposable recovery can decide the current task without the +permanent harness repair, stop at the bounded recovery boundary and name that +dependency instead of mixing purposes in one task. + +For a task whose requested outcome is itself the shared harness repair, retain +the change directly: prefer making a bad technique impossible over merely +documenting that it is forbidden, and verify the helper with focused harness +self-tests rather than an unrelated Telegram feature campaign. Before writing any local overlay helper, search that directory first. An overlay that reimplements a shared facility is itself a TEST_FLAW risk: the @@ -133,11 +141,20 @@ The directness ladder is task-dependent: subject. After a repeated signature, use a fresh recovery assessment and forbid the -failed technique. MAX_TEST_RUNS closes one campaign, not the task: preserve -passes, isolate unmet checks, and either start focused recovery with a different -instrument or prove every applicable strategy unsafe, unavailable, or -non-causal in a Recovery exhaustion table. Time spent, the cap, repeated -failure, probe complexity, and a blank screenshot are not exhaustion. +failed technique. MAX_TEST_RUNS closes the normal campaign, not the task: +preserve passes, isolate unmet checks, and either start one focused recovery +campaign with a different instrument or prove every applicable strategy unsafe, +unavailable, or non-causal in a Recovery exhaustion table. The focused campaign +runs only unmet checks and their controls. + +Do not start a third campaign. At the focused campaign cap, or after the same +focused failure signature repeats without a new directness step, run one final +independent assessment. It either records genuine recovery exhaustion or +returns a hard stop naming the still-plausible direct strategy and the human or +environment decision needed to continue. A cap, elapsed time, repeated failure, +probe complexity, and a blank screenshot are not exhaustion and never become +approval or a task `Block` by themselves; the hard stop leaves the task +`in-progress` and recoverable. ## Assessment diff --git a/.agents/skills/continue/SKILL.md b/.agents/skills/continue/SKILL.md index e45da78e18..e57e7d3d09 100644 --- a/.agents/skills/continue/SKILL.md +++ b/.agents/skills/continue/SKILL.md @@ -342,9 +342,20 @@ After it returns, require one of: canonical AI master; - source checkout clean and task exceptionally `blocked` on canonical master, with exact unverified behavior; +- a pre-source `Scope: split-required` or review-convergence + `RESCOPE_REQUIRED` boundary with `work/split-proposal.md`, leaving the task + `in-progress` and all source/task recovery intact; or - a clearly reported global hard stop, leaving the task `in-progress` and all task-scoped local state recoverable for the next invocation. +A rescope boundary stops this invocation and is reported to the human; it is +not retried, approved, blocked, or routed as an ordinary discovered follow-up. +On a later invocation, a performer that finds the same unresolved boundary +returns it immediately without rerunning planning, review, builds, or tests. +Inbox planning prevents most new oversized tasks; replacing an already-active +task and deciding how to salvage its source is a deliberate queue mutation, +not authority the scheduler should infer. + Before accepting a canonical test block, read `work/result.md` and `work/test.md`. It is genuine only when the verdict is not `TEST_FLAW`, does not cite `MAX_TEST_RUNS` or a missing/blank capture as the blocker, and diff --git a/.agents/skills/perform-task/SKILL.md b/.agents/skills/perform-task/SKILL.md index 3cb517f316..229d0f3c8b 100644 --- a/.agents/skills/perform-task/SKILL.md +++ b/.agents/skills/perform-task/SKILL.md @@ -119,9 +119,18 @@ produces: 3. one canonical `Approve ` commit containing all final AI artifacts and state. -New and unfinished tasks use the single adaptive `implement` path. During -assessment, select one mandatory general review, every specialist review whose -failure surface is present, and a falsifiable evidence plan. The evidence loop +New and unfinished tasks use the single adaptive `implement` path. Assessment +must first confirm that the request is one cohesive implementation/review/test +unit. If it contains independently useful and independently testable product +boundaries, record `Scope: split-required` and a concrete split proposal before +source edits, then stop for queue rescoping; do not force the broad request +through smaller implementation phases and call it one task. + +For a cohesive task, select one mandatory general review and a falsifiable +evidence plan. The first general review uses the complete implementation as the +safety net and chooses specialist reviews only for concrete material questions +that benefit from focused tracing or repository search. Surface presence is a +recall prompt, not an automatic specialist. The evidence loop may use static readings, commands and artifacts, unit tests, a standalone probe or component binary, a Telegram Debug build with logged assertions, an in-app overlay, Computer Use, screenshots, or any necessary combination. Do not @@ -129,13 +138,22 @@ require a portable account, Telegram executable, or desktop unless a selected check uses it. Do not weaken a runtime or visual check merely because another instrument is cheaper. -The assessment's selection is provisional until implementation exists. The -general reviewer examines the complete diff and evidence plan, may require a -missing specialist or stronger instrument, and cannot defer a concern to an -optional reviewer. Review fixes receive targeted re-review instead of an -unconditional replay of every lens. A task whose desired outcome was already -present may finish without a source commit only after the same general review -and evidence loop prove `Outcome: already-satisfied`. +The general reviewer examines the complete diff and evidence plan, may require +a specialist or stronger instrument, and cannot defer a concern to an optional +reviewer. Its approval and every clean specialist result carry forward. A fix +invalidates only the findings, changed invariants, specialists, validations, +and evidence checks it actually affects. Review fixes receive a focused general +delta review plus only those invalidated specialists; they do not restart the +full review or evidence design. + +Automatic replay is bounded. If two review verdicts need changes, findings are +not converging, or a fix expands the architecture or owned paths, run the +pipeline's independent convergence assessment instead of another broad round. +It chooses a bounded focused repair, a coherent replan, or `RESCOPE_REQUIRED`; +unresolved findings are never approved merely to meet the bound. A task whose +desired outcome was already present may finish without a source commit only +after the same general review and evidence loop prove +`Outcome: already-satisfied`. Only a genuine exhausted task blocker produces a canonical `Block ` commit. Agent interruption, tool loss, and @@ -146,10 +164,11 @@ A repeated evidence setup failure is not exhausted recovery by itself. Follow the shared directness ladder: forbid the failed command, fixture, probe, or capture technique and make the next run closer to the changed surface. The configured test-run cap closes one campaign: preserve prior passes, isolate the unmet -checks, and start a focused recovery campaign unless a fresh assessment proves -every direct strategy exhausted. The cap and a `TEST_FLAW` can never by -themselves publish `BLOCKED`; the former two-identical-signature shortcut must -not be used. +checks, and start at most one focused recovery campaign unless a fresh +assessment proves every direct strategy exhausted. A second campaign cap or a +repeated non-converging focused signature stops automatic work for an explicit +human/convergence decision; it does not start another campaign. A cap and a +`TEST_FLAW` can never by themselves publish `BLOCKED` or approval. A locked macOS session is not an environment stop or evidence blocker for a selected Telegram runtime check. Skip interactive Computer Use and complete diff --git a/.agents/skills/perform-task/references/phase-prompts.md b/.agents/skills/perform-task/references/phase-prompts.md index bb06396bbc..d26f031f7c 100644 --- a/.agents/skills/perform-task/references/phase-prompts.md +++ b/.agents/skills/perform-task/references/phase-prompts.md @@ -22,8 +22,9 @@ every applicable placeholder: ``, ``, ``, ## Orchestration Rules -- When delegation is available, use a fresh subagent for Phase 1 (context and plan), Phase 3, each Phase 4 implementation unit, each Phase 6 general review pass, each surviving Phase 6 specialist, and each Phase 6 fix. Do not switch those phases to same-session midstream because of a timeout or missing artifact. -- The mandatory general reviewer runs first and alone on the complete diff, and emits the retirement list. Surviving specialist reviews are independent and write disjoint reports, so spawn them together when capacity allows, giving them the diff and the retirement decision but never the general reviewer's findings. The general reviewer then returns, confirms or drops their findings, reconciles the evidence design, and owns the overall verdict. +- When delegation is available, use a fresh subagent for Phase 1 (context and plan), Phase 3, each Phase 4 implementation unit, the initial Phase 6 general review, each selected specialist, each Phase 6 fix, each focused re-review, and any convergence assessment. Do not switch those phases to same-session midstream because of a timeout or missing artifact. +- The initial mandatory general reviewer runs first and alone on the complete diff, and emits a specialist decision table with one concrete material question for every selected lens. Selected specialists are independent and write disjoint reports, so spawn them together when capacity allows, giving them the diff and their question but never the general reviewer's findings. When the host supports continuing the saved general-review agent, send synthesis back to that agent; otherwise use one fresh synthesis agent with the saved general report and specialist reports instead of making it rediscover the whole review. +- After a fix, use the focused re-review prompt: one mandatory general reviewer over the fix and affected invariants, plus only specialists whose recorded question or blocker the fix invalidated. Carry every other approval forward. Do not schedule a lens from surface presence alone. - Treat delegation as selected only after the first real phase spawn succeeds; tool presence is insufficient. An immediate depth/capacity/policy rejection before phase work selects same-session checklists and is not a delegated retry. - Phase 7 runs in the current session on native, non-WSL Windows because it depends on the final local diff and touched-file set. Skip it on WSL and keep files LF/no-BOM there. - Write each phase prompt to `/logs/phase-.prompt.md` before execution. @@ -43,7 +44,7 @@ every applicable placeholder: ``, ``, ``, is the completion signal; there is no polling, no heartbeat-mtime ladder, and no stall windows. On return, validate the artifact-based completion checks below before treating the phase as done. -- Spawn the independent leaves of one step — the surviving Phase 6 specialists, +- Spawn the independent leaves of one step — the selected Phase 6 specialists, or assessed-disjoint Phase 4 units — as parallel Agent calls in a single message so they run concurrently. - If a returned leaf fails its completion check, retry that disposable phase @@ -57,7 +58,7 @@ every applicable placeholder: ``, ``, ``, - When this session is a top-level `/perform-task`, run each leaf as one blocking `spawn_subagent` (`background: false`). The call returning is the completion signal; validate the artifact checks below on return. -- Spawn the independent leaves of one step — the surviving Phase 6 specialists, +- Spawn the independent leaves of one step — the selected Phase 6 specialists, or assessed-disjoint Phase 4 units — as parallel `spawn_subagent` calls in a single message. - When this session is a `/continue` child, do not call `spawn_subagent`. @@ -70,6 +71,9 @@ every applicable placeholder: ``, ``, ``, ### Codex: asynchronous spawn and wait - Store the canonical target returned by `spawn_agent`. +- After the initial general reviewer finishes pass 1, keep its canonical target. + When specialists finish, use `followup_task` on that target with the pass-2 + synthesis prompt instead of spawning a second complete-diff reviewer. - Poll with `wait_agent` for at most 60 seconds per call; use elapsed wall-clock windows for stall decisions. Use 30-60 second polls when a phase appears close to landing. - `wait_agent` is mailbox-wide and may wake for another agent or user input. A timeout is not failure. After every wake, handle new user input if any, inspect the saved target with `list_agents`, and check the expected artifact and matching progress file. - If the expected artifact exists and shows progress, wait again. @@ -121,11 +125,12 @@ Do not restate the full context, plan, diff, or long reasoning in the chat reply were made. For a project task, `project.proposed.md` must also exist and be non-empty. For a `Visual: layout` task, `visual.md` must also satisfy the visual design completion check below. -- Phase 3 is complete only when `plan.md` contains both `Phases:` in the Status section and `Assessed: yes`, or records a rejection outcome (`Fast-Path: rejected` or `Approach: rejected`) that sends the performer back to a fresh Phase 1 leaf. +- Phase 3 is complete only when `plan.md` contains both `Phases:` in the Status section and `Assessed: yes`, records a rejection outcome (`Fast-Path: rejected` or `Approach: rejected`) that sends the performer back to a fresh Phase 1 leaf, or records `Scope: split-required` and has a complete `split-proposal.md` that stops source work for queue rescoping. - Phase 4 is complete only when the target phase checkbox changed to checked and the touched-file list matches the owned write set, or the blocker explains any mismatch. - Phase 5 is complete only when the build outcome is known and the build checkbox is updated on success. -- A Phase 6 specialist is complete only when every scheduled specialist wrote `review-.md` with a `## Verdict:` line and a non-empty `## Checked` section. A report that records no checked surfaces is incomplete work. -- Phase 6 general review is complete only when `review-general.md` and `review.md` exist with a `## Verdict:` line, a non-empty `## Coverage` section, every retired lens carrying its absence assertion, every surviving lens accounted for, and every evidence check reconciled against the actual diff. +- A Phase 6 specialist is complete only when every scheduled specialist wrote `review-.md` with a `## Verdict:` line and a non-empty `## Checked` section tied to its assigned material question. A report that records no checked surface is incomplete work. +- Initial Phase 6 general review is complete only when `review1-general.md` and `review1.md` exist with a `## Verdict:` line, a non-empty `## Coverage` section, every standard lens marked `SELECT` or `OMIT` with a valid reason, every selected lens accounted for, and every evidence check reconciled against the actual diff. +- A focused Phase 6 review is complete only when `review-focused.md` and `review.md` name the fix paths and invariants, account for every carried-forward and invalidated approval, account for every rerun specialist, and reconcile only invalidated evidence checks. A convergence assessment is complete only with one exact disposition from the pipeline and its required bounded next action or split proposal. - Phase 6b is complete only when the requested fixes were applied and the post-fix build outcome is known. - Phase 3 is additionally incomplete until `test-design.md` exists, covers every acceptance surface, assigns each check a direct instrument, oracle, @@ -332,12 +337,15 @@ Do not implement code in this phase. ## Phase 3: Plan Assessment -Assessment has two rejection outcomes besides refinement, and both withhold -`Assessed: yes` and send the performer back to a fresh Phase 1 leaf: +Assessment has two approach rejection outcomes besides refinement, and both +withhold `Assessed: yes` and send the performer back to a fresh Phase 1 leaf: `Fast-Path: rejected` when the performer's same-session Phase 1 undersized the task, and `Approach: rejected` when the plan is over-engineered or over-coupled beyond step-level repair. On an approach rejection the performer appends the -assessor's named simpler direction to the Phase 1 rerun prompt. +assessor's named simpler direction to the Phase 1 rerun prompt. A third outcome, +`Scope: split-required`, means the request itself contains several independently +useful and testable product boundaries; it writes `split-proposal.md` and stops +before source edits instead of trying another plan for the same task. ```text You are a plan assessment agent. Review and refine an implementation plan. @@ -380,10 +388,10 @@ Assess the plan: beats both growing a mega-module and scattering through one; judge whether the boundary does work, not whether it is new. 5. Expected surfaces: record the surfaces this task is likely to touch and the - escalations they would imply, as a note for the reviewer. Do not select or - omit review lenses here — the general reviewer decides that with the diff in - hand, and every optional lens runs unless it retires the lens by asserting - the absence of its surface. + escalations they would imply, as a recall note for the reviewer. Do not + select or omit review lenses here — the first general reviewer decides that + with the diff in hand from concrete material questions, not surface presence + alone. 6. Evidence design: map every acceptance criterion and material shipped risk to the most direct practical instrument that can detect the negative. Allow static readings, commands/artifacts, unit tests, a standalone probe or @@ -392,7 +400,10 @@ Assess the plan: Preserve deep app testing when behavior lives in Telegram, and require tight captures for visible claims. Do not require Telegram for an isolated probe or build-stage claim it cannot strengthen. -7. Phase sizing: Each phase should be implementable by a single agent in one session. If a phase has more than about 8-10 substantive code changes, split it further. +7. Phase sizing: Each phase should be implementable by a single agent in one + session. If a phase has more than about 8-10 substantive code changes, split + the phase. Then assess the task as a whole: several well-sized phases do not + make an intrinsically broad task cohesive. 8. Visual contract (layout tasks): when visual.md exists, verify its anchors are real (the cited style tokens, fonts, and reference widgets exist), the ordered derivation is arithmetically consistent, and every quantity the @@ -412,15 +423,38 @@ Assess the plan: precedent or existing mechanism to ride on, which existing files absorb the change, and where it stays contained. The performer reruns Phase 1 as a fresh leaf with those lines as input. +11. Intrinsic scope: decide whether one fresh reviewer and one coherent + evidence campaign can judge the final retained result. Strong split signals + are multiple parts with their own useful outcome and oracle; a stable + dependency order where a later part can consume an earlier approved part; + separate network, persistence, concurrency/ownership, engine, lifecycle, or + UI boundaries; materially different fixtures or platforms; or a diff too + broad for one reviewer to reason about as one invariant set. Phase count, + changed-file count, and acceptance count are warning signals, not automatic + thresholds. Keep inseparable API-plus-only-caller changes together. -Update plan.md with your refinements. Keep the same structure but: + When this fails because of the request rather than the proposed approach, + add `Scope: split-required` to Status, do NOT add `Assessed: yes`, and write + `/split-proposal.md` with: + - why one review/test campaign is not coherent; + - the smallest independently buildable and testable replacement tasks; + - each task's shipped boundary, acceptance oracle, and dependencies; + - which current source or validated artifacts, if any, can be salvaged; + - a final integration task only when integration itself has behavior not + already proved by the component tasks. + Do not edit source and do not create or mutate queue tasks. Return + `RESCOPE_REQUIRED` to the performer. + +If you selected any rejection outcome, write only its required status, reason, +direction or split proposal and stop. Otherwise update plan.md with your +refinements. Keep the same structure but: - fix any inaccuracies - add missing steps - remove files, abstractions, and steps the task does not need — deletion is as much a refinement as addition - improve the approach if you found better patterns - ensure phases are properly sized for single-agent execution -- finalize `## Expected Surfaces` as a note for the reviewer, selecting no lens +- finalize `## Expected Surfaces` as a recall note for the reviewer, selecting no lens - finalize `## Evidence Plan`, then write `/test-design.md` with one check per acceptance surface: Claim, Changed surface, Instrument, Oracle, Window, Control, Falsifier, and Evidence. State which prerequisites are @@ -530,32 +564,39 @@ review runs for every task. The optional library is lifetime, reuse, structure, performance, and security; the general reviewer may add a specialist- review for another material risk. -For iteration R: +For the initial implementation: -1. Run the general reviewer first and alone, on the complete diff. Besides its - own review it emits the retirement list: every optional lens runs unless it - is retired, and a lens is retired only by asserting the absence of its - surface in the terms `pipeline.md` gives. Record each retirement with its - assertion. It writes review-general.md. -2. Run the surviving specialists independently and in parallel. Give them the - diff and the retirement decision, never the general reviewer's findings. - They write review-.md. -3. The general reviewer returns, confirms or drops each specialist finding - against the code, and writes the actionable review.md, accounting for - every retired and every surviving lens. -4. APPROVED closes review. NEEDS_CHANGES runs the fix phase for blocking +1. Run the general reviewer first and alone on the complete diff. It owns the + complete safety review and writes `review1-general.md` with a `SELECT` or + `OMIT` decision for every standard lens. Every `SELECT` includes one concrete + material failure question and affected paths/invariants. Surface presence is + a recall prompt, not a reason by itself. +2. Run selected specialists independently and in parallel. Give each the diff + and its exact question, never the general reviewer's findings or another + review report. They write `review1-.md`. +3. Continue the same general-review agent for synthesis when the host supports + it. Otherwise use a fresh synthesis agent that starts from + `review1-general.md`, reads the specialist reports, and opens only the code + needed to confirm their findings. It writes actionable `review1.md`. +4. `APPROVED` closes review. `NEEDS_CHANGES` runs the fix phase for blocking findings only. -5. After a substantive fix, increment R, rerun general with emphasis on the - changed hunks so it re-decides retirement there, and rerun only the - specialists whose surfaces the fix touched or whose prior blocking finding - was repaired. A fix that changed no owned source closes the loop without - another round. -There is no automatic five-lens replay, and no lens is skipped by omission: -silence retires nothing. Every review cycle must either add material coverage, -validate changed code, or close. A wording or style suggestion is non-blocking -unless it causes incorrect behavior, unsafe use, misleading build instructions, -a repository-rule violation, or a material maintenance defect. +For a fix, increment R and do not repeat the initial shape. Run one focused +general reviewer over the fix result, changed paths/functions, affected callers, +prior blockers, and invalidated evidence checks. Rerun only a specialist that +originated a repaired blocker or whose exact recorded question the fix changed. +The focused general reviewer confirms those reports and writes `review.md`, +explicitly carrying all other approvals forward. + +After two `NEEDS_CHANGES` verdicts, non-shrinking findings, architectural/scope +expansion, or loss of a reliable carry-forward boundary, run the convergence +prompt instead of another ordinary fix round. It permits at most one final +focused repair before a stop, replan, or rescope. The bound never converts an +unresolved finding into approval. + +A wording or style suggestion is non-blocking unless it causes incorrect +behavior, unsafe use, misleading build instructions, a repository-rule +violation, or a material maintenance defect. ### Shared specialist preamble @@ -568,8 +609,16 @@ Read: - /plan.md - AGENTS.md and REVIEW.md - the task specification -- the complete task diff and every changed file in full -- for R > 1, the preceding actionable review and fix result +- the complete task diff and changed files relevant to the assigned question +- the exact material review question and affected paths/invariant +- for R > 1, only the preceding actionable finding and fix result assigned to + this specialist + +Do not read another reviewer's findings. Do not search or read +`/review*` or phase-review logs beyond the exact files listed above; +root repository searches at the source checkout instead. If another review +report is exposed accidentally, disclose it and stop so only this specialist +can be rerun cleanly. Review only this task's diff under your assigned angle. Search outside the diff when your angle requires repository or call-site context, but do not report @@ -586,7 +635,8 @@ Write /review-.md: ## Lens: — iteration ## Checked - + ## Findings , pass of 2. You are a leaf and must not delegate. +initial review, pass of 2. You are a leaf and must not delegate. Read: - the task specification and every referenced input - /context.md, plan.md, visual.md when present, and test-design.md - AGENTS.md and REVIEW.md -- on pass 2 only, every review-.md the surviving specialists wrote -- the complete task diff and every changed file in full -- adjacent callers, consumers, generated/build declarations, and repository +- on pass 1, the complete task diff and every changed file in full, plus + adjacent callers, consumers, generated/build declarations, and repository precedents needed to judge integration +- on pass 2, review1-general.md, every selected review1-.md, and only the + code needed to confirm/drop a specialist finding or resolve a contradiction Independently review correctness, completeness, edge/error paths, unintended regressions, integration, proportionality, repository conventions, and the evidence design. Do not defer anything to a specialist. -On pass 1 no specialist has run yet. Besides your own review, emit the -retirement list. Every optional lens — lifetime, reuse, structure, performance, -security — runs unless you retire it, so a lens you do not mention still runs. -Retire one only by asserting the absence of its surface in the exact terms -pipeline.md gives, and write that assertion beside it; a failing clause keeps -the lens, and "documentation only" is not an assertion of absence. Name any -extra domain specialist a material risk needs. Then return: the performer runs -the surviving specialists and calls you back for pass 2. +On pass 1 no specialist has run yet. Besides your own review, emit a specialist +decision table. Mark every optional lens — lifetime, reuse, structure, +performance, security — exactly `SELECT` or `OMIT`; silence is invalid. + +`SELECT` only when the actual diff presents a concrete material failure question +for which focused tracing, call-site search, or domain expertise adds useful +independent confidence. State the question, affected paths/invariant, and the +failure it could expose. `OMIT` when the surface is absent or narrow enough that +your complete review already established its relevant invariant with no open +specialist question; state that proof. Surface presence alone, `low risk`, time +pressure, or `documentation only` is not a decision. Name any extra domain +specialist a material risk needs. Then return: the performer runs selected +specialists and calls you back for pass 2. On pass 2, confirm every specialist finding against the code; drop it when the -concrete failure does not hold. +concrete failure does not hold. Do not redo the complete general review; carry +pass 1 findings and coverage forward and open only the code needed for +synthesis or a newly contradicted invariant. Reconcile test-design.md against the actual diff: - every acceptance criterion and material new risk has a check; @@ -725,11 +784,10 @@ Reconcile test-design.md against the actual diff: - selected instrument prerequisites are explicit, and unavailable unselected instruments are not treated as blockers. -If pass 2 exposes a material risk no surviving lens covered — including one you -retired on pass 1 — write "Missing specialist: — " and return -without an implementation verdict. The performer runs that specialist, then -calls you back again in iteration R. Retiring a lens you then have to recall is -a worse outcome than keeping it, so retire only on the absence clauses. +If pass 2 exposes a concrete material question no selected lens covered, write +"Missing specialist: — " and return without an implementation +verdict. The performer runs only that specialist, then calls you back. Do not +turn a generic surface into a late specialist request. Classify findings: - BLOCKING: concrete wrong behavior, crash, race, security/data-safety failure, @@ -738,13 +796,14 @@ Classify findings: - NON_BLOCKING: optional wording, preference, speculative cleanup, or polish. Preserve it in Dropped/Notes, but do not ask the fix agent to implement it. -Write /review-general.md with Checked, specialist confirmation, +Write /review1-general.md with Checked, the specialist decision table, +specialist confirmation, evidence reconciliation, findings and verdict. Then write -/review.md: +/review1.md: -## Code Review — Iteration +## Code Review — Initial ## Coverage - + ## Evidence reconciliation ## Verdict: APPROVED | NEEDS_CHANGES | MISSING_SPECIALIST @@ -757,6 +816,88 @@ An APPROVED verdict requires no blocking finding and complete evidence reconciliation. NEEDS_CHANGES requires at least one blocking finding. ~~~ +### Focused general re-review + +~~~text +You are the mandatory focused general reviewer for one Telegram Desktop task, +review round after a blocking fix. You are a leaf and must not delegate. + +Read: +- the task specification, AGENTS.md, and REVIEW.md; +- /review.md and the fix result; +- the fixed paths, containing functions/types, and affected callers; +- test-design.md entries the fix reports invalidated; +- only the specialist reports explicitly rerun for this fix. + +Do not restart the complete-diff review. Verify each repaired blocker, inspect +the fix for regressions in its actual data/control/lifetime boundary, and check +that no undeclared path changed. For every prior general and specialist approval, +record `CARRIED` with why the fix did not touch its exact code or invariant, or +`INVALIDATED` with the concrete changed question. Presence of a broad surface is +not invalidation. + +Rerun a specialist only when it originated a repaired blocker, its exact prior +question changed, or this fix introduced a new concrete material question that +focused expertise must answer. If one is needed and has not run, write +`Missing specialist: — ` and return; the performer runs only +that specialist and calls you back. + +Reconcile only evidence checks whose changed surface, oracle, fixture, or +expected result the fix invalidated. Carry all other checks forward. + +Write /review-focused.md and /review.md with: + +## Code Review — Focused round +## Fix boundary + +## Carried approvals + +## Invalidated approvals + +## Verdict: APPROVED | NEEDS_CHANGES | MISSING_SPECIALIST | CONVERGENCE_REQUIRED +## Changes Required + + +Return `CONVERGENCE_REQUIRED` rather than another ordinary fix when this is the +second NEEDS_CHANGES verdict, findings did not shrink, the fix expanded owned +paths/architecture, or the carry-forward boundary is unreliable. +~~~ + +### Review convergence assessment + +~~~text +You are an independent review-convergence assessor for one Telegram Desktop +task. You are a leaf and must not delegate or edit source. + +Read the task, context.md, assessed plan.md, every canonical review.md, every +fix result, current owned paths, the current complete task diff, and the exact +validation/evidence status. Read source only as needed to decide disposition. + +Diagnose why review is not converging: repeated discovery in stable code, +regressions introduced by fixes, architectural coupling, oversized intrinsic +scope, or an external unsafe boundary. Preserve findings already resolved and +do not run another broad review. + +Write /review-convergence.md with exactly one verdict: + +## Verdict: CONTINUE_FOCUSED | REPLAN_CURRENT | RESCOPE_REQUIRED | HARD_STOP + +- CONTINUE_FOCUSED: one bounded list of remaining blockers, one owned write + set, the approvals carried forward, and at most one final focused review. +- REPLAN_CURRENT: why the task remains cohesive, the exact validated source + boundary to preserve or restore, and the replacement approach. Do not use + this to disguise multiple independent product outcomes as phases. +- RESCOPE_REQUIRED: why one review/evidence campaign is incoherent and a + split-proposal.md containing independently buildable/testable replacement + tasks, acceptance oracles, dependencies, and salvageable work. +- HARD_STOP: the exact unsafe or unavailable condition and required human + action. + +The verdict cannot approve code. If a permitted final focused round still has +blocking findings, stop with its unapproved artifacts; do not begin another +campaign automatically. +~~~ + ### Review fix ~~~text @@ -768,12 +909,18 @@ file named by a blocking finding. Implement only "Changes Required". Do not implement Dropped or non-blocking notes. Stay inside owned-paths.txt and do not edit AI artifacts. -After editing, run the cheapest pre-review validation affected by the fix. For -an app-source fix this is normally the configured Debug build; for an isolated -script, generated artifact, or probe it may be its focused syntax/configure or -component check. Use build-lock recovery when applicable. +After editing, run the cheapest validation that can catch breakage in the fixed +surface: a focused compile/target, syntax/configure check, unit, probe, or +component command when sufficient. Rerun the complete Telegram Debug build +immediately only when the fix changes the build graph/ABI or no focused command +can validate compilation; otherwise the performer runs the complete selected +pre-review validation once after review approval. Use build-lock recovery when +applicable. -Report exact touched paths and which review specialists the fix invalidated. +Report exact touched paths, repaired findings, changed functions/invariants, +which prior specialist question (if any) the fix invalidated and why, and which +validation/evidence checks it invalidated. Surface presence alone is not +invalidation. If no blocking finding can be acted on inside the owned write set, change nothing and report that boundary. ~~~ @@ -831,8 +978,10 @@ for independent confirmation. ## Evidence-Campaign-Cap Assessment -At MAX_TEST_RUNS with an evidence flaw still open, use a fresh assessor. The cap -is a convergence checkpoint, never a terminal verdict. +At MAX_TEST_RUNS with an evidence flaw still open, use a fresh assessor. The +first campaign cap may start one focused recovery campaign. A focused campaign +cap or repeated non-converging focused signature is the final automatic +checkpoint; it cannot start a third campaign. ~~~text Read the task, final diff, plan.md, test-design.md, test.md, every run artifact, @@ -850,9 +999,10 @@ Write /test-cap-assessment-.md: -## Verdict: FOCUSED_RECOVERY | RECOVERY_EXHAUSTED +## Verdict: FOCUSED_RECOVERY | RECOVERY_EXHAUSTED | HARD_STOP -Choose FOCUSED_RECOVERY whenever a safer or more direct reading, command, +Choose FOCUSED_RECOVERY only after the normal campaign and whenever a safer or +more direct reading, command, artifact inspection, unit, probe, component, Telegram log/overlay, physical interaction or visual capture can still decide an unmet check. The next campaign runs only unmet checks and their controls. @@ -861,6 +1011,12 @@ Choose RECOVERY_EXHAUSTED only when every applicable instrument is unsafe, unavailable, or would bypass the task's changed surface. Time spent, a run cap, overlay complexity, a blank screenshot, or repeated identical failure is not exhaustion. + +At the focused campaign boundary, choose HARD_STOP when a plausible safe direct +strategy remains but automatic recovery did not converge. Name that strategy, +the exact prior proof retained, and the human/environment decision needed to +continue. Leave the task in-progress; do not publish approval or Block and do +not begin another campaign automatically. ~~~ diff --git a/.agents/skills/perform-task/references/pipeline.md b/.agents/skills/perform-task/references/pipeline.md index fad3591676..b6afc3e132 100644 --- a/.agents/skills/perform-task/references/pipeline.md +++ b/.agents/skills/perform-task/references/pipeline.md @@ -63,6 +63,7 @@ out/Debug/Telegram.app/Contents/MacOS/Telegram MAX_ATTEMPTS = 4 MAX_TEST_RUNS = 12 per test campaign +MAX_TEST_CAMPAIGNS = 2 total: one normal and at most one focused recovery COMPUTER_USE_POLICY = auto | overlay-only | required ``` @@ -138,9 +139,13 @@ work/context.md work/project.proposed.md # project tasks only work/visual.md # layout tasks only work/plan.md -work/review1-general.md # mandatory independent review and verdict -work/review1-.md # only specialists selected by assessment -work/review1.md # actionable overall verdict for the iteration +work/split-proposal.md # only when assessment rejects intrinsic scope +work/review1-general.md # mandatory complete-diff review and selection +work/review1-.md # specialists selected for material questions +work/review1.md # canonical first-review verdict +work/review-focused.md # mandatory focused general re-review, R > 1 +work/review-.md # only specialists invalidated by the fix +work/review-convergence.md # bounded loop disposition when needed work/test-design.md # assessed evidence contract, reconciled after diff work/test.md work/test-cap-assessment-*.md # independent focused-recovery decision at a campaign cap @@ -206,9 +211,11 @@ prompts, plus the host-specific orchestration rules. touch and the change is mechanical — roughly two source files or fewer, no new APIs, strings, or style tokens, no layout derivation. When in doubt, delegate. Assessment always runs as a fresh leaf and has the authority to - reject the fast-path sizing or the plan's whole approach as over-engineered; - either rejection forces a Phase 1 leaf rerun, an approach rejection with the - assessor's simpler direction added to the prompt. + reject the fast-path sizing, reject the plan's whole approach as + over-engineered, or reject the task itself as several independently testable + product boundaries. Fast-path and approach rejection force a Phase 1 leaf + rerun; intrinsic scope rejection writes the split proposal and stops before + source edits so queue planning can replace the task. - Use `fork_turns: "none"` with explicit paths. Fork the smallest turn window only for genuinely unavailable chat-only visual context. - Inherit the parent's model and reasoning level. Do not invent tool fields. @@ -256,11 +263,19 @@ Run sequentially: duplication, edge cases, repository conventions, and phase sizing; weigh the approach against the closest repository precedent and its containment against the shared modules it touches, and reject over-engineering rather - than refining it; on layout tasks verify the visual contract's anchors and - derivation; on a fast-path plan verify the sizing itself. Require + than refining it. Before approving the plan, apply the intrinsic-scope gate: + if it contains several useful boundaries with separate acceptance or + evidence, stable dependency order, or materially different subsystems and + failure analysis, write `work/split-proposal.md`, record + `Scope: split-required`, and stop before source edits. Phase count and line + count are warning signals, not automatic decisions; the decisive question + is whether one fresh reviewer and one coherent evidence campaign can judge + the retained result. On layout tasks verify the visual contract's anchors + and derivation; on a fast-path plan verify the sizing itself. Require `Phases: ` and `Assessed: yes`, or a recorded `Fast-Path: rejected` / `Approach: rejected` outcome that reruns Phase 1 as a fresh leaf — an - approach rejection with the assessor's simpler direction as added input. + approach rejection with the assessor's simpler direction as added input — + or the terminal pre-edit `Scope: split-required` planning boundary. 3. **Implement.** Run one leaf per assessed plan phase. Before each edit, update `work/owned-paths.txt`. A leaf edits only its owned paths and its phase status; it does not commit. @@ -273,22 +288,27 @@ Run sequentially: cleanup and build-lock recovery only to a command that writes the configured build tree. 5. **Review.** Run the adaptive review/fix loop from the phase prompts. The - independent general reviewer always runs over the complete diff, adjacent - integration, task contract, and `work/test-design.md`. Before it, run every - specialist selected by assessment: lifetime (including concurrency and - races), reuse, structure, performance, security, or a named domain review. - The general reviewer confirms or drops their findings, adds any missing - specialist or evidence check, and writes the single `review.md` the fix - phase implements. Only material blocking findings cause a fix. After a fix, - rerun the general review plus specialists whose surfaces changed; never - replay unrelated lenses. Rebuild or rerun a cheaper pre-review check only - when the fix touched that instrument's surface. + first independent general reviewer always examines the complete diff, + adjacent integration, task contract, and `work/test-design.md`, and selects + specialists for concrete material questions. It confirms or drops their + findings and writes the single `review1.md` the fix phase implements. Only + material blocking findings cause a fix. After a fix, preserve every prior + approval that the fix did not invalidate: run one focused general review of + the fix and affected invariants, plus only the specialists that originated a + repaired blocker or whose exact review question the fix changed. Presence of + a broad surface is not enough to replay it. Reconcile only invalidated + evidence checks and rerun only affected validation. At the convergence + triggers below, stop the ordinary loop and obtain an explicit repair, + replan, or rescope disposition. 6. **Normalize.** On native non-WSL Windows, normalize only task-owned source, header, style, localization, and build/config text to CRLF without BOM, preserving content and trailing-newline state, then rerun the selected pre-review validation when normalization could affect it. On macOS, Linux, and WSL preserve LF/no-BOM. -7. **Commit and test.** When the task changed source, create the implementation +7. **Commit and test.** If any review fix followed the last complete selected + pre-review validation, run that complete validation once after review + approval; focused per-fix checks do not replace this final gate. When the + task changed source, create the implementation commit with the scripted helper, then run the evidence loop below: ```bash @@ -332,77 +352,111 @@ Evidence plan: - Evidence: ``` -Assessment does not choose reviewers. The general reviewer does that with the -diff in hand, and `Expected surfaces` is a note for it, not a decision. -Assessment rejects ceremony as well as under-testing: it removes checks that -cannot be affected by the task. +Assessment does not choose reviewers. The first general reviewer does that with +the diff in hand, and `Expected surfaces` is a recall checklist rather than an +automatic decision. Assessment rejects ceremony as well as under-testing: it +removes checks that cannot be affected by the task. ### Review selection -Selection happens with the diff in hand, never before it. Assessment records -the surfaces it expects and the escalation triggers it can name, but it does -not choose reviewers: a lens picked from the task text is a prediction, and -the hazards that matter are routinely invisible until the implementation -exists. A task reading `open a different page` produced a use-after-free that -only the diff showed. +Selection happens with the implementation in hand. Assessment records expected +surfaces and escalation triggers, but a task-text prediction neither schedules +nor omits a reviewer. -The independent **general** review therefore runs first, alone. It reads every -changed file in full and owns correctness, completeness, adjacent integration, -unintended regressions, proportionality, repository conventions, and the -adequacy of the evidence plan. It cannot defer a concern to a specialist. +The independent **general** review runs first, alone, exactly once for the +initial implementation. It reads every changed file in full and owns +correctness, completeness, adjacent integration, unintended regressions, +proportionality, repository conventions, and evidence adequacy. It cannot defer +a concern to a specialist. This complete-diff pass is the mandatory safety net. -Its first output is the **retirement list**. Every specialist below runs unless -the general reviewer retires it, so a lens nobody considered still runs. Retire -one only by asserting the absence of its surface in the terms given, and record -each retirement with that assertion in `review.md`: +Its first output is a **specialist decision table**. Account for every lens +below with `SELECT` or `OMIT`; silence is invalid. Select a specialist only when +the diff creates a concrete material failure question that focused tracing, +call-site search, or domain expertise is likely to answer better than the +general pass alone. Record that question, the affected paths or invariant, and +what a failure would do. Omit it when the surface is absent, or when the surface +is narrow and the general reviewer has already established the relevant +invariant with no unresolved specialist question. `Low risk`, time pressure, +and `documentation only` are not sufficient reasons by themselves. -- **lifetime** — owns object and resource ownership, callbacks, re-entrancy, +The lens surfaces are recall prompts, not automatic retention clauses: + +- **lifetime** — object and resource ownership, callbacks, re-entrancy, destruction order, threads, concurrency, races, synchronization, - cancellation, and shutdown. Retire only when the diff adds or changes no - owner, stores nothing past its call, registers no callback or subscription, - touches no destruction or teardown path, and crosses no thread or async - boundary. -- **reuse** — owns duplication of an established helper, API, style, string, - switch, algorithm, or mechanism. Retire only when the diff introduces none - of those and edits existing call sites alone. -- **structure** — owns cross-module placement, broad moves or deletion, - generated files, build graphs, platform containment, and new abstractions. - Retire only when the diff adds, moves and deletes no file, changes no build - graph or generated output, and crosses no module or platform boundary. -- **performance** — owns hot or repeated paths, main-thread blocking, startup, - memory, I/O, scale, and material build-time cost. Retire only when the diff - adds nothing to a repeated, hot or startup path, adds no allocation, I/O or - blocking work there, and adds no material build-time cost. -- **security** — owns secrets, authentication, permissions, privacy, - cryptography, untrusted input, command or subprocess construction, - filesystem boundaries, downloads, network trust, and destructive behavior. - Retire only when the diff touches none of them. + cancellation, and shutdown; +- **reuse** — duplication of an established helper, API, style, string, switch, + algorithm, or mechanism; +- **structure** — cross-module placement, broad moves or deletion, generated + files, build graphs, platform containment, and new abstractions; +- **performance** — hot or repeated paths, main-thread blocking, startup, + memory, I/O, scale, and material build-time cost; +- **security** — secrets, authentication, permissions, privacy, cryptography, + untrusted input, command or subprocess construction, filesystem boundaries, + downloads, network trust, and destructive behavior. -One failing clause keeps the lens. The test is presence of the surface, not an -estimate of how risky it looks: presence is checkable by the next reader and -severity is not, and severity judged under time pressure drifts optimistic. -`documentation only` is not an assertion of absence; the clauses above are. +The general reviewer may add a named domain specialist when a material risk +such as ABI portability or persistence migration fits none of the lenses. -The general reviewer may also add a named domain specialist when a material -risk such as ABI portability or persistence migration fits none of the lenses. +Run selected specialists independently and in parallel. Give each the task +diff, its exact material review question, and source paths, but never the +general reviewer's findings or another review report. Specialist source search +is rooted at `SOURCE_ROOT`; it must not search or read `WORK_DIR/review*` or +phase-review logs beyond the explicit input list. Accidental exposure is +reported and invalidates only that specialist, not already independent work. -Then run the surviving specialists independently and in parallel. Give them the -diff and the retirement decision, never the general reviewer's findings: a -specialist that reads them anchors on them, and the independence of the lenses -is what lets the synthesis drop a finding another lens refutes. +A specialist reports only material findings with a concrete failure. Reuse the +same general reviewer for synthesis when the host supports continuing that +agent; otherwise a fresh synthesis reviewer starts from the saved general +report and specialist reports, then reads only code needed to confirm or drop +their findings. It writes the sole `review1.md` verdict and accounts for every +lens decision. Wording, style, or optional cleanup that does not cause wrong +behavior, unsafe use, material maintenance cost, or a repository-rule violation +is non-blocking and never starts a fix cycle. -A specialist reports only material findings with a concrete failure. The general -reviewer then returns, confirms each one against the code, and writes the sole -`review.md` verdict, which accounts for every retired and every surviving -lens. Wording, style, or optional cleanup that does not cause wrong behavior, -unsafe use, material maintenance cost, or violated repository rules is -non-blocking and never starts a fix cycle. +### Focused re-review and convergence -After a blocking fix, repeat the same shape against what the fix changed: -general reruns with emphasis on the changed hunks and re-decides retirement -there; only specialists whose surfaces the fix touched rerun. A fix that changed -no owned source closes the loop. A new surface triggers reassessment instead of -an automatic replay of every lens. +An approval remains valid until a later edit changes the exact code or +invariant it established. Before each blocking fix, save the canonical review +and require the fix result to list its touched paths, repaired findings, changed +invariants, and invalidated validations/evidence. After the fix: + +1. run one mandatory focused general review over those edits, the containing + functions and affected callers, and the prior blocking findings; +2. rerun only a specialist that originated a repaired blocker or whose recorded + material question the fix actually changed; +3. reconcile only evidence checks invalidated by the fix; and +4. carry every other general, specialist, validation, and evidence approval + forward explicitly. + +The focused general reviewer owns synthesis. It may add a specialist only for a +new concrete material question introduced by the fix. Merely touching an async, +storage, build, security, or other broad surface does not invalidate every lens +that could describe it. It reads the complete task diff only when the fix has +made the previous review boundary unreliable, in which case it triggers the +convergence assessment rather than silently restarting the initial review. + +Stop the ordinary fix loop and run a fresh independent convergence assessment +when any of these holds: + +- two canonical review verdicts have required changes; +- blocker count or affected scope did not materially shrink after a fix; +- a fix adds owned paths, a subsystem, a build/platform boundary, or a new + ownership, concurrency, persistence, or trust mechanism; or +- the reviewer can no longer state which prior approvals remain valid. + +The assessor writes `review-convergence.md` with exactly one disposition: + +- `CONTINUE_FOCUSED` — one bounded fix list and at most one final focused + review round; +- `REPLAN_CURRENT` — the task remains cohesive, but implementation returns to + an explicitly named validated boundary and a replacement plan before review; +- `RESCOPE_REQUIRED` — the task contains independently testable product + boundaries; write or update `split-proposal.md` and stop automatic work; or +- `HARD_STOP` — an exact unsafe or unavailable condition needs human action. + +If the allowed final focused round still has blocking findings, stop with the +unapproved convergence artifact. Never approve unresolved findings and never +start another broad review campaign merely because time remains. ### Evidence selection @@ -626,11 +680,15 @@ For every instrument, assessment returns exactly one of: after the bounded directness assessment. A `TEST_FLAW` recovery must remove an assumption or move closer to the changed -surface. Do not repeat the same command, fixture, or overlay wording. A campaign -cap is an assessment checkpoint, not permission to block: carry prior passes, -isolate unmet checks, and choose a more direct instrument or document recovery -exhaustion. An `IMPL_BUG` fix creates a new retained attempt, triggers targeted -general/specialist re-review, and reruns only invalidated checks. +surface. Do not repeat the same command, fixture, or overlay wording. The normal +campaign cap is an assessment checkpoint: carry prior passes, isolate unmet +checks, and choose at most one focused recovery campaign or document recovery +exhaustion. A focused campaign that does not converge stops automatic work with +an exact recoverable hard stop; it never starts a third campaign or converts the +cap into approval/Block. An `IMPL_BUG` fix creates a new retained attempt, uses the same +focused general/invalidated-specialist review and convergence triggers as the +pre-commit loop, and reruns only invalidated checks. It never restarts the +initial complete-diff review simply because the attempt number changed. The evidence author reads the full task, assessed plan, final task diff, and existing `test-design.md`. It covers every acceptance surface and nothing @@ -758,6 +816,14 @@ delays finishing the work actually in hand. ## Failure handling +- `Scope: split-required` before source edits and `RESCOPE_REQUIRED` from a + convergence assessment are planning boundaries, not task `Block` verdicts + and not permission to keep retrying. Preserve `split-proposal.md`, all + validated source recovery, and the task's `in-progress` state; return the + proposal to the scheduler or human and stop automatic performance until the + queue is deliberately replaced. A resumed performer that sees the same + unresolved boundary reports it immediately without rerunning context, + implementation, review, or builds. - Source lineage has a strict timing boundary. Before Phase 1, a missing approved prerequisite is a clean pre-phase routing stop: do not publish `blocked`, edit source, or create a backport/cherry-pick/rebase/merge task. @@ -776,10 +842,11 @@ delays finishing the work actually in hand. starting new shared work. A dirty/non-buildable checkout or global environment problem stops the current invocation. - A test campaign cap is not a clean blocked attempt. Preserve the overlay and - evidence, run the cap assessment, and continue with a focused campaign while - any safe direct strategy remains. The publication helper rejects a test block - whose report still says `TEST_FLAW`, cites the run cap, or lacks the required - recovery-exhaustion record. + evidence and run the cap assessment. The normal campaign may authorize one + focused campaign; the focused campaign boundary either proves recovery + exhaustion or returns a recoverable hard stop instead of looping. The + publication helper rejects a test block whose report still says `TEST_FLAW`, + cites the run cap, or lacks the required recovery-exhaustion record. - A Windows file-lock build error follows the shared bounded exact-checkout recovery. Only exhaustion or an unsafe/non-owned holder stops the run and asks the human; the task remains `in-progress`. diff --git a/.agents/skills/process-inbox/SKILL.md b/.agents/skills/process-inbox/SKILL.md index 4ad67b850f..fc9fbf6e1b 100644 --- a/.agents/skills/process-inbox/SKILL.md +++ b/.agents/skills/process-inbox/SKILL.md @@ -108,8 +108,26 @@ essential context, and use a standalone task only when no project does. Do not create generic holding projects such as `fixes`. A release batch of unrelated regressions normally becomes standalone tasks or tasks in existing domain projects. Group requests into one task only when they form one cohesive, -independently testable behavior. Split work until every task is implementable -in one pass and has an exact observable acceptance result. +independently testable behavior that can be implemented, reviewed, and tested +as one normal pass. + +Split at product boundaries, not arbitrary file or line-count boundaries. A +request needs multiple tasks when two or more parts have their own useful +outcome and acceptance oracle, when a later part can consume an earlier part as +a stable dependency, or when the parts require materially different context, +failure analysis, or evidence setup. New network, persistence, concurrency or +ownership machinery plus application lifecycle/UI integration are especially +strong split signals when each can be exercised independently. Shared project +context, overlapping files, or one eventual feature does not by itself justify +paying one review and test loop over their combined implementation. + +Do not over-split inseparable changes: keep a small API and its only caller +together when neither has a meaningful standalone result, and keep one atomic +behavior together when separating it would leave an unbuildable or untestable +intermediate state. For every proposed task, state the one shipped boundary it +owns and the direct evidence that can approve it without first implementing a +sibling. If that sentence needs several independent outcomes or several +unrelated instruments, split again. Project slugs are unique across `projects/` and `projects/archive/`. When a request belongs to an archived project, restore it before routing to it: