Skip to content

v0.5.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 11 Jun 06:31
· 26 commits to main since this release
v0.5.0
9d0dda9

v0.5.0

[0.5.0] — 2026-06-11

Added

  • close-gate: per-task | pr-boundary policy key — controls where the human-blocking close approval sits. per-task (default, current behavior): Task Close Report blocks on the user's "ok" at every task close. pr-boundary: an independent read-only reviewer subagent does the per-task read, Task Close Reports are still written every task (audit trail, non-blocking), and the human's blocking approval happens once per PR/merge — which MUST keep a human-written approval marker the AI cannot author (the self-certification hole stays closed). Deterministic task-done/phase-done gates unchanged in both modes; flipping the key is framed as a falsifiable experiment (catch parity + comprehension drift over 2-3 tracks, rollback = flip back). Registry in references/output-format.md; full mechanics + attack surface in references/close-gate.md §"Approval timing"; wired into SKILL.md cadence step 6, references/cadence.md §Step 5, and the /init-harness pre-fill list.
  • references/parallel-work.md — parallel-work discipline, previously implicit: WIP=1 (one active code track per project; the gate chain serializes on the human, so parallel code tracks multiply gate load + merge risk without adding speed), the sidecar exception (doc-only research/investigation may run parallel to the active code track: no gate chain, zero code changes, writes only research docs, never the status/roadmap file), and the single-writer rule (when multiple sessions share a worktree, exactly one holds the pen for the status/roadmap file; sidecar findings enter through the pen-holder; explicit pen handover). SKILL.md gains a "Parallel work & multi-session discipline" conventions section + Quick Reference rows + a Red Flag; references/roadmap.md gains the concurrent-writes anti-pattern.
  • references/roadmap.md §"Close protocol — the status-file ring" — fixes the append-forever close protocol that grows the read-first status doc past what a single Read can load (observed: 634 lines / 76k+ tokens on a dogfood project). At every milestone/track close, in ONE edit: new closed paragraph enters the active section's ring (active + 2 most recent closed entries), the oldest closed paragraph moves verbatim to a dedicated archive file (newest-first; never into RESUME-as-verbose-history or another living doc with its own job), and a one-line pointer stays behind. O(1) per close, rides the existing close step. Live-validated rules: zero edits at move time (git history is the second copy), retroactive amendments happen in the archive only, sidecar/doc-only entries don't occupy ring slots, and the protocol is deliberately ungated (a fat status file is loud and self-healing; re-evaluate after 2-3 closes). Honest boundary documented: the ring does not fix other append-forever sections (icebox/decisions-log) — that's capture discipline. Wired into SKILL.md step 10, references/milestone-done.md documentation gates, and the roadmap update discipline + anti-patterns.
  • references/user-story.md — two new template sections. Contingencies: pre-declared when <observable situation> → <single pre-decided action> responses for foreseeable mid-implementation situations, written at story time and injected verbatim into builder prompts at cadence step 1 — the builder follows the pre-decided action instead of guessing or burning a controller round-trip; only undeclared surprises escalate via BLOCKED/NEEDS_CONTEXT. none must be written explicitly (absence is a decision, not an omission). Invariants (machine-checkable, optional): phase-specific constraints pure code can verify — each entry must ship a runnable check command (a check that cannot fail is rejected); declared commands run once at declaration time and again at phase close with output in the test-evidence/PR comment. Automatic close-gate manifest wiring deliberately deferred until real invariants accumulate. New anti-patterns + downstream-table rows; SKILL.md cadence step 1, Quick Reference, and the reference index updated to match.
  • commands/builder-profile.md + references/builder-profile.md — a new /builder-profile slash command (opt-in, user-typed). Reads the user's own local Claude Code transcripts (~/.claude/projects/**/*.jsonl) and writes one markdown report to ~/.claude/builder-profile.md: a point-in-time snapshot of how the user actually uses an AI coding agent. Purpose is self-understanding (the user sees their own patterns → can use the agent better) + shared passive context any agent (Claude Code, a companion agent, …) can read on demand. The report is the whole product — no separate memory seed, no skill step wired to consume it. 100% local — no network call, no upload. Gated honesty pipeline: PASS 1 deterministic Python → stats.json (no hallucinated numbers), PASS 1.5 evidence gate (< 3 instances → insufficient signal), PASS 2 self-blinded spine-first cold read (no flattery; synthesis-before-enumeration with an over-fit reverse-check), PASS 3 adversarial verify + magnitude check (no plausible-but-wrong, no narrative contradicting its own numbers), PASS 4 independent verification so the generator doesn't grade itself — scripts/builder_profile_verify.py runs hard framing assertions (no Level section, bands only on volume/model-tier with provenance, per-dimension confidence, tool-counts carry a scope token; exit 1 blocks delivery; tested in scripts/test_builder_profile_verify.py) plus a fresh-context cold critic fed only the rules + finished report. Framing is descriptive-by-default (1-10 scores behind --scores), operating-modes-not-one-archetype, two-kinds-of-confidence (interpretation ≠ measurement), usage-band-only (quality rating/ranking explicitly out-of-scope — needs an external population the tool won't collect), co-discovery-not-growth-edge, you-vs-you-not-leaderboard — the same discovery-over-judgment discipline as references/comprehension-co-discovery.md. After verification the command walks the user through the report in plain language in-conversation (spine-first, honest about what couldn't be measured, co-discovery as real questions) rather than just handing back a file path. Claude Code only for v1 (Codex / Cursor not read). JSONL parser schema + framing-safety rules + report shape in the reference.

