up-docs v0.7.1

[0.7.1] - 2026-04-24

Fixed

• up-docs-propagate-repo agent now audits AGENTS.md and AGENTS.reviews.md as mandatory targets on every run (same discipline as CLAUDE.md). These are Codex CLI's equivalent of CLAUDE.md; v0.7.0's mandatory-audit list omitted them, so a V2 migration could leave their "Session handoff: docs/handoff.md" pointers unchanged — Codex sessions would then try to read a deleted file. Discovered by the drift auditor on the homelab /up-docs:all run that ran immediately after v0.7.0 shipped. The auditor caught 4 findings; 2 of them were these two files.
• up-docs-propagate-repo V2 mandatory-audit block gains a post-split self-reference check: after Phase 1 has moved content from docs/handoff.md into docs/state.md (and siblings), grep the new files for literal docs/handoff.md strings. Pre-migration Session Instructions text frequently contained self-references like "Check docs/handoff.md (this file)" that became stale after the file was renamed to state.md. The check covers state.md, deployed.md, architecture.md, credentials.md — any of which may have inherited handoff.md references from their source sections. Fix in-place. Drift auditor caught this on homelab (docs/state.md:11 was the offender).
• Stale-file-scan NEVER-flag list extended to include AGENTS.reviews.md (was only AGENTS.md in v0.7.0).

Notes

Both fixes traced to the same root cause — v0.7.0's mandatory-audit list was modeled on Claude Code's file set (CLAUDE.md + docs/) and didn't account for Codex-specific files or self-reference drift from renames. Neither was caught in v0.7.0's example block, which kept the gaps invisible until a real-world /up-docs:all invocation exercised the full audit path.

up-docs v0.7.0

[0.7.0] - 2026-04-24

Changed

