skills/boshu2__agentops
1
0
Fork 0
mirror of https://github.com/boshu2/agentops.git synced 2026-09-14 15:08:13 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
ao-pre-reduction@5b334a13f
boshu2__agentops/docs/council-log
T
History
Boden Fuller 63c8b81ad6 feat(skills,docs): --evidence/--tdd council mode, --discovery-artifact rpi flag, stale-scope planning rule, docs/council-log/ 
Operationalizes the "pre-flight council validation against stale inherited
scope" pattern that caught the na-h61 M8 estimate inflation in the same
session. Five items from the summary table in today's retrospective.

## New flags

/council --evidence  (alias --tdd)
  Every finding must include 2+ test_assertions (grep, stat, go test, ...)
  that would mechanically prove the finding is real. Consolidation clamps
  verdict to WARN if any finding lacks assertions. Schema version bumps
  3 → 4. See skills/council/references/evidence-mode.md for the full
  schema, judge prompt additions, and a worked example.

/council --commit-ready
  Also writes the consolidated report to docs/council-log/YYYY-MM-DD-
  <mode>-<target-slug>.md (in addition to the transient .agents/council/
  path). Use when the verdict is load-bearing for a merged commit and
  the provenance should survive rebases. See docs/council-log/README.md.

/rpi --from=implementation --discovery-artifact=<path>
  Explicit "external discovery" entry point. When discovery has already
  been done by an upstream /council --evidence run (or a hand-written
  plan), pass the path and /rpi validates the artifact, extracts scope
  into an execution packet, and proceeds straight to /crank. See
  skills/rpi/references/discovery-artifact-mode.md. Formalizes the
  improvised pattern used in the na-h61 session earlier today.

## New planning rule

skills/plan/references/stale-scope-validation.md
  "Re-validate inherited scope estimates against HEAD before acting on
  deferred beads, handoff docs, or prior-session plans." Referenced from
  skills/plan/SKILL.md and skills/pre-mortem/SKILL.md. Includes the
  concrete na-h61 case study (395 LOC estimate collapsed to ~300 LOC
  once the council verified the staging infra already existed).

## New committable council artifact path

docs/council-log/
  README.md documents the convention and retention policy.
  2026-04-11-validate-m8-assumption-validation.md is the canonical
  example — the consolidation that caught the na-h61 scope inflation,
  now in git history so any future session can re-verify the reasoning.

## Files

skills/council/SKILL.md                             (+3 lines — new flags)
skills/council/references/evidence-mode.md          (new, ~180 lines)
skills/rpi/SKILL.md                                 (+3 lines — new flag)
skills/rpi/references/discovery-artifact-mode.md    (new, ~130 lines)
skills/plan/SKILL.md                                (+1 line — rule ref)
skills/plan/references/stale-scope-validation.md    (new, ~100 lines)
skills/pre-mortem/SKILL.md                          (+1 line — rule ref)
docs/council-log/README.md                          (new, ~90 lines)
docs/council-log/2026-04-11-validate-m8-...         (new, canonical example)

Follows the same-session retrospective request from the user after
closing na-h61. The CLI half (ao beads verify|lint|harvest) ships in a
separate commit.

Council parity: skills-codex/{council,rpi,plan,pre-mortem}/ exists and
is now drifted. Sync deferred per the CLAUDE.md deprecation note on
sync-codex-native-skills.sh — manual edit required, tracked as a
follow-up. Skill-lint remains pre-existing RED on main (unchanged by
this commit).
2026-04-11 08:35:39 -04:00
..
2026-04-11-validate-m8-assumption-validation.md
feat(skills,docs): --evidence/--tdd council mode, --discovery-artifact rpi flag, stale-scope planning rule, docs/council-log/
2026-04-11 08:35:39 -04:00
README.md
feat(skills,docs): --evidence/--tdd council mode, --discovery-artifact rpi flag, stale-scope planning rule, docs/council-log/
2026-04-11 08:35:39 -04:00

README.md

docs/council-log/

Committed provenance for high-stakes /council validations.

Purpose

When a council verdict is load-bearing for a merged commit (e.g., it caught a stale scope estimate, blocked a flawed plan, or validated an architectural decision), the consolidated report belongs in git history — not in the transient .agents/council/ directory. This directory exists so future readers of git log can trace why a decision was made back to the multi-judge evidence that supported it.

How artifacts land here

A /council invocation with --commit-ready writes its consolidated report to docs/council-log/YYYY-MM-DD-<type>-<target>.md in addition to the usual .agents/council/ path. Per-judge reports stay in .agents/council/ (transient, gitignored); only the consolidated verdict with evidence-mode test assertions lands here.

Example:

/council --evidence --commit-ready validate "M8 C1 Option A scope estimate"

Produces:

  • .agents/council/2026-04-11-m8-option-a-judge1.md (local, transient)
  • .agents/council/2026-04-11-m8-option-a-judge2.md (local, transient)
  • docs/council-log/2026-04-11-validate-m8-option-a.md (committed, shareable)

What belongs here (and what doesn't)

DO commit:

  • Councils that changed a load-bearing decision (scope estimate, architectural choice, migration go/no-go)
  • Councils that caught a stale or incorrect prior-session claim
  • Councils whose verdict is referenced by a commit message or PR body
  • --evidence-mode councils with test assertions future readers can re-verify

DO NOT commit:

  • Routine /vibe checks mid-implementation (those belong in .agents/council/)
  • Brainstorming exploration (ephemeral)
  • Research councils that produced no actionable verdict
  • Debug councils run to help the agent think (not decisions)

File naming convention

docs/council-log/YYYY-MM-DD-<mode>-<target-slug>.md

Where:

  • YYYY-MM-DD is the UTC date of the council invocation
  • <mode> is validate, brainstorm, or research
  • <target-slug> is a kebab-case summary of what was validated (e.g., m8-option-a, auth-migration-plan)

Multiple councils on the same day with the same target get a -<n> suffix: 2026-04-11-validate-m8-option-a-2.md.

Relationship to .agents/council/

Aspect .agents/council/ docs/council-log/
Gitignored? Yes No
Content All council output (per-judge + consolidated + packet) Consolidated report only
Purpose Transient working memory Durable provenance
Retention Until flywheel prune / local cleanup Permanent (survives rebase)
Who reads it Current session's agents Future agents + humans reviewing git history

Entry format

Each committed entry should lead with:

---
title: <Human-readable title>
date: YYYY-MM-DD
mode: validate | brainstorm | research
flags: --evidence --mixed ...
verdict: PASS | WARN | FAIL
confidence: HIGH | MEDIUM | LOW
judge_count: N
---

Followed by:

  1. TL;DR — what was decided and why
  2. Consolidated findings (each with test_assertions when --evidence was set)
  3. Disagreements (if any) with attribution
  4. Related commits/beads/PRs

See 2026-04-11-validate-m8-assumption-validation.md for the canonical example (the council that caught the na-h61 scope inflation).

Reference in New Issue View Git Blame Copy Permalink