Changed

  • Contribution flow: the repo is now the single source of truth — the edit-live-first + scripts/sync.sh mirror flow is retired (the live copy at ~/.claude/skills/project-lifecycle/ is no longer part of the flow; the versioned plugin cache is the consumption path). Unreleased changes are dogfooded via claude --plugin-dir <repo-path> (working tree shadows the installed version per session; confirm via /plugins; SKILL/reference text live immediately, hooks/+commands/ need /reload-plugins). Rewritten: CONTRIBUTING.md §"Before you open a PR", references/self-update-flow.md (full rewrite), SKILL.md §Self-update, README.md + README.zh-CN.md §Development. Mid-phase safety rule sharpened: merging to main is always safe (sessions keep their released version); only RELEASES wait for phase boundaries.
  • PR-body TL;DR shape is now four-part: Problem / What we did / Why we did it (new — the plain-words motivation/trade-off, distinct from §2's technical justification) / Result + honest boundary. Updated in SKILL.md step 8, references/handoff-template.md §TL;DR, and references/milestone-done.md; CONTRIBUTING.md's PR-body template now includes the TL;DR section it had drifted away from (the skill mandated it; the repo template never did).
  • references/cadence.md §Step 4 + references/close-gate.md + SKILL.md — selective re-verification after fixup, task level only: re-run only the verifier scopes the fixup diff touched (affected AC IDs / folder-map side); acceptance verifier re-runs affected ACs only, validator re-checks its own findings + the fixup diff only, unaffected-scope suites may be skipped at task level with task-done test-evidence scoped accordingly. Two hard boundaries: phase-done still demands complete full-suite evidence (the full run is the safety net — phase-level gating is unchanged), and a falsification rule (if the phase gate catches a regression that a skipped task-level re-run would have caught, log it and stop using selectivity for the rest of the phase). Takes effect at the next phase boundary on mid-phase projects — a running phase's exit criteria never change.
  • README.md + README.zh-CN.md — added a one-line positioning statement at the top: Project Life Cycle helps teams turn ad-hoc AI coding sessions into repeatable, verifiable, traceable software development processes.
  • README.md + README.zh-CN.md — synced docs with what Claude Code actually shows after plugin install: the TL;DR /builder-profile bullet now carries the gated pipeline (deterministic stats → evidence gate → cold-read → adversarial verify → independent verification) and the --scores opt-in from the command's real description, and the install section now lists the namespaced command forms (/project-lifecycle:init-harness, …) users see in the command list, noting the bare forms used throughout the README resolve as long as no other installed command claims the same name.

Fixed

  • hooks/guard.sh — tokenizes the command with shlex before matching, so a git commit -m "…--no-verify…" (or a message that merely mentions main) is no longer falsely blocked; only a real --no-verify argv token or a real main push-ref triggers the guard. Fails open on unparseable commands. Adds two regression tests to hooks/test-hooks.sh.

Removed

  • scripts/sync.sh — the live ↔ repo sync bridge is gone with the flow that needed it. The sync commit type, the sync PR label, and the sync-script PR label are removed from CONTRIBUTING.md, references/changelog.md, references/handoff-template.md, SKILL.md, and .github/release.yml (sync-script merges into tooling). scripts/commands-manifest.txt stays — validate.py still reconciles it against commands/.
  • docs/ is no longer tracked in the repository — internal working documents are local-only; .gitignore now excludes the directory.

Full history: see CHANGELOG.md

What's Changed

✨ New Features & References

  • feat(references): add parallel-work.md — WIP=1, sidecar exception, single-writer rule by @Victoriakaey in #2
  • feat(close-gate): add close-gate policy key for human-approval timing (per-task | pr-boundary) by @Victoriakaey in #1

🛠 Workflow & Cadence Changes

  • feat(workflow): four-part PR TL;DR — adds 'Why we did it' bullet by @Victoriakaey in #4
  • feat(roadmap): add status-file ring close protocol by @Victoriakaey in #3

🤖 CI / Tooling

  • feat(tooling): retire the live-copy sync flow — repo is the single source of truth by @Victoriakaey in #5

New Contributors

Full Changelog: v0.1.0...v0.5.0

Contributors

Victoriakaey
Assets 2
Loading