• Handoff-system-v2 adaptation. up-docs-propagate-repo, /up-docs:repo, and /up-docs:all now target the post-2026-04-24 handoff layout (docs/state.md + docs/deployed.md + docs/architecture.md + docs/credentials.md + docs/sessions/<YYYY-MM>.md + docs/bugs/<NNN>-*.md + docs/conventions.md + .claude/rules/*.md) while preserving full backward compatibility with the legacy docs/handoff.md layout via probe-based detection. Rationale: 23 repos in the author's fleet migrated to v2 during the 2026-04-24 batch (pre/post reduction 91.1% aggregate); the plugin now matches.

  • Layout detection: agent probes docs/state.md first. If present → V2; if absent and docs/handoff.md present → V1 legacy; otherwise NONE. No CLI flag or user input required.
  • V2 mandatory-audit rewrite: docs/state.md (**Last updated:** + 🔴/🟡/🟢 active-incidents block under ## Session Instructions, 2 KB hard cap), docs/deployed.md (deployment-truth rows + What Remains), docs/architecture.md (system graph, optional), docs/credentials.md (secret paths, optional), docs/sessions/<current-month>.md (append row with ≤20-word headline + commit SHAs + bug refs; update INDEX.md row count), docs/bugs/<NNN>-<slug>.md (create one per session-fixed bug with frontmatter; run docs/bugs/_regen_index.py after), docs/conventions.md (numbered skeleton; full rule body may live in .claude/rules/ after Phase 5 of migration), .claude/rules/<topic>.md (path-scoped behavioral rules, ≤200 lines per file), CLAUDE.md (usually no-change post-migration — pure index).
  • V1 legacy fallback: repos that haven't run the v2 migration still work. Agent falls back to the pre-0.7.0 audit (docs/handoff.md + docs/conventions.md) and includes an advisory note in its output suggesting the migration.
  • Handoff brief (Step 6/7 in skills) upgraded: sources fields from the matching layout. V2 brief pulls Last-work from docs/sessions/<current-month>.md, deployed from docs/deployed.md, active incidents from docs/state.md, open bugs from docs/bugs/INDEX.md (rows with status != fixed). V1 brief unchanged. NONE skips the brief silently.
  • Append-only bug KB rule codified: creating a new bug file uses max(existing_ids) + 1; editing or renumbering prior bug files is forbidden. Supersession handled via supersedes: / superseded_by: frontmatter fields, both files kept.
  • Stale-file scan NEVER-flag list extended to include v2 files (docs/state.md, docs/deployed.md, docs/architecture.md, docs/credentials.md, docs/specs-plans.md), the docs/sessions/ and docs/bugs/ directories (persistent logs), and everything under .claude/ (plugin-lifecycle-managed).
  • python3 docs/bugs/_regen_index.py is a sanctioned Bash call in the agent's guardrails (only destructive-adjacent operation allowed; rewrites docs/bugs/INDEX.md idempotently from frontmatter).

• templates/drift-finding.md example row updated: docs/handoff.md → docs/deployed.md to reflect the new layout's deployed-truth file.

Notes

Rule-body migration decision per repo:

• Phase 5 run (rule bodies in .claude/rules/): extend the matching rules file; leave docs/conventions.md pointer unchanged.
• Phase 5 deferred (real conventions.md still full-body): append to docs/conventions.md using the six-field schema + Quick Reference row.
• Template DOC-001/002/003 conventions.md: extend docs/conventions.md for now; Phase 5 backfill will migrate to rules later.

The plugin does not enforce one or the other — it adapts to what exists.

up-docs v0.6.1

Fixed

• up-docs-propagate-notion agent no longer fabricates version strings, identifiers, paths, or other load-bearing values when composing Notion prose. Added a dedicated <verification_discipline> block mirroring the pattern already applied to up-docs-audit-drift in 0.5.1: every fact written to Notion must come verbatim from the session-change summary or a just-retrieved notion-fetch result. Copy-paste discipline is mandatory; reconstruction from pattern or memory is forbidden. Includes sanctioned escape paths (omit missing detail, skip edit as "No change needed") when a value is not in the summary.

Triggered by a 2026-04-23 /up-docs:all run where the propagator fabricated three plugin version numbers into the Claude Code Plugins Notion page: 2.3.0, 2.2.0, 3.1.0 where the summary correctly stated 2.2.7, 1.4.0, 1.1.0. The drift auditor caught it on the same run, and the Notion page was corrected via a targeted re-dispatch immediately before this fix landed.

repo-hygiene v1.4.0

Changed

• /hygiene Step 2 (semantic audit of plugin READMEs, root README, and docs/ files) now dispatches the new hygiene-semantic-auditor subagent (Haiku) instead of reading all those files in the Opus context. Step 1 (seven parallel mechanical scripts) is unchanged — those are sub-second and benefit from immediate in-session failure escalation. Estimated ~15K tokens saved per hygiene run when invoked from Opus sessions.

Added

• hygiene-semantic-auditor (Haiku): read-only structural README/docs audit. Returns findings in the same JSON schema as the Step 1 scripts so the command merges them into a single unified findings list.

qt-suite v0.3.1

Changed

• gui-tester and test-generator agents changed from model: inherit to model: sonnet. When invoked from Opus sessions, inherit meant these agents ran on Opus for deterministic multi-step MCP interactions and coverage-gap test generation — Sonnet is the correct tier. Roughly 5× cheaper per invocation for Opus users.

qdev v1.3.0

Changed

• /qdev:deps-audit, /qdev:quality-review, and /qdev:doc-sync are now thin orchestrators that dispatch dedicated subagents rather than performing the research, analysis, and edit work inline. Estimated ~50K tokens saved per typical weekly usage cycle when invoked from Opus sessions.

Added

• qdev-deps-auditor (Haiku): manifest discovery + per-dependency CVE and version research via dual-source web search.
• qdev-quality-reviewer (Sonnet): research-first iterative quality review with pass loop + oscillation detection. Handles the pass loop; the command drives AskUserQuestion for needs-approval findings.
• qdev-doc-syncer (Haiku): docstring/JSDoc sync against current signatures. Dry-run and apply modes.

python-dev v1.1.0

Changed

• /python-code-review is now a thin orchestrator that dispatches the new python-code-reviewer subagent (Sonnet) instead of walking Opus through 11 domain audits inline. The 11 domain rules moved from the command body into the agent prompt. Estimated ~20K tokens saved per review when invoked from Opus sessions.

Added

• python-code-reviewer (Sonnet): runs all 11 domain passes (anti-patterns, type safety, design, style, resources, resilience, configuration, observability, testing, async, background jobs) and returns a prioritized findings report with file:line citations.

opus-context v1.1.0

Changed

• SessionStart hook now injects SKILL.md body into AI context via hookSpecificOutput.additionalContext JSON, replacing the prior terminal-only banner. The rules are now guaranteed to be present in every session from turn 1, rather than depending on behavioral skill auto-invocation that was unreliable.
• Tightened SKILL.md from ~1000 tokens to ~350 tokens. Removed the Anti-Patterns section (pure negative restatement of the baseline rules) and collapsed repeated justification prose. Every operational rule preserved.
• Terminal confirmation banner moved from stdout to stderr so stdout can carry the JSON payload.

Fixed

• Skill rules failed to fire in many Opus sessions because description-based auto-invocation depended on the model choosing to call the Skill tool. The mechanical SessionStart injection addresses the root cause.

home-assistant-dev v2.2.7

Changed

• ha-integration-reviewer agent downgraded from Sonnet to Haiku. The review checklist is structural (manifest fields, config_flow presence, coordinator usage, type annotations) — mechanical pattern-matching with no inference required. Roughly 40% reduction in per-review token cost when invoked from Opus sessions.

up-docs v0.6.0

Added

Handoff pruning + permission-gated stale-file detection in propagate-repo. Every /up-docs:repo and /up-docs:all run now performs routine maintenance alongside propagation:

• Handoff.md pruning (automatic, direct edit): docs/handoff.md "Last Updated" section retains at most the 5 most recent entries. Older session-outcome lines are pruned — the information is already preserved in git log and per-plugin CHANGELOGs. Bugs Found And Fixed is never pruned (persistent log). What Is Deployed, Architecture, and Gotchas are pruned only on demonstrable staleness, not age alone.

• Stale file scan (surface only): globs docs/superpowers/plans/, docs/superpowers/specs/, docs/plans/, docs/specs/, and any ISO-8601-prefixed .md under docs/. A file is flagged ONLY when ALL three hold: (1) contains a completion marker (Status: ✅ Complete, DO NOT EXECUTE, superseded by, archived, deprecated, replaced by); (2) the referenced work has shipped per CHANGELOG evidence; (3) file is older than 60 days. Active plans, templates, handoff/conventions/CLAUDE/README/AGENTS, and persistent logs are explicitly excluded.

• Permission-gated deletion: the propagator agent emits a ## Stale File Candidates section listing paths + reasons + confidence. It never executes rm. The skills (/up-docs:repo, /up-docs:all) pick up the list, present candidates via AskUserQuestion with multiSelect: true, and run git rm only on paths the user explicitly approves. No candidates → section omitted entirely.

• /up-docs:repo and /up-docs:all gain AskUserQuestion in allowed-tools and new stale-review steps (Step 5 in /up-docs:repo, Step 6 in /up-docs:all).

• up-docs-propagate-repo guardrails explicitly forbid destructive Bash operations (rm, git rm, mv of delete-marked files, truncating redirects). Deletion is owned by the skill + user consent flow.

Changed

• up-docs-audit-drift output-format block now explicitly enumerates the five required stats keys (total_findings, by_layer, high_confidence, unverifiable, destructive_fixes_required) and states unverifiable must always be emitted, even when zero. Pins the schema so zero-finding runs no longer drift to the legacy 4-key shape.