Skip to content

feat: spec & docs & review redux — contract-forward docs, adversarial review, loop skill - #64

Merged
skapoor8 merged 3 commits into
mainfrom
feature/spec-and-review-redux
Aug 30, 2026
Merged

feat: spec & docs & review redux — contract-forward docs, adversarial review, loop skill#64
skapoor8 merged 3 commits into
mainfrom
feature/spec-and-review-redux

Conversation

@skapoor8

@skapoor8 skapoor8 commented Aug 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Intent

Generated docs and requirements in the codevoyant skills kept restating the design instead of saying what the software is for, diagrams shipped without ever being rendered, and /pr review was not exhaustive. This branch tightens all three: docs become contract-forward with human-owned prose, requirements follow a strict rule set, artifacts pass a render gate before they are written, and reviews gain an adversarial pass plus verification gates. It also fixes the split-brain .codevoyant store that worktrees and the main repo were creating separately.

Changes

  • Shared store init: one skills/shared/store-init/cv_init_store.py replaces eight inline copies via vendor.json; worktrees and the main repo now resolve to the same ~/.codevoyant/<project-slug>/ store
  • Docs become contract-forward and prose-minimal: prose sections are @human fill-ins, artifacts stay agent-generated; retcon no longer writes prose, review flags any it finds
  • New validate_artifacts.py gate: every mermaid diagram renders with a pinned CLI and passes node/label caps before a doc is written
  • Requirements authoring constrained by the R1–R7 rule set: requirements must read as domain outcomes, not design restatement; gated in docs review and spec planning
  • Fifth adversarial review dimension: a red-team agent whose BLOCKING findings each carry a concrete failing scenario, plus gates for CI status, a static security floor, and PR-body claim verification
  • Reviews now post file-level, resolvable comments only; a top-level comment appears only for structural issues that cannot be anchored to a file
  • Doc-aware plans refuse cross-module writes unless the plan calls out the boundary explicitly
  • New loop skill: repeats a task until its objective is met or a max iteration count, each iteration in a background agent
  • Spec tabulates every enumerable set (rote replacements, file sets, requirement sets) into spec/{plan}/tables/ and checks completeness at validation time, so nothing written in intent.md is silently dropped
  • Replaces CLAUDE.md with AGENTS.md and drops Claude Code config (the original commit on this branch)

Validation

  • mise run test passes
  • mise run skills:validate passes
  • CI green on every phase commit (ff35c7b..613c86c)

Future Work

  • Real mutation-testing tooling behind a future --run-tests flag for the adversarial pass
  • Calibrating the adversarial pass's BLOCKING threshold against real reviews
  • Extending the store-init fix to the user-level dev/pm explore skills outside this repo

@skapoor8 skapoor8 changed the title chore: replace CLAUDE.md with AGENTS.md and drop Claude Code config feat: spec & docs & review redux — contract-forward docs, adversarial review, loop skill Aug 30, 2026
skapoor8
skapoor8 commented Aug 30, 2026
View reviewed changes

@skapoor8 skapoor8 left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inline comments only.

Comment thread skills/spec/references/validation-prompt.md Outdated
Comment thread skills/docs/scripts/validate_artifacts.py Outdated
Comment thread skills/docs/scripts/validate_artifacts.py
Comment thread skills/pr/references/workflows/review.md
Comment thread skills/docs/scripts/validate_artifacts.py Outdated
Comment thread skills/pr/references/workflows/review.md
Comment thread skills/docs/scripts/test_validate_artifacts.py
@skapoor8
feat(skills): rebuild spec and review pipeline with validation gates
dee4925 
**Store**
- add shared store-init script with unit tests, vendored into nine
  skills through the keyed vendor-assets manifest
- replace inline bash copies and wire store init into the explore,
  pr, docs, and qa workflows that touch .codevoyant

**Spec**
- tabulate enumerable sets with completeness gates: tabulation.md
  contract, tables/ directory, SCOPE=tabulation validation
- refuse uncalled-out cross-module writes in doc-aware mode via
  boundary callouts, [BLOCKED] entries, and review audits
- add constrained Requirements block with SCOPE=requirements
  validation in the plan template and spec review

**Review**
- add adversarial review dimension: red-team-adversary (Dimension 5)
  and claim-checker agents
- add security gates, CI/commit/static-floor checks; restrict to
  file-level comments with a fixed minimal publish fallback

**Docs**
- contract-forward prose-minimal policy: closed LLM text budget and
  @Human markers across twelve templates
- CLI artifact validation gate with pinned mermaid renderer and
  semantic caps; refresh pr, docs, and spec pages and add loop page

**Requirements**
- R1-R7 constrained requirements authoring with gate semantics,
  enforced in docs review and spec validation

**Loop**
- new bounded repeat-until-objective loop skill with runner and
  judge background agents and a max-iterations bound

**Housekeeping**
- replace CLAUDE.md with AGENTS.md, drop Claude Code config, and
  move the changelog sanitizer to a mise task
@skapoor8
skapoor8 force-pushed the feature/spec-and-review-redux branch from 4abc5e5 to dee4925 Compare August 30, 2026 05:57
skapoor8
skapoor8 commented Aug 30, 2026
View reviewed changes
Comment thread skills/loop/SKILL.md
Comment thread skills/loop/agents/loop-judge.md Outdated
Comment thread skills/qa/scripts/test_cv_init_store.py Outdated
@skapoor8
fix(vendor): respect the files filter so shared tests stay in shared
826dc72 
- vendor-assets treated `files` as a union with the whole source dir;
  it is an exclusive filter per the documented contract
- re-vendor: drop the 10 vendored test_cv_init_store.py copies; the
  test lives only in skills/shared/store-init/ (still run by mise test)
- update the vendor-assets tests to the new contract (unlisted files
  stay put; assets without `files` still walk the whole source)
@skapoor8
refactor(loop): collapse to a single-command run with a tracking doc
8410456 
- drop the flow-style definition model: no new/go/list/status workflows,
  no saved loop definitions — loops are not flows
- /loop <task> --until <objective> [--max N] [--check <cmd>] [--resume <slug>]
  writes the tracking doc (.codevoyant/loops/{slug}/loop.md) and runs
  immediately; the procedure lives inline in SKILL.md
- merge loop-runner + loop-judge into one loop-agent that performs the
  task and strictly judges the objective per iteration
- update docs/skills/loop.md to match
@skapoor8
skapoor8 merged commit aed74ce into main Aug 30, 2026
2 checks passed
@github-actions

github-actions Bot commented Aug 30, 2026

Copy link
Copy Markdown

🎉 This PR is included in version 2.1.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

github-actions Bot pushed a commit that referenced this pull request Aug 30, 2026
@semantic-release-bot
chore(release): 2.1.1 [skip ci]
0591eca 
## [2.1.1](v2.1.0...v2.1.1) (2026-08-30)

### Bug Fixes

* **docs:** escape bare angle-bracket tokens that break the vitepress build

- <command>/<slug>/<branch> in prose are parsed as HTML tags by the
  Vue compiler (loop.md/pr.md/spec.md) — wrap them in inline code

- surfaced by the Deploy Docs job on main after PR #64; branch CI
  never caught it because ci.yml does not build docs
@skapoor8
skapoor8 deleted the feature/spec-and-review-redux branch August 30, 2026 19:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

released

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@skapoor8