Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.
JavaScript agentic-codingai-agentsai-governanceautonomous-agentsclaude-codeclicode-reviewcodexcoding-agentsdeveloper-toolsgit-hooksllmlocal-firstmulti-agentsoftware-factoryspec-driven-developmentverificationvibe-coding
docs(rigor): guides say how a person uses Rigor and Sentinels [I1]
Corey Olsondd6e815fd444
diff --git a/docs/rigor.md b/docs/rigor.mdnew file mode 100644index 00000000..560fca0e--- /dev/null+++ b/docs/rigor.md@@ -0,0 +1,58 @@+# Rigor++Rigor turns a repeated mistake into a rule the board keeps. It watches the failures the board already records. When the same cause shows up again, Rigor lists it, and the coordinator can draft a rule that checks for it. The person decides whether the rule becomes part of the project.++## What counts as a repeat++A cause repeats when it shows up on two items. It also repeats when one item fails twice at two different commits. A cause can also become a repeat at once when the person marks it never again.++Merge conflicts never count as a repeat. Two branches that touch the same lines collide, and no rule can prevent that.++## How a cause is named++Every cause has a key. The key comes from the structured fields of a failure, never from the free-text note, so the same mistake gets the same key each time. There are five kinds:++- `test:<file>::<title>` for a failing test+- `refusal:<CODE>` for a refusal the board gave+- `row:<id>` for a spec row+- `doctrine:<id>` for a doctrine row+- `sentinel:<name>` for a watch that went red++Name the cause when you send work back, so Rigor can read it. For example:++ pullboard verify <id> reject --reason TEST_FAILURE --note "what failed" --cause <key>+ pullboard reopen <id> --note "why" --cause <key>++A reject or reopen without a cause still counts as a failure. Rigor just cannot read it, and the report says how many there are.++## How you use it++Start by looking at what has repeated:++ pullboard rigor++Each line shows the cause, whether it reads as work, product or both, how often it failed, and which items it touched. A line that says "never again (the person)" is one the person has already decided on.++When a cause repeats, the board posts a notice to the coordinator with the next command. The coordinator then drafts the rule and proves it. The command takes a rule, a check, and two commits: one where the check fails, and one where it passes:++ pullboard rigor draft <key> "<rule>" --check "<command>" --red <commit> --green <commit> [--section <letter>]++Rigor runs the check at both commits. If the check does not fail at the red commit and pass at the green one, the draft is refused. A cause that reads as work becomes a doctrine row whose check must count zero. A cause that reads as product becomes a spec row gated by its failing test. A cause that reads as both produces one of each, and the person picks which to keep.++A `test:` cause needs a literal `node --test <file>` check, and the named test must fail at the red commit and pass at the green one.++Drafting approves nothing. The person reviews each draft with its evidence and its proof. They approve or decline it in the Needs you list in `pullboard view`, or with:++ pullboard spec approve <ids> | decline <ids> --reason "why"++Once a doctrine row is approved, every submit runs the doctrine check, so the rule holds from then on. Check the current rules and their counts with:++ pullboard doctrine check++## Marking a cause never again++Sometimes the person knows a mistake must never happen again, and does not want to wait for a second failure. The person records the cause as a fact and marks it never again:++ pullboard fact <id> root-cause "<why>" --cause <key> --never-again --as person++Only the person can do this, from the main checkout, through the terminal or the view. The cause lists in `pullboard rigor` at once, and the coordinator is asked to draft it.diff --git a/docs/sentinels.md b/docs/sentinels.mdnew file mode 100644index 00000000..2dc70a02--- /dev/null+++ b/docs/sentinels.md@@ -0,0 +1,59 @@+# Sentinels++A sentinel is a check that runs on a schedule and tells someone when it goes red. The board has two kinds. The health watch is built in and looks for stuck work. A board watch is a check your project defines, and the person approves it before it ever runs.++## How you use it++There are two watches to know about. Read the health watch first, since it needs no setup.++### The health watch++The health watch needs no setup. It looks at every item and reports the ones that are stuck: waiting too long on a claim, a review, a hold or a release. To see the current list, run:++ pullboard health++Each line gives the item, why it is stuck, since when, the next step and who takes it. The command exits with status 1 when anything is stuck, so a script can check for it.++The watch runs by itself. `pullboard resume` checks the board, and the view checks again every ten minutes while it is open.++When a finding appears or clears, the sentinel sends a shout. The coordinator always gets it. The owner gets it too when the owner is a person, a seat or a lane. You read these shouts in your inbox:++ pullboard inbox++The thresholds live in `pullboard.json`. `health.stuck` sets how long an item can sit before it counts, with a default of one hour. `health.holds` and `health.release` do the same for held lanes and release waits, with a default of one day each.++To turn the health watch off, set `health.sentinel` to `false` in `pullboard.json`, or in your machine settings.++### A board watch++A board watch runs a command you choose, such as a test suite, on a schedule. Anyone on the board can propose one, and only the person can approve it. An agent proposes a watch like this:++ pullboard sentinel propose nightly-build --check "true" --every hourly --owner coordinator++The schedule is `10m`, `hourly` or `daily`. The owner is the coordinator, a registered seat, or a lane. You can also set the working directory with `--directory <path>`, the time limit with `--timeout <milliseconds>`, and the next step a reader should take with `--next "<step>"`.++The person then approves the exact command, directory and schedule:++ pullboard sentinel approve nightly-build++Or the person declines it, with a reason:++ pullboard sentinel decline nightly-build --reason "<why>"++Approval binds to the exact row. If anyone changes the command, the directory, the schedule or the owner, the watch goes back to pending and must be approved again.++To see every watch, its approval, its owner and its last result, run:++ pullboard sentinels++This command reads the board and runs nothing.++### What happens when a board watch runs++Approved watches run during `pullboard resume`, once their schedule is due. A watch never runs twice at the same time.++The owner hears about a watch only when its result changes. A red result sends "Sentinel failed" with the output and the next step. The next green result sends "Cleared". Every red run is kept in the history, so nothing is lost between the two messages.++### How Rigor uses a sentinel++Each red run counts as a failure with the cause `sentinel:<name>`. Two red runs of the same watch make a repeated cause, and Rigor lists it in `pullboard rigor`. From there it follows the same path as any other repeated cause, so the coordinator can draft a rule and the person decides on it. See [Rigor](rigor.md) for how that works.