diff --git a/.claude/skills/arch-init/SKILL.md b/.claude/skills/arch-init/SKILL.md index e032a0f5f..b69b0b751 100644 --- a/.claude/skills/arch-init/SKILL.md +++ b/.claude/skills/arch-init/SKILL.md @@ -77,11 +77,23 @@ plus the most recent dated section*, so a save must leave exactly that behind: 1. **Rewrite the current-state / open-loops section in place** — overwrite it with where things actually stand now (current focus + open loops + how to - resume). Do not accumulate stale "current state" blocks. + resume). Do not accumulate stale "current state" blocks, and never leave two + sections with the same heading (a duplicated "How to resume" or "Open loops" + means you appended where you should have overwritten). **Delete resolved + loops entirely** — a closed item's record is the log entry, not a lingering + line in current state. 2. **Append one short dated log entry** capturing what changed this stretch. -3. **Keep it to one screen (compaction discipline).** The state file is a - summary, not a transcript. When you append, prune stale dated sections so - the file stays readable at a glance. +3. **Compact — this is part of the save, not optional polish.** Every save + both adds AND removes: after writing, keep the recent dated log entries in + full and collapse older ones into a single one-line summary that names + where the detail lives (the closed PRs, issues, and reviews it covered). + Remember these state files are gitignored — there is no git history to + fall back on, so pruned prose is gone for good. Prune by replacing detail + with pointers to durable artifacts, never by deleting the only record of + something. The file is a summary a fresh session reads at a glance — + one screen is the right order of magnitude, judged by you. If a save has + grown it past easy readability, prune as part of that save rather than + leaving it for next time. **Content guardrails.** No secrets (tokens, keys, credentials). No transcript dumps or raw tool output. Include only: current focus, open loops, and the diff --git a/.codex/skills/arch-init/SKILL.md b/.codex/skills/arch-init/SKILL.md index e032a0f5f..b69b0b751 100644 --- a/.codex/skills/arch-init/SKILL.md +++ b/.codex/skills/arch-init/SKILL.md @@ -77,11 +77,23 @@ plus the most recent dated section*, so a save must leave exactly that behind: 1. **Rewrite the current-state / open-loops section in place** — overwrite it with where things actually stand now (current focus + open loops + how to - resume). Do not accumulate stale "current state" blocks. + resume). Do not accumulate stale "current state" blocks, and never leave two + sections with the same heading (a duplicated "How to resume" or "Open loops" + means you appended where you should have overwritten). **Delete resolved + loops entirely** — a closed item's record is the log entry, not a lingering + line in current state. 2. **Append one short dated log entry** capturing what changed this stretch. -3. **Keep it to one screen (compaction discipline).** The state file is a - summary, not a transcript. When you append, prune stale dated sections so - the file stays readable at a glance. +3. **Compact — this is part of the save, not optional polish.** Every save + both adds AND removes: after writing, keep the recent dated log entries in + full and collapse older ones into a single one-line summary that names + where the detail lives (the closed PRs, issues, and reviews it covered). + Remember these state files are gitignored — there is no git history to + fall back on, so pruned prose is gone for good. Prune by replacing detail + with pointers to durable artifacts, never by deleting the only record of + something. The file is a summary a fresh session reads at a glance — + one screen is the right order of magnitude, judged by you. If a save has + grown it past easy readability, prune as part of that save rather than + leaving it for next time. **Content guardrails.** No secrets (tokens, keys, credentials). No transcript dumps or raw tool output. Include only: current focus, open loops, and the diff --git a/codev-skeleton/.claude/skills/arch-init/SKILL.md b/codev-skeleton/.claude/skills/arch-init/SKILL.md index e032a0f5f..b69b0b751 100644 --- a/codev-skeleton/.claude/skills/arch-init/SKILL.md +++ b/codev-skeleton/.claude/skills/arch-init/SKILL.md @@ -77,11 +77,23 @@ plus the most recent dated section*, so a save must leave exactly that behind: 1. **Rewrite the current-state / open-loops section in place** — overwrite it with where things actually stand now (current focus + open loops + how to - resume). Do not accumulate stale "current state" blocks. + resume). Do not accumulate stale "current state" blocks, and never leave two + sections with the same heading (a duplicated "How to resume" or "Open loops" + means you appended where you should have overwritten). **Delete resolved + loops entirely** — a closed item's record is the log entry, not a lingering + line in current state. 2. **Append one short dated log entry** capturing what changed this stretch. -3. **Keep it to one screen (compaction discipline).** The state file is a - summary, not a transcript. When you append, prune stale dated sections so - the file stays readable at a glance. +3. **Compact — this is part of the save, not optional polish.** Every save + both adds AND removes: after writing, keep the recent dated log entries in + full and collapse older ones into a single one-line summary that names + where the detail lives (the closed PRs, issues, and reviews it covered). + Remember these state files are gitignored — there is no git history to + fall back on, so pruned prose is gone for good. Prune by replacing detail + with pointers to durable artifacts, never by deleting the only record of + something. The file is a summary a fresh session reads at a glance — + one screen is the right order of magnitude, judged by you. If a save has + grown it past easy readability, prune as part of that save rather than + leaving it for next time. **Content guardrails.** No secrets (tokens, keys, credentials). No transcript dumps or raw tool output. Include only: current focus, open loops, and the diff --git a/codev-skeleton/.codex/skills/arch-init/SKILL.md b/codev-skeleton/.codex/skills/arch-init/SKILL.md index e032a0f5f..b69b0b751 100644 --- a/codev-skeleton/.codex/skills/arch-init/SKILL.md +++ b/codev-skeleton/.codex/skills/arch-init/SKILL.md @@ -77,11 +77,23 @@ plus the most recent dated section*, so a save must leave exactly that behind: 1. **Rewrite the current-state / open-loops section in place** — overwrite it with where things actually stand now (current focus + open loops + how to - resume). Do not accumulate stale "current state" blocks. + resume). Do not accumulate stale "current state" blocks, and never leave two + sections with the same heading (a duplicated "How to resume" or "Open loops" + means you appended where you should have overwritten). **Delete resolved + loops entirely** — a closed item's record is the log entry, not a lingering + line in current state. 2. **Append one short dated log entry** capturing what changed this stretch. -3. **Keep it to one screen (compaction discipline).** The state file is a - summary, not a transcript. When you append, prune stale dated sections so - the file stays readable at a glance. +3. **Compact — this is part of the save, not optional polish.** Every save + both adds AND removes: after writing, keep the recent dated log entries in + full and collapse older ones into a single one-line summary that names + where the detail lives (the closed PRs, issues, and reviews it covered). + Remember these state files are gitignored — there is no git history to + fall back on, so pruned prose is gone for good. Prune by replacing detail + with pointers to durable artifacts, never by deleting the only record of + something. The file is a summary a fresh session reads at a glance — + one screen is the right order of magnitude, judged by you. If a save has + grown it past easy readability, prune as part of that save rather than + leaving it for next time. **Content guardrails.** No secrets (tokens, keys, credentials). No transcript dumps or raw tool output. Include only: current focus, open loops, and the diff --git a/codev-skeleton/roles/architect.md b/codev-skeleton/roles/architect.md index 750e651fc..56cac231d 100644 --- a/codev-skeleton/roles/architect.md +++ b/codev-skeleton/roles/architect.md @@ -170,6 +170,17 @@ gh pr view --json files | jq '.files[].path' # See which subsystems - **Medium**: SPIR features, new commands, refactors touching 3+ files - **High**: Protocol changes, porch state machine, Tower architecture, security model +#### Presenting the decision to the human (PRFT) + +When you bring a fix to the human for a decision — a merge word, a `pr` gate, a dev-approval — present it **unprompted** in PRFT form, whatever the risk tier: + +- **Problem** — the user-visible symptom, in a sentence or two. +- **Root Cause** — the verified mechanism. Verify it yourself; a builder's summary is evidence, not ground truth. +- **Fix** — what changed and why it's safe. +- **Testing** — the evidence: suites run, live verification, CI state. + +Keep each part tight and lead with it — don't bury the decision under process narration. The human should be able to say yes or no from your message alone, without opening the diff. + #### Step 3: Execute Review **Low risk** — no external models needed: diff --git a/codev/roles/architect.md b/codev/roles/architect.md index cd3c0709e..aa07e6fbd 100644 --- a/codev/roles/architect.md +++ b/codev/roles/architect.md @@ -170,6 +170,17 @@ gh pr view --json files | jq '.files[].path' # See which subsystems - **Medium**: SPIR features, new commands, refactors touching 3+ files - **High**: Protocol changes, porch state machine, Tower architecture, security model +#### Presenting the decision to the human (PRFT) + +When you bring a fix to the human for a decision — a merge word, a `pr` gate, a dev-approval — present it **unprompted** in PRFT form, whatever the risk tier: + +- **Problem** — the user-visible symptom, in a sentence or two. +- **Root Cause** — the verified mechanism. Verify it yourself; a builder's summary is evidence, not ground truth. +- **Fix** — what changed and why it's safe. +- **Testing** — the evidence: suites run, live verification, CI state. + +Keep each part tight and lead with it — don't bury the decision under process narration. The human should be able to say yes or no from your message alone, without opening the diff. + #### Step 3: Execute Review **Low risk** — no external models needed: diff --git a/packages/codev/src/agent-farm/__tests__/spec-1134-arch-init-skill.test.ts b/packages/codev/src/agent-farm/__tests__/spec-1134-arch-init-skill.test.ts index e25d521f4..9bbc6c380 100644 --- a/packages/codev/src/agent-farm/__tests__/spec-1134-arch-init-skill.test.ts +++ b/packages/codev/src/agent-farm/__tests__/spec-1134-arch-init-skill.test.ts @@ -101,10 +101,11 @@ describe('Spec 1134 — /arch-init skill ships in both trees', () => { expect(t).toMatch(/append.*dated/i); }); - it('carries compaction discipline (one screen / prune stale sections)', () => { + it('carries compaction discipline (one screen / compact / prune)', () => { const t = text(); expect(t).toMatch(/one screen/i); - expect(t).toMatch(/prune stale/i); + expect(t).toMatch(/compact/i); + expect(t).toMatch(/prune/i); }); it('carries save content guardrails (no secrets, no transcript dumps)', () => {