joycraft 0.6.20 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -67,6 +67,84 @@ This is what Claude Code and Codex can't do out of the box: an unattended `inter
67
67
 
68
68
  On Claude Code, `/joycraft-implement-feature` gets you the in-session equivalent: one interactive invocation runs the whole queue with a fresh-context **subagent** per spec — the subagent boundary plays the role of Pi's process boundary. You're at the keyboard and it's one command, so none of the headless ToS/cost caveats apply.
69
69
 
70
+ ## What's new in 0.7 — the living harness
71
+
72
+ Through 0.6, Joycraft was excellent at *writing things down*: interviews became
73
+ briefs, briefs became specs, sessions ended with discoveries and decision-log
74
+ rows. What nothing enforced was whether any of it stayed **true** — specs could
75
+ quietly invent constraints, agents re-derived decisions the project had already
76
+ made, and the harness only ever grew. 0.7 closes that loop; the harness now
77
+ audits itself:
78
+
79
+ | | Before (≤0.6) | Now (0.7) |
80
+ |---|---|---|
81
+ | **Spec constraints** | Decompose could invent numbers/conventions that looked authoritative downstream | Every constraint carries a cite — `[src: D3]`, `[src: brief "Scope"]` — or is flagged `[src: INVENTED]` and stopped at a human gate; open decisions block decomposition entirely |
82
+ | **Design claims** | All claims read equally confident | Load-bearing claims are self-scored against fixed anchors (0/25/50/75/100); anything ≤50 is blocked from propagating until deepened or decided |
83
+ | **Prior knowledge** | Agents reasoned from scratch each phase | Research/design/decompose open with a bounded retrieval pass over `docs/context/` + `docs/discoveries/` and must cite what they reused |
84
+ | **Boundaries** | Prose rules an agent could drift past | `joycraft-harden` converts eligible rules into machine-checked deny patterns, stamped with provenance + a probation marker |
85
+ | **Harness growth** | Only ever grew | `joycraft-optimize` v2 assigns every control one of six dispositions (KEEP/ONE_HOME/LOAD_LATER/MAKE_A_CHECK/PROBATION/RETIRE); its Reaper deletes shipped feature folders only after the PR verifiably merged, and archive-moves abandoned ones |
86
+ | **Shipped features** | Folders sat forever; deleting lost the story | Session-end extracts a one-line ledger row to `docs/context/shipped.md` + marks the folder reap-eligible before the Reaper may touch it |
87
+ | **Skill surface** | All skills looked alike to discovery | Skills declare `entry: human \| agent \| situational` — human doors stay discoverable, internals get terse anti-discovery descriptions |
88
+ | **Trust** | The gates were assumed to work | Each gate was evaluated with N=3 fresh-context agent runs graded from tool-call timelines — one gate failed 2/3, got fixed, and re-passed 3/3 |
89
+
90
+ **Side effects to expect:** new files in your knowledge layer
91
+ (`docs/context/shipped.md`, `docs/context/anchors.md`,
92
+ `docs/reference/knowledge-lifecycle.md`), `(anchor: N)` annotations in design
93
+ artifacts, decompose refusing to run while a brief has an open decision, and
94
+ hardened rules being genuinely blocked at the hook layer — including for you.
95
+
96
+ As of **0.7.1 the full pilot ring ships in the npm package** — it piloted in
97
+ Joycraft's own repo first (the same discipline Joycraft asks of your projects)
98
+ and now needs real external projects to iterate against. The full
99
+ before/now/side-effects record is in [CHANGELOG.md](CHANGELOG.md).
100
+
101
+ ### Upgrading to 0.7
102
+
103
+ From your project root:
104
+
105
+ ```bash
106
+ npx joycraft@latest upgrade
107
+ ```
108
+
109
+ What this does to an existing setup:
110
+
111
+ - **Your customizations survive.** Upgrade diffs every file it installed against
112
+ what's on disk: unmodified files update silently, customized files show you
113
+ the diff and ask. Nothing is overwritten without a yes (or `--yes` in CI).
114
+ - **State file moves.** `.claude/.joycraft/state.json` migrates to
115
+ `docs/.joycraft/state.json` (gitignored, harness-neutral) automatically.
116
+ - **Session-end gains the extraction step.** The next time a feature finishes,
117
+ it writes a `docs/context/shipped.md` ledger row and marks the brief
118
+ `reap: eligible` — it never deletes anything.
119
+ - **Every skill gains `entry:` frontmatter** (human / agent / situational).
120
+ Purely additive; invocation is unchanged.
121
+ - **Harness selection is honored.** A Codex-only project stays Codex-only.
122
+ - **The pilot ring arrives (0.7.1).** Two new skills (`joycraft-decide`,
123
+ `joycraft-harden`), the retrieval pass, the decision gate + provenance-cited
124
+ specs, confidence anchors, and optimize v2 with the Reaper. The gates you'll
125
+ feel first: decompose blocks on open decisions, and invented spec premises
126
+ stop at a human review before any spec file is written.
127
+
128
+ **Or let your agent drive it.** Paste this prompt into Claude Code, Codex, or
129
+ Pi inside your project and it will run the upgrade, show you what changed, and
130
+ leave a reviewable commit:
131
+
132
+ ```text
133
+ Upgrade Joycraft in this project to 0.7. Steps: (1) Create a branch
134
+ chore/joycraft-0.7. (2) Run `npx joycraft@latest upgrade` interactively —
135
+ when it shows a diff for a file I customized, summarize the diff for me in
136
+ one or two sentences and ask before accepting; never blanket-accept.
137
+ (3) After the upgrade, list every file it changed, added, or migrated
138
+ (including the docs/.joycraft/state.json move), and read CHANGELOG.md's
139
+ 0.7.0 entry from the joycraft package to explain in plain terms what
140
+ changed about how my harness behaves — before vs. now, plus side effects
141
+ I should expect. (4) Confirm my harness selection and gitignore profile
142
+ were preserved, and that my CLAUDE.md/AGENTS.md customizations are intact.
143
+ (5) Run my project's test and typecheck commands to confirm nothing broke.
144
+ (6) Commit the result with message "chore: upgrade joycraft to 0.7" and
145
+ show me the diff stat — do not push or open a PR without asking.
146
+ ```
147
+
70
148
  ## Quick Start
71
149
 
72
150
  First, install the CLI:
@@ -173,6 +251,9 @@ Frameworks auto-detected: Next.js, FastAPI, Django, Flask, Actix, Axum, Express,
173
251
  | Run a feature's whole spec queue from one command | `/joycraft-implement-feature` | Fresh-context subagent per spec → fail-fast → session-end once |
174
252
  | Run specs autonomously without hand-holding | `/joycraft-implement-level5` | Experimental — autofix loop + holdout scenario testing |
175
253
  | Verify an implementation independently | `/joycraft-verify` | Read-only subagent checks work against the spec |
254
+ | Wrap up when a feature's specs are done | `/joycraft-session-end` | Consolidate discoveries → validate → graduate specs → ledger row → push/PR |
255
+ | Assess and mature your harness | `/joycraft-tune` | Score 7 dimensions → apply fixes → maturity roadmap |
256
+ | Audit harness overhead and prune | `/joycraft-optimize` | Six-disposition self-audit; its Reaper pass retires shipped/abandoned feature folders |
176
257
  | Set up Joycraft for a team | `/joycraft-collaborative-setup` | Scaffold `docs/areas/`, owner conventions, a team CONTRIBUTING doc |
177
258
 
178
259
  The core loop: