Implementation Notes: Review Phase Graph Rework

Summary

The explicit-only review graph, durable report contract, three-review delivery budget, and adversarial skill-adherence evidence are implemented in canonical shared skills. The final pass refactors the runtime into the durable workflow-graph structure: one bootstrap, one deterministic router, four flat gates, and one mode-specific runtime handoff contract. Canonical source, Harness mirrors, managed fixtures, operator docs, and integration checks are aligned. Squash/push and successor-baseline publication/readback are the remaining release actions.

Implementation

review-phase now bootstraps through one deterministic router and loads exactly one flat gate: preparation, one bounded all-lens run, report retention, or routing return.
Delivery appends review-owned runtime records to its caller-provided handoff. Standalone review uses one deterministic repository-local handoff. Cold resume reconstructs the route from current evidence without transcript continuity.
The run gate freezes one bounded snapshot, runs one advisory autoreview plus all independent normative lenses, and writes one immutable local report. Retention and routing remain separate gates.
Delivery recovers retained review authority before its budget guard, permits at most three reviews and three corresponding repairs, and completes repair 3 through focused validation without review 4.
create-plan emits implementation_skill_guidance; implement-spec forwards each entry and requires exactly one implementation-note evidence record per guidance entry. Review verifies those records against changed artifacts.
Report navigation, frontmatter guidance, operator docs, sync tests, managed fixtures, and generated baseline identity now represent the same contract.

Direct Execution Deviation

The user explicitly requested direct implementation with goalify and writing-for-agents, without create-plan, implement-spec, or a delivery-phase wrapper. Therefore this run produced no PLAN.md and no plan-produced implementation_skill_guidance entries. The evidence below records the two explicitly assigned skills once each and does not fabricate guidance cardinality.

Skill Application Evidence

Skill	Status	How and where applied
`goalify`	`applied`	Activated one persistent goal covering canonical source, Harness mirrors, validation, main integration, and baseline publication; work continued against that completion boundary.
`writing-for-agents`	`applied`	Kept skill entrypoints concise, disclosed branch-specific graph and report rules through references, and preserved one authority for invocation, state, evidence, and retention semantics.

Source, Mirror, And Release Evidence

Canonical source: wearedevpunks/skills@423c6d59b285a423262ee8983475de4e13864746.
Canonical focused graph contracts pass 25/25 and the full shared-source suite passes 97/97 after reconciling the latest frontend source. Pointer, disclosure, no-op, syntax, diff, and applicable Skills CLI packaging audits pass.
Harness default sync and packaged canonical parity have zero differences. The active review mirror and packaged review skill also have zero byte differences. Managed fixtures and generated baseline identity resolve the same final source.
CHANGELOG.md and BASELINE_CHANGELOG.md define the planned successor baseline/stable/2026.08.11-review-phase-durable-workflow-graph, compatible with >=3.1.11 <4.
Publication is pending. No successor stable tag, uploaded assets, control-plane revision, or downstream hi check result is claimed here.

Durable Workflow Graph Final Pass

SKILL.md contains invocation policy and bootstrap only.
phases/router.md resolves one of four gates or one terminal, checkpoint, or blocked outcome from ordered current evidence.
prepare-review, run-review, retain-report, and return-route each own one bounded transition and return through the router instead of loading siblings.
references/runtime-handoff.md defines delivery and standalone storage, complete record shape, conflict reconciliation, cold-resume discovery, and explicit idempotent no-write outcomes.
AUTHORING-HANDOFF.md records every graph-authoring route and ends audit-complete after route, disclosure, handoff, test, and packaging validation.

Adversarial Review Chronology

Pass	Findings repaired	Completion evidence
1	Invocation boundary, budget-guard order, deterministic identities, retained-report uniqueness, readonly isolation, and stale wiki schema.	Canonical, CLI, and wiki focused checks reran after repair.
2	Zero-write exhaustion, byte and sidecar trust, derived-relation and schema semantics, and wiki ingestion fields.	Canonical contract and mirror/content checks reran after repair.
3	YAML frontmatter had to be validated before the authority fence.	The repair passed focused validation; execution then stopped without review 4.

Validation Evidence

Surface	Result	Evidence
Canonical shared skills	Pass	Focused graph contracts 25/25; full suite 97/97 after frontend reconciliation; pointer, disclosure, packaging, syntax, and diff audits passed.
CLI skill sync and content	Pass	Focused sync/content/fixture contracts 40/40; default sync and packaged canonical parity have zero differences.
CLI static checks	Pass	`check-types` and full `bun run --cwd apps/cli check` exited 0, covering Oxlint, Oxfmt on 394 files, and managed fixture 1/1; scoped diff checks passed.
Active review mirror	Pass	Active and packaged review skill directories have zero byte differences.
Wiki	Pass	Sync tests 8/8; sidebar 1/1; content current; focused frontmatter, metadata, links, formatting, and diff checks passed. Full wiki suite passes 11/12.

Acceptance Status

Range	Status	Evidence
AC-001 through AC-024	Met	Explicit invocation, target adapters, one frozen all-lens run, readonly validation, and failure semantics are covered by canonical and packaged contracts.
AC-025 through AC-029	Met	Planning guidance, worker forwarding, evidence cardinality, and adversarial verification are present in source and mirrors.
AC-030 through AC-054	Met	Immutable report retention, routing, counter recovery, repair epochs, clean fix-3 handoff, and distribution parity are covered by contracts, docs, and mirror checks.
AC-055 through AC-062	Met	External PR review remains excluded; budget exhaustion, lineage, preallocated run identity, atomic repair opening, and retry semantics are covered.

Pre-existing Blockers

The full wiki suite passes 11/12. Its only failure is the pre-existing .agents/skills/docs-onboarding/SKILL.md phrase hi scaffold init, outside this review-phase change. Focused review wiki tests and checks pass.
Full bun run --cwd apps/wiki check reaches current content and passes Oxlint, then Oxfmt reports two unrelated pre-existing scoped-agent-guidance grill-status and research-report files. Focused formatting for this review-phase diff passes.

Remaining Work

Squash the implementation to main and push it.
Publish baseline/stable/2026.08.11-review-phase-durable-workflow-graph with bun run baseline:publish, then read back release assets, control-plane authority, and downstream hi check evidence. Until then, no successor tag, uploaded asset, control-plane revision, or downstream result is claimed.

Implementation Notes: Review Phase Graph Rework

On this page