Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,29 @@

All notable changes to SkipHow 2.x and later appear in this file. Earlier release notes remain available on [GitHub Releases](https://github.com/mzored/SkipHow/releases).

## 7.0.1 (2026-10-18)

### Inherited rules and tooling are the CTO's to judge

- Rules, tools, and records that earlier sessions made are the CTO's own earlier decisions, including a technical option the owner picked from a list an agent offered; product choices stay the owner's however they were made. Only what the owner's own words require stays the owner's. Simplify no longer treats a rule as the owner's when its history is unclear, and commits under the owner's account do not make a rule theirs. Simplify keeps the intent the owner stated, such as small modules, and revises the mechanism an agent chose for it, such as a line limit with a baseline to maintain.
- A rule that forces needless work counts as a defect, and the kernel's reuse rule now applies before an agent repairs its own tooling as well as before it writes new tooling.
- Simplify judges the project's own tooling, gates, and limits by their cost per run and in fixes against what they catch and what the test runner, CI provider, linter, or a maintained library offers. The agents and CI jobs that run them do not count as the callers that justify them. A test cut that relies on other coverage holds only after that other test has been read.

### Findings and loading survive the run

- When a lead accepts a delegate's return, it settles each finding: fixes it, folds it into planned work, records it with the reason it waits, or says why it is not a finding. Returns list findings apart from status. The kernel opens `tracked-work` for deferred findings, which says where the record goes and what it carries.
- Every workflow now loads the kernel by invoking the `skiphow` skill where the host has a skill tool, and otherwise by reading the file. A host that re-attaches invoked skills after compaction then keeps the kernel in context.

### Why

A trace of 22 root sessions and their delegates that ran 7.0.0 on three owner projects found loading much improved, but also four failures. Three sessions lost a kernel they had read as a file at compaction. Leads never mentioned again 41% of the items their delegates raised. Agents kept an agent-chosen line limit and an agent-built test selector as owner decisions. Test deletions that claimed other coverage left holes that only review caught. See [evidence](docs/evidence.md#current-package) and [decisions](docs/decisions.md).

### Checks and evidence

- This is a patch release. It restores behavior 7.0.0 promised: revising agent-made rules, keeping the system small, and accounting for every finding. Authority and protected-action boundaries are unchanged, and product decisions stay the owner's.
- An isolated read-only Codex review ran three rounds. Round 1 found that the owner-pick clause in the kernel and simplify did not limit options to technical ones, so an agent could have revised a product choice the owner made from an agent's list. Both now say technical, and the docs match. Round 2 found that the new fixture claimed every direct fix changes the file's length, but a same-length fix exists. The fixture now says only a length-changing fix trips the budget, and the required revision does not depend on it. Round 3 found nothing that qualified.
- No paid model sessions or clean-install runs were made. The new behavior remains `UNVERIFIED`.

## 7.0.0 (2026-10-17)

### The CTO keeps the system small
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
7.0.0
7.0.1
10 changes: 5 additions & 5 deletions docs/decisions.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Internal methods need no public routes or owner-operated stages. Correctness-cri

## Keeping the system small

Two real projects governed by earlier packages filled up with what the package was meant to prevent: more test code than product code, tests of their own deploy and CI scripts, custom test-selection tooling, shims with only in-repository callers, and review loops of up to six rounds. The old text made every addition a gain and every removal a risk. The kernel now says the opposite. Everything added stays and costs the owner, so the agent builds the least that delivers the outcome, writes a test only for a break a user or caller would notice, and removes what no longer pays with no more justification than adding it needed. For the owner that means fewer tests and tools, no compatibility shims, short reviews, and project rules that earlier sessions wrote being revised when they cost more than they protect. Guards for money, security, customer data, and the release path stay. The owner-invoked simplify workflow applies the same standard to a whole existing project. Whether agents follow it is `UNVERIFIED`; [evidence](evidence.md#current-package) records the trace behind the change.
Two real projects governed by earlier packages filled up with what the package was meant to prevent: more test code than product code, tests of their own deploy and CI scripts, custom test-selection tooling, shims with only in-repository callers, and review loops of up to six rounds. The old text made every addition a gain and every removal a risk. The kernel now says the opposite. Everything added stays and costs the owner, so the agent builds the least that delivers the outcome, writes a test only for a break a user or caller would notice, and removes what no longer pays with no more justification than adding it needed. For the owner that means fewer tests and tools, no compatibility shims, short reviews, and project rules, tools, and records that earlier sessions made being revised when they cost more than they protect, unless the owner's own words set them. Guards for money, security, customer data, and the release path stay. The owner-invoked simplify workflow applies the same standard to a whole existing project. Whether agents follow it is `UNVERIFIED`; [evidence](evidence.md#current-package) records the trace behind the change.

## Host boundary

Expand Down
18 changes: 18 additions & 0 deletions docs/evidence.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,24 @@ Current package behavior remains `UNVERIFIED` unless a qualifying receipt names

## Current package

7.0.1 follows a maintainer trace of 22 root sessions and their delegates that ran 7.0.0,
mostly the simplify workflow, on three owner projects on both hosts. Loading had improved:
every root loaded the kernel, its workflow, and several references, and every Claude
implementer received the engineering standard. Four failures remained. Three sessions
read the kernel as a file and lost it at compaction without reading it again, while three
that invoked the skill had it re-attached after every compaction. Leads never mentioned
again 51 of the 124 items their delegates raised, although none of the 43 items the leads
deferred themselves was lost. Agents kept an agent-chosen line limit with its baseline
ratchet and patched an agent-built test selector, treating both as owner decisions:
the owner had picked from an agent's menu, every commit carried the owner's account,
and simplify told agents to treat a rule as the owner's whenever history was unclear.
Test deletions justified by coverage elsewhere left real holes that only review caught.
7.0.1 makes workflows invoke the kernel skill where the host can, has leads settle each
returned finding when they accept a return, counts only the owner's own words as owner
rules, and makes needless work forced by a rule, and repairs to the project's own
tooling, the moment to judge them. The trace is field evidence, not a receipt, and the
new behavior is `UNVERIFIED`.

7.0.0 rewrites the package so the CTO keeps the owner's system small. A maintainer trace
of the same two owner projects, run under 4.3.0 through 6.3.5 across about 265 root
sessions and 1,900 delegates, found test and tooling code that grew several times faster
Expand Down
2 changes: 1 addition & 1 deletion docs/outcome-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ The lead establishes project context and acceptance conditions, researches conse

Technical supervision includes assessing material risks and accumulating costs across the authorized project, even when requested behavior and checks pass. Evidence directs attention beyond the touched files where it can reveal material problems; no request automatically needs an exhaustive audit. The lead questions the fit of existing solutions and chooses retention, simplification, replacement, or removal by complete accepted behavior and total cost. Under a change request, it fixes confirmed engineering findings within authority in this run at safe boundaries, including iteration, while prioritizing the owner's outcome. A finding is confirmed when it names a broken behavior, a security or data risk, a contradiction with the request, or a simpler design; a request for more tests, cases, or guards that names no break is not one. An issue preserves unfinished work and never substitutes for a feasible repair. Deferral needs a concrete owner decision, protected action, blocker, or evidenced cost that would materially compromise the owner's outcome; its record preserves the reason, next action, and resume condition. Investigation and improvements stop when further benefit does not justify their cost. Existing restrictions, delivery boundaries, and read-only requests remain binding.

The lead keeps the owner's system small. Everything added stays and costs the owner: code, tests, tooling, flags, compatibility paths, CI jobs, documents, project rules, and review rounds. The lead builds the least that delivers the outcome and removes what no longer pays for itself, with no more justification than adding it needed. A replacement moves every in-repository caller and deletes the old path. Failures are fixed at their cause, never hidden. Tests and tooling growing faster than the product, repeated fixes to the project's own tooling, and long review loops are defects the lead fixes. Project rules that earlier sessions wrote on their own judgment are the lead's own earlier decisions and are revised when they cost more than they protect; rules the owner asked for stay the owner's. Guards that protect money, security, customer data, and the release path stay. On request, the simplify workflow measures an existing project, removes what does not pay through reviewed changes, and reports what it saved.
The lead keeps the owner's system small. Everything added stays and costs the owner: code, tests, tooling, flags, compatibility paths, CI jobs, documents, project rules, and review rounds. The lead builds the least that delivers the outcome and removes what no longer pays for itself, with no more justification than adding it needed. A replacement moves every in-repository caller and deletes the old path. Failures are fixed at their cause, never hidden. Rules that force needless work, tests and tooling growing faster than the product, repeated fixes to the project's own tooling, and long review loops are defects the lead fixes. Rules, tools, and records that earlier sessions made, including a technical option the owner picked from an agent's own list, are the lead's own earlier decisions and are revised when they cost more than they protect; only what the owner's own words require stays the owner's. Guards that protect money, security, customer data, and the release path stay. On request, the simplify workflow measures an existing project, removes what does not pay through reviewed changes, and reports what it saved.

The owner resolves genuinely open choices about product behavior, scope, priority, cost, risk, audience, privacy, or rollout. Existing answers and applicable authorization survive later turns. The lead continues independent authorized work while an unresolved choice blocks dependent behavior.

Expand Down
15 changes: 15 additions & 0 deletions docs/prior-art.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,21 @@ An idea from another project becomes a focused method or a kernel invariant only

The reasoning behind each rule that survived is in [decision history](decisions.md), and what real runs have and have not shown is in [current evidence](evidence.md).

## Rules and tooling taken as given in 7.0.1

Read on 2026-10-18 at the revision in the link, because the owner asked whether agents had begun to work like Matt
Pocock's [retro](https://github.com/mattpocock/skills/blob/a7d038f6bf7f01b516408e95e2fb56e0b338fa6f/skills/engineering/retro/SKILL.md)
skill. They had not, and SkipHow had never taken it. The field question was narrower: agents kept agent-made rules and
tooling because nothing marked the moment they paid for them and simplify called unclear rules the owner's. Retro
shares the view that friction in a session is evidence about the environment, that an existing check left unwired or
broken is the finding rather than a reason to build another, and that steering text which changes nothing should go.
SkipHow already held those ideas in the kernel; 7.0.1 makes them apply when an agent repairs its own tooling or does
work only a rule demands. It does not take the user-invoked retrospective that presents candidates to the user, because
here those findings are the CTO's to act on and the owner-invoked simplify already covers a periodic pass. It does not
take "default to building the check over writing the rule" or a separate coding-standards file for reviewers, because
a custom check and a new standing file are additions that stay and cost the owner; the kernel sends code shape to the
linter or type checker the project already has.

## Keeping the system small in 7.0.0

Read on 2026-10-17 at the revisions in the links. The question was why two governed projects filled with tests,
Expand Down
5 changes: 4 additions & 1 deletion evals/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,10 @@ for the symptom. `review-unqualified-test-requests-declined` uses the `orders-se
note names dead code, two ask for tests and a guard without naming a break, and the candidate must remove the first
and decline the others with a reason. `agent-written-artifact-rule-revised` uses the `orders-service-agent-rules`
overlay and requires the candidate to revise a rule an agent session wrote that makes every fix add a test file and a
log entry, while the owner-requested rule beside it stays. Six earlier cases were rewritten where they required a
log entry, while the owner-requested rule beside it stays. The 7.0.1 case `agent-chosen-size-ratchet-revised` uses the
`orders-service-size-rule` overlay, whose instructions carry no labels: only the owner's quoted words show that the wish
for small modules is theirs, while the 20-line limit and the baseline that an ordinary fix can trip are not. The candidate
must revise that mechanism, keep the wish, and neither edit the baseline to comply nor ask the owner. Six earlier cases were rewritten where they required a
reviewer on every slice, an independent review of a one-supplier wording change, or retained regression checks, and
`delegation-brief-and-returned-problem` now requires the brief to carry the Engineering standard. No arm without the
candidate package is required to produce these events.
Expand Down
Loading
Loading