The cycle

The cycle is a job cterm runs for a project on a clock, every weekday at 8:00 for instance. It reads where the project stands (its goals, the items ready to start, its sessions, what changed since the last cycle, its monitors and your answers), judges what the last cycle did, and decides what to do now. Then cterm does only what the project's dial, the day's budget and the policy let it, writes one record of the cycle and sends you one digest. Its records are on the project page's Cycles tab.

What it is for

A project used to move only when someone started its work. The steward places and ranks what you file, but it never decided what to do next. The cycle does, on its own clock, within limits you set:

• It looks every day, with every tab closed, and tells you once what it saw and did.
• It never goes further than the dial. At watch it only observes and judges; at steer it also files ideas and bugs, asks you questions and proposes an order; at build it also starts task sessions; at ship it also merges what the policy lets ship alone.
• It keeps to a budget: so many sessions and so many dollars a day. At the cap nothing more starts that day.
• It keeps a record: what it read, what it judged, what it proposed, and what cterm did with each proposal and why.

How to use it

1. Open the project's Settings tab, How far cterm goes. Set the dial: start at Watch to see what it would do without changing anything.
2. Under the dial, The cycle: when it runs (Only when asked, every day, weekdays, or every few hours from a time, in a time zone), the sessions and dollars it may spend a day, the policy (below) and The plan: whether a change to the plan it proposes waits for your yes or, at Ship, is applied without asking. Save.
3. The Cycles tab shows the dial, when the next cycle runs and the day's budget so far. Run now runs one at once (the project's owner or an admin); when the clock's time had already passed, that cycle counts for it and the next one moves on, so no second cycle follows.
4. Each cycle's digest comes to your devices as a notification; tapping it opens that cycle's record.

The policy

Three lists, one entry a line, and a few rules in your words:

• Ships alone: at ship, a finished session is merged by itself only when every file it changed is here.
• Asks first: waits for your yes. Anything the lists do not name asks too.
• Never by itself: the cycle never starts or merges it; a person does.

An entry is a path or a glob (docs/, *.md, src/billing/**) or title:<words>, matched in an item's title. The words in In your words go to the cycle as rules it reads (for example "a change a customer sees always asks").

From a terminal

• cterm cycle status <owner>/<project>: the dial, the cadence and the next run, the day's budget, the last records and the newest one in full.
• cterm cycle run <owner>/<project>: one cycle now.
• cterm cycle off <owner>/<project>: the dial at off. No cycle runs and nothing new starts by itself; a cycle running now finishes, and so do the sessions it started.

How it works

• One model call per cycle, on the project's owner's Claude login and the steward's model, in the project folder with read-only tools. It may read the code and the roadmap; it changes nothing itself. Its answer is a set of proposals: items to start, sessions to merge, questions, ideas and bugs to file, an order for what comes next.
• cterm checks every proposal before doing anything. An item is started only when it is ready (planned or next, a line to build still open, no needs, nothing open it waits for), the policy does not call it never, and the day's budget has a session and money left; the usual holds of a start by cterm apply too (two of its own at once, the usage window, shared files). A merge needs ship, a finished session nobody works in, and every changed file in Ships alone.
• Questions go to the project's queue, from "the cycle". Your answer is kept for the next cycle, which reads it in its prompt with every answer given since the last cycle started: approved, binned with your reason, or answered in your words (Answer…).
• The order it proposes goes to the steward, who applies it to the roadmap with its own rules (a pinned item stays, a waiting one waits).
• The plan itself is not the cycle's to change. It may only propose a change, at a longer cadence (below).
• The record keeps every proposal with what became of it: done, with what it made; held back, with why (the dial, the budget, the policy, a hold); or failed. The digest is the cycle's own two lines plus cterm's count.
• A cycle missed while the Mac slept runs once when it wakes, marked late. Two cycles of one project never run at once.

Changing the plan

The cycle moves within the plan: the order, the items it starts. Sometimes the plan itself should change: a goal dropped, an item that no longer serves any goal, a phase cut differently. For that the cycle writes a plan proposal, and only when one is due:

• once a month, counted from the last proposal (or, before the first, from the project's first cycle);
• at once when two goals are off (behind or missed in their last reading, or judged off by the cycle);
• after you answer a proposal with your words, so the next cycle can revise it as you said;
• never while a proposal waits for your answer.

The proposal is a short document: a title, why, the changes one per line, and the evidence (the goals' readings, what the last cycles saw). cterm saves it in the project folder under .cterm-proposals/, which version control ignores, and puts it in the project's queue, from "the cycle", with the file: open it from the entry and read it before you answer.

• Approve and the steward applies it to the roadmap through its script, the changes as the file says them then, so you may edit the file before approving. It leaves an item in progress and a pinned rank alone, leaves out what the script refuses with the reason, and writes one log entry, "Plan proposal q-N applied", naming each change made and each left out.
• Answer… with your words and the next cycle reads them and may write it again, revised.
• Bin it and nothing changes; the next proposal is due a month on.

With The plan set to Applied without asking at Ship and the dial at Ship, a due proposal goes straight to the steward, with no queue entry; the cycle's record says so. At any other position it waits for your yes.

Each cycle's record says whether a proposal was due and why, and the digest says when one waits for you.

Scenarios

Trying it safely

Set the dial at Watch and the cadence at Weekdays at 8:00. Each morning the digest says what the cycle sees and what it would do; the record lists every proposal as held back, "the dial is at watch". Nothing in the project changes. When its proposals look right, move the dial to Steer, then Build.

A budget of one session a day

At Build with Sessions a day at 1, the cycle starts the first ready item it proposes. Its other proposals are held back with "the day's budget of 1 session is used", and a second cycle the same day starts nothing.

Two goals off

Two goals read behind for weeks. The next cycle at Steer proposes to drop an item that moves neither and to lower a target, with the readings as evidence. The digest ends "a change to the plan for your yes"; the entry in the queue opens the document. You strike one line from the file and approve: the steward applies the other, and the roadmap's log names it.

Stopping it

cterm cycle off <owner>/<project>, or the dial at Off. The next cycle does not run and Run now says why.

Related

• The Situation and the dial on the project page.
• The steward, who applies the order the cycle proposes and the plan proposals you approve.
• Monitors, whose numbers a goal reads and the cycle sees.
• Task sessions, what the cycle starts.