diff --git a/GLOSSARY.md b/GLOSSARY.md index facf4e938..7cc1459d2 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -107,6 +107,9 @@ _Avoid_: invocation, job A **Command** that stopped at a plan-limit warning or rejection, with outcome `paused`: an **Experiment** or **Scoring run**. Its **Command record** keeps the stopping Harness and window, utilization and reset time when reported, and the command that resumes it. It waits in **Needs you** as Paused until a later Command resumes the same work or the Day shift makes a **Dismissal**. Resuming continues the same work with finished Trials and Scores kept and nothing finished repeated. This is separate from interruption, is neither success nor failure, and does not resume automatically. _Avoid_: failed Command (for a plan-limit pause) +**Quota wait**: +The time until GitHub's quota for a GitHub user resets, during which **Passes** are skipped and running **Commands** wait instead of failing. + **Ticket run**: One invocation of the factory on a single issue that is not a **Spec**, from launch to cleanup, normally ending in one pull request ready for review, or a **Self-merge** when its command or the **User config** asks for one. A Ticket run on an issue labelled `bug` reproduces the bug before fixing it, in a fresh Ticket run or a **Continuation**, except for **Flaky-test Tickets**, Security fixes and **Base fixes**, which have their own flow. A Continuation whose **Issue branch** has commits beyond the **Base branch** reproduces at their merge base, then checks the fix on the branch; a fix already there still goes on to review and the pull request. If the bug is not reproduced, including when it is absent at that merge base, the Ticket run ends successfully with triage notes and `needs-info` on the issue, without opening or merging a pull request. Started directly on an **Issue URL**, by a **Spec run** for one of its **Tickets**, by an **Architect run** for the Ticket its **Architecture review** published, by a **Pickup run** for the **Ready issue** it took, or by a **Security run** for a **Security finding** it fixes. Every Ticket run carries out a **Process**: the **Built-in process** by default, or a **Custom process** selected by the Process that starts it. That Process owns its sequence of Steps. Dispatch chooses Spec or Ticket and makes any Claim before work starts; child Ticket runs inherit their Command's choices and limits. _Avoid_: Run, Merge run (former names), auto-merge (GitHub's own feature) @@ -295,14 +298,14 @@ The token counts and cost reported in one **Session trace**, grouped by observed A **Command**'s whole tree of work, its child **Ticket runs** and all of their **Session traces** included. Their shared identity keeps the tree together across sessions. **Command log**: -Everything one **Ticket run**, **Spec run**, **Architect run**, **Pickup run**, **Security run** or **Custom process** printed, kept in a file of its own with its repository's other logs, stamped like its **Session traces**. The start stamp is for display and grouping; Commands with the same start time still have distinct storage ownership for their Command logs, Session traces and **Command records**. An Architect run's, Pickup run's, Security run's or Custom process's covers the Spec runs or Ticket runs it dispatched, and a Spec run's covers its **Ticket runs**, as a Ticket run's covers its **Base fix**: none of those keeps one of its own. It is kept once the command starts work: a Pickup run, Architect run or Security run skipped before doing any work keeps none, and neither does a Ticket run that fails before it starts work, such as on **Origin match**. +Everything one **Ticket run**, **Spec run**, **Architect run**, **Pickup run**, **Security run** or **Custom process** printed, kept in a file of its own with its repository's other logs, stamped like its **Session traces**. The start stamp is for display and grouping; Commands with the same start time still have distinct storage ownership for their Command logs, Session traces and **Command records**. An Architect run's, Pickup run's, Security run's or Custom process's covers the Spec runs or Ticket runs it dispatched, and a Spec run's covers its **Ticket runs**, as a Ticket run's covers its **Base fix**: none of those keeps one of its own. It is kept once the command starts work, or earlier when a **Quota wait** needs a visible, stoppable Command record. Without such a wait, a Pickup run, Architect run or Security run skipped before doing any work keeps none, and neither does a Ticket run that fails before it starts work, such as on **Origin match**. _Avoid_: cron log, output log, run log (a **Ticket run** is one kind of command) **Log inventory**: The retained Command logs and Session traces available to list on a machine, each naming an exact file under the User config's log folder. A Command's referenced Session traces may include files outside that inventory. **Activity log**: -One running record per repository of what the factory did there: a line when a **Ticket run**, **Spec run**, **Architect run**, **Pickup run**, **Security run**, **Triage run** or **Custom process** starts work, naming its **Command log**, a line when it is given a **Stop** or a **Dismissal**, or a Dismissal is taken back, naming who asked and whether from the CLI or the **Console**, and a line when it ends, with its outcome. A Custom process's lines name it as Process ``. A skipped Architect run, Pickup run, Security run or Triage Pass writes a line only when its reason differs from the last one recorded for its kind, so a repository that sits idle shows one line, not one per pass. A skipped Custom process started with no issue writes `Process skipped: ` when that is not already the last Process line. A warning about the **User config**, such as a setting it ignores, is written once per change. It is what thirdshift writes about a scheduled pass, in place of output to the scheduler. +One running record per repository of what the factory did there: a line when a **Ticket run**, **Spec run**, **Architect run**, **Pickup run**, **Security run**, **Triage run** or **Custom process** starts work, naming its **Command log**, a line when it is given a **Stop** or a **Dismissal**, or a Dismissal is taken back, naming who asked and whether from the CLI or the **Console**, and a line when it ends, with its outcome. A Custom process's lines name it as Process ``. A skipped Architect run, Pickup run, Security run or Triage Pass writes a line only when its reason differs from the last one recorded for its kind, so a repository that sits idle shows one line, not one per pass. A skipped Custom process started with no issue writes `Process skipped: ` when that is not already the last Process line. During a **Quota wait**, each named Custom process compares its own last reason instead, so alternating processes do not repeat an unchanged quota skip. A warning about the **User config**, such as a setting it ignores, is written once per change. It is what thirdshift writes about a scheduled pass, in place of output to the scheduler. _Avoid_: cron log, pass log, history **Command record**: diff --git a/docs/guide.md b/docs/guide.md index 399380d8a..1e0d21bcd 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -45,6 +45,8 @@ From a clone of the issue's repository, `thirdshift `: 7. In a **Ticket run** that Self-merges (`thirdshift merge `), does the **Self-merge**: once the pull request is open, ready for review, mergeable and green, thirdshift merges it into the Base branch with a merge commit, on exactly the head commit whose CI it watched (`gh pr merge --merge --match-head-commit `). Just before each attempt, it reads the PR's `reviewDecision`: `REVIEW_REQUIRED` or `CHANGES_REQUESTED` ends the Ticket run as **review required**, a policy refusal, without attempting the merge or taking another Repair round. An empty or `APPROVED` decision, or a failed read, keeps the existing merge behavior. It never uses GitHub's auto-merge ([ADR-0004](adr/0004-self-merge-by-thirdshift-not-github-auto-merge.md)). A merge that fails goes back round step 6, within the same budgets, and is tried again on the new green head. If that round finds nothing to fix, the refusal is a **policy refusal**, such as merge commits being disallowed or a review being required. After the merge, thirdshift deletes the Issue branch on `origin`, and closes the issue if it is still open, with the comment `Closed by #, merged into by a thirdshift Ticket run with Self-merge.` GitHub closes it on its own only for a merge into the repository's default branch, and then thirdshift leaves it alone. Once the issue is closed, either way, thirdshift takes `in-progress` off it, [removing the Claim](#when-the-claim-ends). 8. Cleans up: removes the worktree, the local Issue branch and the temporary directory the Factory skills were written out to, whether the Ticket run succeeded or not. The one exception is a **Failed ticket run** whose work could not be pushed: see below. +CI watch quota exhaustion follows the [Command's Quota wait policy](#delivery-and-pull-request-identity): reset plus one minute and 0–60 seconds of jitter, within a shared two-hour cap. Secondary limits retry after 60 seconds, at most five times. Neither is a CI failure or a reason to start a Repair while retries remain. + ### Worktree ownership and cleanup A factory-owned checkout, on an **Issue branch** for a **Ticket run** or detached for an **Architecture review**. @@ -63,6 +65,10 @@ See [ADR-0014](adr/0014-successful-review-acquisition-authorizes-stale-disposal. What a **Ticket run**, or a **Spec run** for its **Spec PR**, does from its worktree once its work begins. It runs the opening session (the implement session, or the **Spec review**), pushes, marks the pull request ready, keeps it mergeable and green through the **Repair loop**, and, in a **Ticket run** that Self-merges, does the **Self-merge**. +When thirdshift's own GitHub reads or writes hit primary quota exhaustion, the running **Command** records a **Quota wait**, waits until reset plus one minute and a random 0–60 seconds, then retries the same call. This includes CI watch and Delivery's pull request updates, labels, comments and Self-merge, across Ticket, Spec, Review, Fix, Security and Triage runs, Custom processes and work a Pass dispatched. The Command and its child Ticket runs share a two-hour total wait cap; a call that would exceed it fails as before. A secondary-limit failure instead waits 60 seconds and retries up to five times, without recording a Quota wait. + +While waiting, `status`, `show` and the Console show `Quota wait until