ETHOS 9, Earn Its Place: factory, /write-skill and /autoplan carry it

Garry, 2026-11-02: "Also work this principle of only include it if it is
beneficial and good into gstack". ETHOS.md principle 9 states the rule, the
fair test (claude_code preset, frontier models per R54, masked no-gstack
arm), the R48 Why-null cycle, the safety exception, and measure biggest
first, linking docs/inventory.md. factory.md item 8 cites it, trimmed
elsewhere to 3,298 of 3,300 bytes with no rule dropped. /write-skill's edit
ladder step 2 is the evidence rule and section 4 adds the Evidence: commit
line. /autoplan's CEO phase lists each part a plan adds to gstack with its
evidence or owned, dated plan; two redundant lines went to keep autoplan
under its size pins (pins lowered by 17). CONTRIBUTING.md "Adding a new
skill" and docs/skills.md point at the ledger.

Skill-Size: 3273→3666 bytes (write-skill/SKILL.md.tmpl)
Skill-Size: 12738→12721 bytes (autoplan/sections/ceo-phase.md)
Evidence: plan none (owner ruling R56, GST-914); write-skill and autoplan rows stay grandfathered untested
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
garrytanandcapy-ai[bot] committed 2026-11-02 05:03:47 +00:00
1 parent 37f515bae0
commit 85e3edad83
10 files changed
+91 -32

No files matched your search

+1
View File
@@ -811,6 +811,7 @@ Write or change skill prose with `/write-skill` (edit ladder, levels, `gstack-sk
3. The dynamic template discovery picks it up for every host render and for `gstack/llms.txt`. Two things it does not fill in: a row in `SKILL_REQUIREMENTS` in `lib/doctor-components.ts` (the doctor's `--for <skill>` table; `test/doctor-components.test.ts` fails on a skill directory without one, and the same gen run rerenders `bin/gstack-doctor-components.sh`), and the catalog rows readers find the skill through (README.md, AGENTS.md, `docs/skills.md`, `docs/PROJECT_STRUCTURE.md`, the root `SKILL.md.tmpl` router)
4. Budget it: run `bun test/helpers/capture-context-budget.ts` and commit the refreshed `test/fixtures/context-budget.json` — the context-budget ratchet fails any skill without a ceiling; the catalog budget (`test/catalog-budget.test.ts`) fails until its cap is ratcheted by the protocol in its failure message, and the number is quoted in CLAUDE.md, this file and `docs/CONTRIBUTOR_REFERENCE.md`
5. Commit `{skill}/SKILL.md` (and the generated `{skill}/sections/preamble.md` when the template's `preamble-tier` is 2 or higher), external host output is generated at setup time and gitignored
6. Give it a row in the evidence ledger, `docs/inventory/evidence.json` ([ETHOS.md: 9. Earn Its Place](ETHOS.md#9-earn-its-place)): evidence that it helps on frontier models (`sources`, `models`, `prompt: preset`, `scope`, `masked: true`), or `status: untested` with its `reason`, a concrete `plan` (a `test/fixtures/skill-evals/<skill>/tasks.json` or an /eval-plan preregistration), an `owner` and a `measure_by` date. `test/inventory.test.ts` fails on a skill without a valid row; `bin/gstack-inventory --check` names the problem, and `bin/gstack-inventory` refreshes the dated snapshot in `docs/inventory.md`
## Conductor workspaces
+37
View File
@@ -273,6 +273,42 @@ the eval that jumps twenty points usually found a shortcut, not a capability.
---
## 9. Earn Its Place
Garry, 2026-11-02:
"Also work this principle of only include it if it is beneficial and good into gstack".
Every skill, step, instruction, check and default costs tokens and attention
on every run that loads it. So each one earns its place. A new part comes with
evidence that it helps on frontier models, or with a stated reason, an owner
and a date by which a fair test will measure it.
A fair test runs Claude Code's own system prompt (the `claude_code` preset,
not the Agent SDK's stub), on frontier models (today Opus 5.5 and GPT-6.1 Sol,
plus at most one named low-cost model), against a no-gstack arm that is masked
so it cannot read gstack. A result from the stub, from Haiku or Sonnet alone,
or from an unmasked arm is a lead, not a verdict.
When a fair test shows an existing part doesn't help, it gets one "Why null?"
cycle: did the model use the part, did the task fit, was there enough power and
room below the ceiling, and does today's model do the job without it. Then
keep it, fix the method, or cut it, and say which plainly.
Safety and security guards (careful, freeze, guard, unfreeze, cso) stay on
their stated reason: they stop the rare bad run that an average score can't see.
Measure the biggest parts first, the ones that load the most on the most runs.
[docs/inventory.md](docs/inventory.md) ranks every part by load and shows its
evidence; `docs/inventory/evidence.json` is the ledger, and
`bin/gstack-inventory --check` validates it.
**Anti-patterns:**
- A new step because it sounds wise, with no test planned.
- Keeping a part because it looked good on the stub or a small model.
- Cutting a part after one null result, without the Why-null cycle.
---
## How They Work Together
Boil the Ocean says: **cover the whole requirement with the least code.**
@@ -282,6 +318,7 @@ Attack the Premise says: **when fixes keep failing, test the belief they share.*
Separate Before Serializing says: **remove the race before you referee it.**
Make Operations Idempotent says: **design for the run that happens twice.**
Explain the Number says: **a result you cannot explain is not yet a result.**
Earn Its Place says: **every part shows it helps, or has a dated plan to.**
Together: search first, then build the complete version of the right thing.
The worst outcome is building a complete version of something that already
+3 -3
View File
@@ -11,11 +11,12 @@ announcement. Dispatching a reviewer never completes its step.
- Premises: accept reasonable ones (P6). Queue clearly-wrong/challenged premises
as User Challenges for Phase 4: assumption, reason and cost of proceeding.
The user decides there; never stop mid-pipeline.
- List each part the plan adds to gstack (skill, step, instruction, check, default) with its
evidence or owned, dated test plan; a missing one is a finding.
- Alternatives: pick highest completeness (P1). If tied, pick simplest (P5).
If top 2 are close → mark TASTE DECISION.
- Scope expansion: in blast radius + <1d CC → approve (P2). Outside → defer to TODOS.md (P3).
Duplicates → reject (P4). Borderline (3-5 files) → mark TASTE DECISION.
- All 11 review sections: run fully, auto-decide each issue, log every decision.
**Required execution checklist (CEO):**
@@ -38,8 +39,7 @@ Before every spec dispatch, including after each accepted spec fix, run:
```bash
bun "<SNAPSHOT_TOOL>" amend-input ceo "<ACTIVE_PLAN>" "<CEO_STEP0_CHECKPOINT>" "<RESTORE_PATH>" "<methodologyPath>"
```
This applies the recorded requirements and exports the complete current
`Implementation plan`. Keep returned `checkpointPath` as the amendment baseline;
Keep returned `checkpointPath` as the amendment baseline;
use returned `reviewInputPath` as `<CEO_SPEC_INPUT>`. Read that file at every
returned `readRanges` offset/limit through EOF, then read the CEO scope summary in full.
Reconcile dispositions, scope counts, proposal IDs and actual heading/test references
+3 -3
View File
@@ -9,11 +9,12 @@ announcement. Dispatching a reviewer never completes its step.
- Premises: accept reasonable ones (P6). Queue clearly-wrong/challenged premises
as User Challenges for Phase 4: assumption, reason and cost of proceeding.
The user decides there; never stop mid-pipeline.
- List each part the plan adds to gstack (skill, step, instruction, check, default) with its
evidence or owned, dated test plan; a missing one is a finding.
- Alternatives: pick highest completeness (P1). If tied, pick simplest (P5).
If top 2 are close → mark TASTE DECISION.
- Scope expansion: in blast radius + <1d CC → approve (P2). Outside → defer to TODOS.md (P3).
Duplicates → reject (P4). Borderline (3-5 files) → mark TASTE DECISION.
- All 11 review sections: run fully, auto-decide each issue, log every decision.
**Required execution checklist (CEO):**
@@ -36,8 +37,7 @@ Before every spec dispatch, including after each accepted spec fix, run:
```bash
bun "<SNAPSHOT_TOOL>" amend-input ceo "<ACTIVE_PLAN>" "<CEO_STEP0_CHECKPOINT>" "<RESTORE_PATH>" "<methodologyPath>"
```
This applies the recorded requirements and exports the complete current
`Implementation plan`. Keep returned `checkpointPath` as the amendment baseline;
Keep returned `checkpointPath` as the amendment baseline;
use returned `reviewInputPath` as `<CEO_SPEC_INPUT>`. Read that file at every
returned `readRanges` offset/limit through EOF, then read the CEO scope summary in full.
Reconcile dispositions, scope counts, proposal IDs and actual heading/test references
+7 -7
View File
@@ -1,17 +1,17 @@
# How we work: the gstack software factory on Capy
# How we work: gstack's factory on Capy
What seven Captain crews converged on (2026-10-29). Your crew's CREW.md and recorded approvals decide who may merge, update a base, spend or touch production; urgency changes priority, never permissions or gates. With no Captain, ask the person and never merge without their word. Story: capy/README.md; examples: your org Drive's software-factory/README.md, if any.
What seven Captain crews agreed on. Your crew's CREW.md and recorded approvals decide who may merge, update a base, spend or touch production; urgency changes priority, never permissions or gates. With no Captain, ask the person; never merge without their word. Story: capy/README.md; examples: org Drive software-factory/README.md.
1. **Plan, then a yes.** New functionality starts with /autoplan sized to the work; the build waits for "do it". [SKILL.md: Plan, approve, ship]
2. **Someone else merges.** Run /ship to a receipt on your final pushed head, send one READY quoting gstack's verify output verbatim, and stop. The merge owner merges on green and assigns versions. [docs/captain.md: The READY contract]
3. **Block only on the floor.** A finding blocks if it would fail a test, break production, or lose data or secrets; the rest goes in the PR body or next wave. [docs/review-policy.md]
4. **Fix waves.** When main goes red, hold /ship while one owner finds the root cause; bring main in once, as your rules allow. Fold deferred findings and test follow-ups into one PR. [docs/triage.md]
5. **Severe first, same gates.** A severe user-facing bug jumps the queue; the plan can be short; receipt, checks and merge owner stay.
6. **Trade findings, not small talk.** Another crew's finding goes to its Captain, through yours, with the evidence.
5. **Severe first, same gates.** A severe user-facing bug jumps the queue with a short plan; receipt, checks and merge owner stay.
6. **Trade findings, not small talk.** Another crew's finding goes to its Captain, through yours, with evidence.
7. **Measure before you act.** Run the real system on the merged tree you ship; a real run outranks a reviewed plan. Each number names its run, commit or uncapped query; say what you did not verify.
8. **Evals decide, and losses get reported.** Preregister bars, cap and stop rule before paying [/eval-plan]. Cheap proof (a keyless fake, a smoke) before the paid run. Use controls (no-skill and placebo arms, clean decoys). Report use and pass apart; quote spend from the meter.
9. **Flakes: one rerun, a ledger, a daily fix.** Only the rerun the policy allows, never a harness or infra red; a second red is real; no test is loosened. [docs/captain.md: The daily flaky pass]
8. **Evals decide, and losses get reported.** Preregister bars, cap and stop rule before paying [/eval-plan]. Cheap proof (a keyless fake, a smoke) first. Controls: no-skill and placebo arms, clean decoys. Report use and pass apart; quote spend from the meter. A new part needs proof it helps or a dated test plan [ETHOS.md: 9. Earn Its Place].
9. **Flakes: one rerun, a ledger, a daily fix.** Only the policy's rerun, never for a harness or infra red; a second red is real; never loosen a test. [docs/captain.md: The daily flaky pass]
10. **Quiet.** Message on a decision, a blocker, a READY or a finished phase. A broadcast needing no reply goes in the Captain's notes; never reply just to acknowledge.
11. **Ask once, plainly.** One ask per decision, explained like the owner is five: your Captain's name, then a lettered line each: "A: <code> hit problem p, which happens when h. We could do 1) x, 2) y or 3) z. Recommendation x because why. A1 to take recommendation." "do it" takes every recommendation; "A2" takes option 2. Owner tasks: the exact link (in Capy: path and field), numbered simple steps, the reply word. Never re-ask a standing rule; check what you can yourself. [docs/captain.md: The ask format]
11. **Ask once, plainly.** One ask per decision, explained like the owner is five: your Captain's name, then a lettered line each: "A: <code> hit problem p, which happens when h. We could do 1) x, 2) y or 3) z. Recommendation x because why. A1 to take recommendation." "do it" takes every recommendation; "A2" takes option 2. Owner tasks: the exact link (in Capy: path and field), numbered steps, the reply word. Never re-ask a standing rule; check what you can yourself. [docs/captain.md: The ask format]
12. **Fresh threads, closed out.** One thread per unit of work (crew threads ask their Captain); past the context limit, hand off. Its Captain archives only its crew's threads; threads outside every crew are the owner's, even its automation's. Size reviews to the diff; read the token counter. [docs/ship-budget.md]
13. **The owner's model preference.** `gstack-models resolve --role agent` picks agent models, except cross-family voices and eval subjects. [docs/model-policy.md: Your model preference]
+5 -1
View File
@@ -908,8 +908,12 @@ gstack's own templates and for any skill folder you own.
add nothing a fresh session already does; edit the line that covers the idea instead of appending; put the fact on the
lowest level that reaches the agent in time (description, SKILL.md, `references/`, the tool's `--help`, the tool's
errors); write the rule and put the story in the commit message.
- **Evidence.** A new skill, step, instruction, check or default needs evidence that it helps on frontier models, or a
dated plan to measure it ([ETHOS.md: 9. Earn Its Place](../ETHOS.md#9-earn-its-place)). Commits carry an `Evidence:`
line, and every gstack skill has a row in the evidence ledger, `docs/inventory/evidence.json`, which
[docs/inventory.md](inventory.md) ranks by load per run.
- **Size.** `gstack-skill-bill` prints bytes and estimated tokens per level, and in a gstack checkout the skill's eval
task file (`EVAL TASKS:`). Commits carry
task file (`EVAL TASKS:`) and its ledger row (`EVIDENCE:`). Commits carry
`Skill-Size: <before>→<after> bytes`; a skill more than 10% over its last `Skill-Diet:` commit is DUE, and a red
context-budget ratchet means diet, not a higher ceiling.
- **Drift.** `test/skill-bin-drift.test.ts` fails when a template or rendered skill calls a gstack bin or flag that
+9
View File
@@ -594,6 +594,15 @@ describe('capy skill: factory.md, the auto-loaded "how we work" page', () => {
expect(citationProblems(text)).toEqual([]);
});
test('item 8 cites ETHOS.md principle 9, Earn Its Place, which states the fair test, the Why-null cycle and the safety exception', () => {
const item8 = fs.readFileSync(FACTORY, 'utf8').split('\n').find(l => l.startsWith('8. '))!;
expect(item8).toContain('[ETHOS.md: 9. Earn Its Place]');
const ethos = fs.readFileSync(path.join(REPO, 'ETHOS.md'), 'utf8');
const p9 = ethos.slice(ethos.indexOf('## 9. Earn Its Place'), ethos.indexOf('## How They Work Together'));
expect(p9.length).toBeGreaterThan(200);
for (const words of ['only include it if it is beneficial and good', 'claude_code', 'Opus 5.5', 'GPT-6.1 Sol', 'masked', 'Why null?', 'Safety and security guards', 'biggest', 'docs/inventory.md']) expect(p9).toContain(words);
});
test('negative controls: a missing file, a missing heading and an unknown skill are each caught', () => {
expect(citationProblems('[docs/no-such-page.md: Anything]')).toEqual(['missing file docs/no-such-page.md']);
expect(citationProblems('[docs/captain.md: No Such Heading]')).toEqual(['missing heading docs/captain.md: No Such Heading']);
+12 -12
View File
@@ -2,53 +2,53 @@
"_comment": "Generated SKILL.md files over the limit, pinned at their exact character count (#3199). test/skill-md-size-guard.test.ts fails when a pinned skill grows past its pin or shrinks below it: lower the pin when a skill shrinks and delete it once the skill is within the limit. Raising a pin is an owner decision. The shared-preamble hoist (GSTA-96) moved every tier 2+ skill's shared preamble into sections/preamble.md; the pins below are what remains.",
"limit": 100000,
"pins": {
"agy/gstack-autoplan": 109666,
"agy/gstack-autoplan": 109649,
"agy/gstack-plan-design-review": 109116,
"agy/gstack-plan-devex-review": 114957,
"agy/gstack-plan-eng-review": 143590,
"agy/gstack-review": 104276,
"codex/gstack-autoplan": 108409,
"codex/gstack-autoplan": 108392,
"codex/gstack-plan-design-review": 110473,
"codex/gstack-plan-devex-review": 116465,
"codex/gstack-plan-eng-review": 144755,
"codex/gstack-review": 103799,
"copilot/gstack-autoplan": 109109,
"copilot/gstack-autoplan": 109092,
"copilot/gstack-plan-design-review": 109382,
"copilot/gstack-plan-devex-review": 114419,
"copilot/gstack-plan-eng-review": 143755,
"copilot/gstack-review": 103857,
"cursor/gstack-autoplan": 108341,
"cursor/gstack-autoplan": 108324,
"cursor/gstack-plan-design-review": 107924,
"cursor/gstack-plan-devex-review": 113689,
"cursor/gstack-plan-eng-review": 142345,
"cursor/gstack-review": 122147,
"factory/gstack-autoplan": 110619,
"factory/gstack-autoplan": 110602,
"factory/gstack-plan-design-review": 111022,
"factory/gstack-plan-devex-review": 117052,
"factory/gstack-plan-eng-review": 145453,
"factory/gstack-review": 125920,
"gbrain/gstack-autoplan": 108748,
"gbrain/gstack-autoplan": 108731,
"gbrain/gstack-plan-eng-review": 124972,
"gemini/gstack-autoplan": 108899,
"gemini/gstack-autoplan": 108882,
"gemini/gstack-plan-design-review": 109210,
"gemini/gstack-plan-devex-review": 114247,
"gemini/gstack-plan-eng-review": 143588,
"gemini/gstack-review": 103679,
"hermes/gstack-autoplan": 108751,
"hermes/gstack-autoplan": 108734,
"hermes/gstack-plan-eng-review": 125008,
"kiro/gstack-autoplan": 108115,
"kiro/gstack-autoplan": 108098,
"kiro/gstack-plan-design-review": 107770,
"kiro/gstack-plan-devex-review": 113541,
"kiro/gstack-plan-eng-review": 142207,
"kiro/gstack-review": 121971,
"openclaw/gstack-autoplan": 108571,
"openclaw/gstack-autoplan": 108554,
"openclaw/gstack-plan-eng-review": 123487,
"opencode/gstack-autoplan": 109090,
"opencode/gstack-autoplan": 109073,
"opencode/gstack-plan-design-review": 109238,
"opencode/gstack-plan-devex-review": 114297,
"opencode/gstack-plan-eng-review": 143614,
"opencode/gstack-review": 122769,
"slate/gstack-autoplan": 108228,
"slate/gstack-autoplan": 108211,
"slate/gstack-plan-design-review": 107847,
"slate/gstack-plan-devex-review": 113615,
"slate/gstack-plan-eng-review": 142276,
+7 -3
View File
@@ -102,8 +102,8 @@ telemetry — it never blocks the workflow.
## 1. Find the skill
Run `~/.claude/skills/gstack/bin/gstack-skill-bill <name|folder>`. It resolves exact names only and prints the
skill's kind and its size per level. A new skill: make the folder first (in a gstack checkout, follow CONTRIBUTING.md
Run `~/.claude/skills/gstack/bin/gstack-skill-bill <name|folder>`. It prints the skill's kind,
its size per level and its `EVIDENCE:` row. A new skill: make the folder first (in a gstack checkout, follow CONTRIBUTING.md
"Adding a new skill"), then write every line by sections 2 and 3.
- `user`: edit it in place.
- `gstack-install`: never edit; gstack-upgrade overwrites it. Edit `<skill>/SKILL.md.tmpl` in a gstack checkout, or
@@ -126,7 +126,9 @@ Put each fact on the lowest level that still reaches the agent before it needs i
Stop at the first step that handles the change.
1. **Fix it below the skill.** A clearer error, a flag, a check or a test in the tool. Prose is for judgment calls.
2. **Check the model needs it.** If a fresh session does the right thing without the line, add nothing.
2. **Earn its place.** Add a skill, step, instruction, check or default only with evidence it helps frontier models
or a dated plan to measure it (skill-evals `tasks.json` or an /eval-plan prereg). If a fresh session does it right
without the line, add nothing.
3. **Edit, don't append.** Change the line that already covers the idea; each meaning lives in one place.
4. **Pick its level** (section 2).
5. **Rule, not story.** One positive rule under a short name; the incident goes in the commit message.
@@ -138,6 +140,8 @@ When code changes a name or flag a skill teaches, update the skill in the same c
- Run `~/.claude/skills/gstack/bin/gstack-skill-bill` before and after, and put `Skill-Size: <before>→<after> bytes (<file>)` in the commit
message. DUE means it grew over 10% since its last `Skill-Diet:` commit: diet it instead of adding.
- Add `Evidence: <run id, results file or commit>`, `Evidence: plan <tasks.json or prereg> measure_by <date>` or
`Evidence: safety: <reason>`. A new gstack skill adds its `docs/inventory/evidence.json` row (`gstack-inventory --check`).
- In a gstack checkout: `bun test test/skill-bin-drift.test.ts test/parity-suite.test.ts` and the budgets in
CONTRIBUTING.md. A red context-budget ratchet means diet, not a higher ceiling.
- Rerun the case that prompted the change in a fresh session.
+7 -3
View File
@@ -29,8 +29,8 @@ allowed-tools:
## 1. Find the skill
Run `~/.claude/skills/gstack/bin/gstack-skill-bill <name|folder>`. It resolves exact names only and prints the
skill's kind and its size per level. A new skill: make the folder first (in a gstack checkout, follow CONTRIBUTING.md
Run `~/.claude/skills/gstack/bin/gstack-skill-bill <name|folder>`. It prints the skill's kind,
its size per level and its `EVIDENCE:` row. A new skill: make the folder first (in a gstack checkout, follow CONTRIBUTING.md
"Adding a new skill"), then write every line by sections 2 and 3.
- `user`: edit it in place.
- `gstack-install`: never edit; gstack-upgrade overwrites it. Edit `<skill>/SKILL.md.tmpl` in a gstack checkout, or
@@ -53,7 +53,9 @@ Put each fact on the lowest level that still reaches the agent before it needs i
Stop at the first step that handles the change.
1. **Fix it below the skill.** A clearer error, a flag, a check or a test in the tool. Prose is for judgment calls.
2. **Check the model needs it.** If a fresh session does the right thing without the line, add nothing.
2. **Earn its place.** Add a skill, step, instruction, check or default only with evidence it helps frontier models
or a dated plan to measure it (skill-evals `tasks.json` or an /eval-plan prereg). If a fresh session does it right
without the line, add nothing.
3. **Edit, don't append.** Change the line that already covers the idea; each meaning lives in one place.
4. **Pick its level** (section 2).
5. **Rule, not story.** One positive rule under a short name; the incident goes in the commit message.
@@ -65,6 +67,8 @@ When code changes a name or flag a skill teaches, update the skill in the same c
- Run `~/.claude/skills/gstack/bin/gstack-skill-bill` before and after, and put `Skill-Size: <before>→<after> bytes (<file>)` in the commit
message. DUE means it grew over 10% since its last `Skill-Diet:` commit: diet it instead of adding.
- Add `Evidence: <run id, results file or commit>`, `Evidence: plan <tasks.json or prereg> measure_by <date>` or
`Evidence: safety: <reason>`. A new gstack skill adds its `docs/inventory/evidence.json` row (`gstack-inventory --check`).
- In a gstack checkout: `bun test test/skill-bin-drift.test.ts test/parity-suite.test.ts` and the budgets in
CONTRIBUTING.md. A red context-budget ratchet means diet, not a higher ceiling.
- Rerun the case that prompted the change in a fresh session.