diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 6858baa..a7e7eb5 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "cdev", "displayName": "CDev — Continuous Development", - "version": "0.1.1", - "description": "Run coding agents unattended over weeks: the repository holds the plan, the state and the proof. One conditioning skill and one execution loop reading role profiles, planners, a plain-language explainer, and an optional multi-repo orchestration layer.", + "version": "0.2.0", + "description": "Run coding agents unattended over weeks: the repository holds the plan, the state and the proof. One conditioning skill and one execution loop reading role profiles, planners, status readers, a plain-language explainer, and an optional multi-repo orchestration layer.", "author": { "name": "elmayii" }, diff --git a/CHANGELOG.md b/CHANGELOG.md index c44d973..97dfb46 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,32 @@ All notable changes to the CDev plugin are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver. Installed copies update only when the version changes. +## [0.2.0] — 2026-09-19 + +### Added + +- **`cdev-status`** — a read-only reading of where a sprint stands, on three axes: functional + requirements, non-functional requirements, user stories. Engineered **at read time** from + the raw chain sprint → batch → handoff (plus decisions and git); the plan holds no + requirement list to maintain. Every item cites its source; percentages are estimates and + say so; `since ` adds a delta from git history, nothing persisted; an + axis the repository does not support reads "not derivable". Edits nothing, marks nothing. +- **`cdev-monorepo-status`** — the same three-axis reading for a SYSTEM sprint across its + repositories. Applies `cdev-status` by reference and adds only what is system-level: + contracts as a source, **local truth** (each repository's own plan and handoff, read in the + repository; workspace↔repo divergence flagged, the repository's state reported; the state + snapshot never decides), and one compact per-repository table. + +### Changed + +- **Planners close each batch's open decisions with the human before writing it** + (core — [RFC, Discussion #9](https://github.com/elmayii/cdev/discussions/9)). `cdev-planner` + shows the batch grouping, then goes batch by batch: questions with suggested answers and one + recommended → answers recorded → that batch written → next. No open decision, no question. + With no human present, a batch with open decisions is written `BLOCKED` naming each + decision — never `READY`. `cdev-monorepo-planner` applies the same rule by reference, per + SYSTEM_BATCH. + ## [0.1.1] — 2026-08-15 ### Fixed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6f2faa..1ee93ef 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,7 +23,7 @@ exactly that material. ## Repository layout -- `skills/` — the seven Claude Code skills (the current host binding). +- `skills/` — the nine Claude Code skills (the current host binding). - `profiles/` — role profiles: exactly four things each (what "verified" means, what "evidence" means, the hardest gate, the self-chosen work order). Never a different loop. - `templates/` — the conditioning render base (`PLACEHOLDERS.md` is the contract). diff --git a/README.md b/README.md index 31fab87..6ec26a0 100644 --- a/README.md +++ b/README.md @@ -74,10 +74,12 @@ Ten-minute worked example: [the walkthrough](docs/community/walkthrough.md). | `/cdev:bootstrap` | Prepare one repository for CDev | | `/cdev:cdev-planner` | Turn an objective into executable work, or analyze gaps | | `/cdev:cdev` | Run continuous development in a conditioned repository | +| `/cdev:cdev-status` | Read where the sprint stands — functional, non-functional, user stories — from the repo alone | | `/cdev:ockham` | Re-explain dense technical output in plain language | | `/cdev:bootstrap-monorepo` | Prepare a workspace coordinating several repositories | | `/cdev:cdev-monorepo-planner` | Plan and analyze work across repositories | | `/cdev:cdev-monorepo` | Execute coordinated work across conditioned repositories | +| `/cdev:cdev-monorepo-status` | The same reading for a system sprint, across its repositories | ## Which command, when? @@ -86,6 +88,7 @@ Ten-minute worked example: [the walkthrough](docs/community/walkthrough.md). | A repository, not yet prepared for autonomous work | `/cdev:bootstrap` | | You know the objective; the work is not structured yet | `/cdev:cdev-planner` | | The plan has executable work | `/cdev:cdev` — it works batch after batch | +| Several batches have run and you want to know where the sprint stands | `/cdev:cdev-status` — read-only, derived when you ask | | The plan ran out | The loop derives next work itself — only inside what your docs specify | | Something needs *you* | It stops only for real blockers, and names the exact decision | | The product spans several repositories | The `*-monorepo` commands — coordination that never takes a repo's autonomy away | @@ -110,6 +113,7 @@ because the local plan owns its order. Repositories the change doesn't touch are /cdev:bootstrap-monorepo # condition the workspace over your repos /cdev:cdev-monorepo-planner # system objective → real batches in each repo /cdev:cdev-monorepo # execute, coordinate, verify end to end +/cdev:cdev-monorepo-status # where the system sprint stands, repo by repo ``` The full mechanism, with a backend → frontend worked example: diff --git a/docs/08-installation.md b/docs/08-installation.md index 913e2d3..bee82c3 100644 --- a/docs/08-installation.md +++ b/docs/08-installation.md @@ -14,7 +14,7 @@ The plugin root ships four load-bearing directories, and they all travel togethe | Directory | Role | |---|---| -| `skills/` | The seven entry points (auto-discovered by the host) | +| `skills/` | The nine entry points (auto-discovered by the host) | | `profiles/` | The role profiles the loop and the conditioner read | | `templates/` | The render base for conditioning, with its placeholder contract | | `scripts/` | The bootstrap verifier and the sandbox fixture builder | @@ -42,17 +42,19 @@ complete copy of the plugin root at: ## What you get -Seven skills, namespaced by the plugin name: +Nine skills, namespaced by the plugin name: | Invocation | What it is | |---|---| | `/cdev:bootstrap` | Condition one repository (recognition-first, both halves, human gate) | | `/cdev:cdev` | The execution loop — dispatcher plus single loop reading the role profiles | | `/cdev:cdev-planner` | Single-repo planning: materialize an objective, or gap-analyze | +| `/cdev:cdev-status` | Read-only status of a sprint on three axes, derived at read time | | `/cdev:ockham` | User-invoked plain-language re-telling of dense output | | `/cdev:bootstrap-monorepo` | Condition a multi-repo workspace (never touches the children) | | `/cdev:cdev-monorepo` | The orchestrating loop over conditioned repositories | | `/cdev:cdev-monorepo-planner` | Cross-repo planning and gap analysis | +| `/cdev:cdev-monorepo-status` | Read-only status of a SYSTEM sprint across its repositories | The namespace is the point: un-namespaced copies in `~/.claude/skills` collide with anything sharing a name; `cdev:*` cannot. diff --git a/docs/09-cdev-monorepo.md b/docs/09-cdev-monorepo.md index a90bd0e..a3391b3 100644 --- a/docs/09-cdev-monorepo.md +++ b/docs/09-cdev-monorepo.md @@ -121,6 +121,10 @@ Independent references in different repositories may run in parallel. Work insid repository remains sequential, because its local plan owns the order. Repositories that are not referenced by the current system batch are not opened and do not block it. +At any point, `/cdev:cdev-monorepo-status` gives a read-only reading of where the system sprint +stands: functional requirements, non-functional requirements and user stories at system +level, then one line per repository — each repository's state read in the repository itself. + ### 5. Exchange durable handoffs Repositories do not communicate through an agent's conversational memory. A producer publishes diff --git a/docs/community/rfc-process.md b/docs/community/rfc-process.md index afd201d..ad86c96 100644 --- a/docs/community/rfc-process.md +++ b/docs/community/rfc-process.md @@ -18,7 +18,8 @@ rules) gets proposed and decided. 1. **Open a Discussion in the RFC category.** State: the rule you want to change or add, the recorded incident(s) that motivate it (link field reports — yours or others'), and the - smallest version of the change. + smallest version of the change. *Interim rule: until an RFC category exists (categories + are created by hand in the web UI), open it in **Ideas** with the title prefixed `[RFC]`.* 2. **Evidence bar:** the method's own precedent (docs/07 §6) — every core rule added so far traces to a specific recorded failure. "It would be cleaner" does not clear the bar; "here is the handoff entry where this broke" does. diff --git a/docs/develop/AGENT_EXECUTION_PROTOCOL.md b/docs/develop/AGENT_EXECUTION_PROTOCOL.md index 3fa1f26..a36a227 100644 --- a/docs/develop/AGENT_EXECUTION_PROTOCOL.md +++ b/docs/develop/AGENT_EXECUTION_PROTOCOL.md @@ -19,6 +19,14 @@ Run per batch, in order; record pass / fail / not-run per check in the handoff: 4. **Sandbox exercise** — for every touched skill: build a fixture with `scripts/sandbox.ps1`, have a fresh subagent follow the skill against a scripted scenario, record the outcome. A skill change without a sandbox exercise is `not-run`, and the batch is not `DONE`. + *Multi-repo skills:* `sandbox.ps1` builds single repositories only. While no workspace + fixture exists, a **recorded field exercise** stands in for the sandbox exercise of a + multi-repo skill: the branch loaded with `claude --plugin-dir`, run either by the human in + their own workspace, or — when the human asks — by the agent on **local clones** of that + workspace (never the real trees: clones outside this repository, `origin` removed, deleted + afterwards), with the human judging what only they can. Outcome written into the handoff, + anonymized; the sandbox check is recorded `not-run` with that reason (human decisions, + DECISIONS 2026-09-19 and 2026-09-20). ## Branches and commits diff --git a/docs/develop/AGENT_PROGRESS.md b/docs/develop/AGENT_PROGRESS.md index 2cd8f21..8584745 100644 --- a/docs/develop/AGENT_PROGRESS.md +++ b/docs/develop/AGENT_PROGRESS.md @@ -5,6 +5,385 @@ Newest-first. Required fields: date+unit · status · done · files · verificat --- +## 2026-09-20 · S10-B06 Field exercise — run by the agent on clones of a real workspace · still BLOCKED (on the human's judgment) + +**Why the agent ran it:** the human asked. Constraints and their reasons are in DECISIONS +2026-09-20: real trees never written to (a never-elevated gate; they carried uncommitted work; +the script's `git clean -fd` would have been destructive there) → two sets of local clones, +`--no-hardlinks`, **outside this public repository**, `origin` removed from every clone, real +workspace HEAD and dirty count identical before and after. Real skill loading: headless Claude +Code sessions with `--plugin-dir` on the branch. Product anonymized below; the raw outputs +stay in the agent's scratchpad and are not committed. + +**Part A — `cdev-monorepo-planner`, launched bare (no "ask me" line), throwaway objective +touching two repositories, the agent answering as the human between resumed turns:** +- A1 pointer followed — **held** (the transcript shows a Read of `cdev-planner/SKILL.md`; the + pointer exists only on the branch, so this also proves the branch loaded, not the installed + 0.1.1). +- A2 grouping before any write — **held**. A3 questions per SYSTEM_BATCH before that batch is + written — **held over two rounds**: clone untouched after turn 1; after turn 2 the first + SYSTEM_BATCH written (global plan, contract, bidirectional references and handoff notes in + the two participating repositories) and the third repository still untouched while the + second batch's own round was asked. +- A4 suggested answers + one recommended — **held**; the form tool — **not-run** (not + observable headless; the fallback binding was used). +- A5 system-level decisions — **held**: which repositories participate, the sync-point + artifact, verification level, the accesses the batch needs, a human-only schema step, and a + **permission** it said only the human can grant (waiving a repository's live-test rule). +- A6 no hand-back of the prompt — **held** (it asked what the prompt left genuinely open). + A7 gap-free batch unasked — **did not occur**. A8 answers dated in the workspace's + DECISIONS — **held** (one dated entry, 44 lines). +- Beyond the script: it took a free-text answer and **pushed back** where that answer collided + with a repository's local protocol, routing the batch toward `BLOCKED` instead of assuming; + it corrected one of its own assumptions by citing the workspace protocol. +- Cost observed: roughly 13 USD for the second turn alone. Planning on a real workspace is + expensive with or without the new rule. + +**Part B — `cdev-monorepo-status`, cold, read-only tool allow-list:** +- *Run 1* — **no status produced**: the session hit the human's usage limit (HTTP 429) after + about 17 minutes of API time and ~8 USD. Cause found in its transcript: for local truth it + fanned out to **three subagents**, each reading a repository's whole plan and log. The skill + did not ask for that. Before dying: B1 held, no write attempt, snapshot file not opened. +- *Fix 1* — "read narrowly" added to both status skills. *Run 2* — **status delivered**: + 5.5 minutes, **3.92 USD**, zero subagents, reads by slice (locate, then offset/limit), clone + clean. B1 held · B2 held (three axes in order, every item sourced to a SYSTEM_BATCH and its + local reference) · B3 held, one borderline row (production rollout gates listed as a + non-functional item) · B4 held (one estimated figure per axis; the executive reading says + ~25 points rest on "met, unverified") · B5 held · **B6 held and led the report**: "the + workspace plan says 3 of 8 closed, the repositories say 7 of 8 — the repository's state is + the one reported", divergences flagged, none resolved, snapshot file never opened · B8 held. +- *Defect found by run 2, in my fix:* the status's own method note said it had **not opened + the contracts, the global decisions or the local handoffs**. "Narrowly" had been read as + fewer sources. *Fix 2:* "slices, never fewer sources", and "name whatever you did not open". + Regression on the small sandbox fixture — **pass**: decisions (newest wins) and per-batch + handoff verification cited, the method note names what it did not open. **Fix 2 is + unexercised on the real workspace** — not re-run, to spare the human's quota (the exercise + had already cost roughly 30 USD of it); their own interactive run is that check. +- Worth the human's attention: the default scope landed on an **old SYSTEM sprint** — the only + one still marked `ACTIVE` in the global plan although later ones ran. The skill followed its + rule and said so at the top. Length: 1,623 words; the brevity line has little effect. +- B7 and B9 — **not-run: only the human can make them.** + +**Files:** skills/cdev-status/SKILL.md, skills/cdev-monorepo-status/SKILL.md, +docs/develop/AGENT_EXECUTION_PROTOCOL.md (§4 local line amended), docs/develop/DECISIONS.md, +docs/develop/SPRINTS.md, docs/develop/reports/s10.md. + +**Verification:** frontmatter — pass (9/9) · language — pass · periphery — pass · +`bash scripts/validate.sh` — pass · sandbox (`cdev-status`, regression after fix 2) — pass · +field exercise — as above. + +**Blockers:** the human's B7 and B9 on the produced status (path given in-session; it holds +product data and is not in this repository), optionally A4 interactively. The merge still +also waits on the RFC's summary. + +**Next:** on the human's judgment, close B06 → B07 → the sprint. + +--- + +## 2026-09-19 · S10-B07 Sprint verification, report and the pull request · BLOCKED (on B06 and the RFC) + +**Done:** Full protocol sequence over the final skill set (nine skills). Sprint report +`docs/develop/reports/s10.md`: what was added, what was deliberately not built and why (the +requirement lists, the isolation machinery, the workspace fixture, a written gap threshold), +what the exercises taught, the verification debt that remains, the contract delta for +installed copies. **Draft PR #10** opened against `main` from the template — What · Layer +(core, linking the RFC, + skill) · Evidence · `Closes #8` — with the two things the merge +waits on as unchecked boxes at the top, and "merge commit, not squash" stated. Opened under +the human's in-session authorization of 2026-09-19. Draft on purpose: marking it ready is one +click, and it should not look mergeable while two conditions are open. + +**Files:** docs/develop/reports/s10.md. + +**Verification:** frontmatter — pass (9/9) · language — pass (0 outside line 3) · periphery — +pass (product names in skills/ + profiles/: 0; named technologies in skills/: 0) · +`bash scripts/validate.sh` — pass (`cdev@0.2.0`, 9 skills, links) · +`claude plugin validate .` — pass (one pre-existing warning: the root pointer file) · plan +invariants — pass (exactly one `ACTIVE` sprint) · sandbox — per batch: B02 and B03 pass, +multi-repo skills **not-run** (declared) · CI `validate` on PR #10 — pass on ubuntu, macos +and windows (run 35453528910, observed after the push of `c9f44dd`). + +**Blockers — two human decisions, either order:** +1. **Run the field exercise** (`docs/develop/reports/s10-field-exercise.md`) and report back. + Unblocks B06, then B07. +2. **Summarize the RFC** in Discussion #9: accepted / rejected / needs-more-field-evidence. + Gates the merge only. +The merge itself, then the tag `v0.2.0`, the GitHub Release and the marketplace pin, are the +human's (commands in the B05 entry). + +**Next:** nothing ungated remains in Sprint 10. Sprint 04 is `PROPOSAL` (needs a human to name +a target repo). On the human's report: record the field entry, fix on the branch whatever +broke and have it re-observed, finish the report, close B06 → B07 → the sprint. + +--- + +## 2026-09-19 · S10-B06 Human field exercise of the monorepo skills · BLOCKED (on the human) + +**Done:** `docs/develop/reports/s10-field-exercise.md` — the script. Step 0 proves the session +is running the branch and not the installed 0.1.1 (checked from this repo: with +`--plugin-dir` the working tree wins — the skill's base directory is this repository and the +new sentence is present; the human re-checks from their workspace, because that is a +different working directory). Part A: `cdev-monorepo-planner` launched **bare** on a throwaway +two-repository objective, eight observations (pointer followed, grouping first, questions per +SYSTEM_BATCH before each write, suggested answers + recommended + form tool, system-level +decisions present, no hand-back of the prompt, gap-free batch unasked, answers dated in +DECISIONS), then everything discarded with git. Part B: `cdev-monorepo-status` cold, in a +**fresh session**, on the real SYSTEM sprint, nine observations — including the one only the +human can make: is there any requirement or story in it they do not recognise as theirs. + +**Files:** docs/develop/reports/s10-field-exercise.md. + +**Verification:** `bash scripts/validate.sh` — pass · product-name sweep over the script — pass +· the exercise itself — **not-run** (it is the human's). + +**Blockers:** **the human runs the script and reports back** (held / broke per observation, +B7 and B9 in their own words). This repository's agent never opens that workspace. Until the +entry exists: the sprint does not close, the PR is not merged, and both multi-repo skills +remain unproven — `cdev-monorepo-status` has never been seen running by anyone. + +**Next:** blocked-but-not-idle — B07's preparable parts: full protocol sequence, sprint +report, the pull request. + +--- + +## 2026-09-19 · S10-B05 Live docs and version 0.2.0 · DONE + +**Done:** The live surfaces that name the skill set now say nine and list both status +commands: `README.md` (command table, "which command, when", the monorepo block), +`docs/08-installation.md` ("nine entry points", "Nine skills", two table rows), +`CONTRIBUTING.md`, and one paragraph in `docs/09-cdev-monorepo.md` after the execution step. +In the same commit: `.claude-plugin/plugin.json` → `0.2.0` (its description gains "status +readers") and the CHANGELOG's Unreleased section becomes `## [0.2.0] — 2026-09-19`. Layer: +periphery / docs. Documents 01–07 untouched (extraction record); walkthrough not extended. + +**Left alone on purpose:** `docs/10-usage-recommendations.md` — it lists workloads with a model +and effort for each, and I have no evidence for what a read-only status warrants; inventing a +recommendation would be assertion, not evidence. `AGENTS.md:19` says "seven documents" — that +is the docs series, not the skills, and is correct. + +**Files:** README.md, CONTRIBUTING.md, docs/08-installation.md, docs/09-cdev-monorepo.md, +.claude-plugin/plugin.json, CHANGELOG.md. + +**Verification:** stale skill counts on live surfaces — pass (none; one found at doc 08 line +45 on the first sweep and fixed) · both commands present in README and doc 08 — pass · +`plugin.json` version and CHANGELOG heading agree (0.2.0) — pass · +`bash scripts/validate.sh` — pass (`manifest ok: cdev@0.2.0`, 9 skills, links) · +`claude plugin validate .` — pass · language / periphery / sandbox — not-run (no skill body +touched). + +**Release commands — prepared, NOT executed. After the merge, from `main`, the human's:** +``` +git checkout main && git pull +git tag -a v0.2.0 -m "v0.2.0 — status skills, planners that close open decisions per batch" +git push origin main v0.2.0 # annotated tags need the explicit push +gh release create v0.2.0 --title "v0.2.0" --notes-file +# then, in the marketplace clone — ALWAYS after the tag exists on GitHub: +# marketplace.json → "ref": "v0.2.0", "sha": "$(git -C ../cdev rev-parse v0.2.0^{commit})" +# commit, push; then /plugin marketplace update cdev-marketplace and confirm cdev@0.2.0 +``` + +**Blockers:** none. **Next:** B06 — the field-exercise script for the human. + +--- + +## 2026-09-19 · S10-B04 `cdev-monorepo-status` — the three axes for a SYSTEM sprint · DONE (sandbox not-run, declared) + +**Done:** New `skills/cdev-monorepo-status/SKILL.md` (layer: new skill). It does not restate +the method: a path pointer into `cdev-status` (resolved to the real path), plus only what the +system level adds — scope (the `ACTIVE` SYSTEM sprint, two independent numberings), sources +(SYSTEM_BATCHes and their references, sync points, the contracts under +`workspace/contracts/`), **local truth** (each affected repository's own plan and handoff, +read in the repository; divergence flagged, the repository's state reported; the state +snapshot file never read as a state), one compact per-repository table, "not derivable" by +repository name, and the system-level risks in the executive reading. + +**Files:** skills/cdev-monorepo-status/SKILL.md, CHANGELOG.md. + +**Verification:** frontmatter — pass · language — pass · periphery — pass · +`bash scripts/validate.sh` — pass (9 skills) · `claude plugin validate .` — pass · single home +— pass (the method's distinctive text greps in `cdev-status` only; this skill carries the +path pointer) · **live load** (`claude --plugin-dir . -p`) — pass: all nine skills list, +`cdev:cdev-status` and `cdev:cdev-monorepo-status` among them. *Correction to B03's entry:* its +acceptance also asked that `cdev:cdev-status` list; I had recorded only the static validation +there. The listing was checked here, for both skills. +· **sandbox — not-run** (declared: no workspace fixture exists; protocol §4 local line). This +skill has never been seen running. Its evidence is the human field exercise of B06, and the +sprint does not close without it. + +**Blockers:** none for this batch's own acceptance. **Next:** B05 — live docs and 0.2.0. + +--- + +## 2026-09-19 · S10-B03 `cdev-status` — progress on three axes, engineered at read time · DONE + +**Done:** New `skills/cdev-status/SKILL.md` (layer: new skill — read-only, loop untouched; record +in DECISIONS 2026-09-19). Scope (ACTIVE sprint / named / `all` / `since`), the read order over +the raw chain, the three axes in order with a source on every item, four states (met · met, +unverified · partial · pending), estimated percentages labelled as such, the report shape +accepted in the field, the git-derived delta, and the rules: read-only always, "not +derivable" instead of filling, disagreement flagged never resolved, the human's language. + +**Three defects of my own text, found by the first exercise round and fixed in-branch:** +(1) the skill named the protocol as a source of non-functional requirements, so both runs +listed the repo's working rules (check sequence, branch convention, gates) as NFRs — 4 of 8 +rows; now: system qualities only, the protocol tells you what "verified" means and is never +an item. (2) "met" required recorded verification while a rule also defined "met, unverified"; +a run resolved the ambiguity by giving every axis two figures; now an explicit fourth state, +one figure per axis, and the executive reading says how much rests on unverified items. +(3) ~1,100-word statuses against compact field specimens; a brevity line added — its effect +was modest, and much of the length came from the fixture's own plan↔git disagreements. + +**Files:** skills/cdev-status/SKILL.md, CHANGELOG.md. + +**Verification** (every run a fresh subagent with no planning context; fixture state captured +after each; all fixtures left with a clean tree — nothing written by the skill): +- frontmatter — pass · language — pass · periphery — pass · `bash scripts/validate.sh` — pass + · `claude plugin validate .` — pass (one pre-existing warning: the root pointer file). +- **(1) cold start** — pass, twice (before and after the fixes). Three axes in order; every + cited path exists; partials carry percentage + reason + owning batch; the decision changed + during implementation appears in its newest form citing DECISIONS and warning that the + batch text no longer holds; the `DONE`-with-`not-run` batch reads "met, unverified"; + executive reading and "what is left" present; answered in Spanish to a Spanish prompt. + After the fixes: system-only NFRs plus an explicit "no other quality is stated, none is + added"; one figure per axis. +- **(2) `since B01`** — pass. Resolved the bare batch id to the commit that closed it in the + sprint in scope (and said so), applied one item list to both states, "(before NN%)" per + axis, changed items marked. Without the argument: no delta (run 1). +- **(3) not derivable** — pass **on the fourth attempt; the first three are recorded, not + hidden.** Attempts 1 and 2 did not meet the clause by the letter, and the fault was the + fixtures': the premise "a sprint carrying no non-functional signal" was false — the signal + sat in the batch text, then in the product notes. In both the skill invented nothing and + named what was missing. Attempt 3 met the clause but is **discounted**: the fixture commit + I made to remove the signal was titled with the conclusion, and the agent read it in + `git log`. Attempt 4, on a fixture with the edit folded into ordinary commits and no hint + anywhere: the axis reads "not derivable", three missing things named, Sprint 02's + constraints explicitly not carried over, the decision routed to the planner. In no attempt + did a run invent a generic quality — not even input sanitising or file size, which an + HTML-import feature invites. +- **(4) unconditioned repo** — pass. Proposed `bootstrap`, refused to read percentages out of + the product notes, touched nothing. + +**Found by accident, worth keeping:** my status fixture recorded a batch `DONE` whose code was +never committed. Every run flagged the plan↔handoff↔git disagreement and none resolved it — +the rule held on a flaw I had not planted. + +**Blockers:** none. **Next:** B04 — `cdev-monorepo-status`. + +--- + +## 2026-09-19 · S10-B02 Planners close gaps per batch, before writing · DONE + +**Done:** `skills/cdev-planner/SKILL.md` gains § "Closing open decisions (before each batch is +written)" — the rule's single home — plus a Mode 1 step pointing at it, the PARTIAL line and +the `READY` promotion made consistent with it. The section names itself apart from Mode 2's +"gap analysis" (same word, different thing). `skills/cdev-monorepo-planner/SKILL.md` does not +restate it: a path pointer, applied per SYSTEM_BATCH, plus its own system-level sources of +open decisions. Both execution loops' planner invocations re-read (field rule 5): no +contradiction — a batch the planner leaves `BLOCKED` is simply not selected, which is what +blocked-but-not-idle already does; no loop text changed. Protocol §4 gains the local line on +multi-repo skills (field exercise stands in for the missing workspace fixture). CHANGELOG +bullet under Unreleased. Layer: **core** (RFC: Discussion #9). + +**Files:** skills/cdev-planner/SKILL.md, skills/cdev-monorepo-planner/SKILL.md, +docs/develop/AGENT_EXECUTION_PROTOCOL.md, CHANGELOG.md. + +**Verification:** +- frontmatter — pass (7/7) · language — pass (0 outside line 3) · periphery — pass (product + 0, tech names in skills 0) · `bash scripts/validate.sh` — pass. +- single home — pass: the rule's text greps in `cdev-planner` only; `cdev-monorepo-planner` + carries the path pointer. +- **sandbox, attended (`cdev-planner`)** — pass. Fresh subagent, hand-conditioned fixture, the + driver answering as the human through turn-ending messages (the host-binding fallback: no + form tool). Fixture state captured at every stop: T1 grouping shown + sprint-wide questions, + **nothing written**; T2 sprint header only; T3 batch 1 written after its answers; T4 batch + 2; T5 batch 3; T6 batches 4 and 5. Every round: lettered options, one recommended. It did + not ask what the product notes settle ("neither is a question"), asked a **permission** + question (may the batch edit the product source?), took a free-text answer, honoured an + answer that overruled its recommendation, recorded unasked assumptions per batch, and left + the ABSENT area unplanned with open questions. `DECISIONS.md` holds one dated entry per + batch. *Caveat, recorded honestly:* the planner found open decisions in every batch of the + original objective, so the "batch with no gap" clause was exercised by the driver adding a + fully specified fifth batch mid-run — it was written with no question and the spec was not + handed back for confirmation. +- **sandbox, unattended** — pass. Same fixture, no human: the undecided batch is `BLOCKED` + with two named decisions, a suggested answer each, and "not to be promoted on the + suggestions"; nothing `READY` rests on an unanswered decision it judged blocking. + *Observation:* this run judged "what counts as the same URL" a non-blocking open question + and wrote that batch `READY`; the attended run asked it. Judgment varies between runs — + the cost the RFC names for leaving the threshold unwritten. +- **baseline (`main`'s planner, attended scenario)** — recorded. It asked too, but once: one + up-front round (3 items), then all four batches written in one go, and its own report lists + five assumptions "the human has NOT seen" — decisions the new rule turns into per-batch + questions. That is the difference the rule makes. +- sandbox, `cdev-monorepo-planner` — **not-run** (no workspace fixture; protocol §4 local + line). Its evidence is the human field exercise of B06. + +**Fixture flaw found by all three runs:** the hand-conditioned fixture declared a batch `DONE` +whose work was never in the tree; every planner flagged it before planning and none repaired +it silently. Accidental, but it exercised Mode 1 step 1. + +**Blockers:** none. **Next:** B03 — `cdev-status`. + +--- + +## 2026-09-19 · S10-B01 Field evidence and the RFC · DONE + +**Done:** `docs/develop/reports/s10-field-evidence.md` — the two habits as the record shows +them (planner launches and the hand-typed gap-closing line; the three-axis status and how it +was really produced), the design the human rejected and why, and a "not evidenced" section. +Every load-bearing quote was re-read against the private source before writing; counts are +marked as one mining pass, spot-checked. Branch pushed; RFC opened as Discussion #9 in Ideas, +`[RFC]`-prefixed, five template headings, evidence linked by commit permalink (`6d06c26`); +issue #8 carries the linking comment. `docs/community/rfc-process.md` states the interim +category rule. Layer: docs (the core layer's prerequisite). Outward acts (push, Discussion, +issue comment) executed under the human's in-session authorization of 2026-09-19. + +**Files:** docs/develop/reports/s10-field-evidence.md, docs/community/rfc-process.md. + +**Verification:** product-name sweep over the evidence file (protocol §3 patterns plus the +vendor and place names in the source quotes) — pass, 0 matches · `bash scripts/validate.sh` +— pass · permalink resolves via the API — pass · Discussion category, prefix and five +headings read back via the API — pass · frontmatter / language / periphery / sandbox — +not-run (no skill touched). + +**Deviation:** B01 carries two commits, not one — the RFC must link the evidence by +permalink, so the evidence had to be committed and pushed before the Discussion could exist, +and this closing record could only follow it. + +**Blockers:** none for the work. The PR's merge waits on the human's "accepted" summary in +Discussion #9. + +**Next:** B02 — the gap-closing rule in `cdev-planner`, pointer in `cdev-monorepo-planner`. + +--- + +## 2026-09-19 · Planning — Sprint 10 drafted, then ratified ACTIVE by the human (cdev-planner) · DONE + +**Done:** Two read-only subagents mined the maintainer's prompt history and the surviving +transcripts for the two habits behind issue #8 (planner launches carrying a hand-written +gap-closing instruction; the three-axis status request). Plan↔git divergence found and +reconciled with human approval (S09/B01 → `DONE`, commit `c006c63`). Issue #8 opened and +later corrected (authorized in-session). Sprint 10 written as `PROPOSAL`, seven batches, each +written only after its own question round with the human — the first draft's B03 (a +maintained block of ID'd requirements in the plan) was **dropped on the human's review** and +the design moved the rigor to the reader instead. Clarity map gained four rows; decisions +recorded per batch. No skill, profile or template touched. + +**Files:** docs/develop/SPRINTS.md, DECISIONS.md, PRODUCT.md, AGENT_PROGRESS.md. + +**Verification:** `bash scripts/validate.sh` — pass (manifest, placeholders, frontmatter 7/7, +links) · plan invariants — zero `ACTIVE` sprints until the human ratifies S10 (plan-exhausted +state, not two actives) · frontmatter / language / +periphery / sandbox — not-run (no skill touched). + +**Blockers:** none for the start — the human ratified Sprint 10 to `ACTIVE` the same day +(DECISIONS 2026-09-19). Outward acts were authorized for this session only; B06 will block on +the human's field exercise, and the merge on the RFC's "accepted" summary. + +**Next:** `/cdev:cdev` runs S10 from B01 on +`feat/8-status-and-gap-closing-planners`. + +--- + ## 2026-08-16 · First CI workflow (issue #3) · DONE **Done:** `scripts/validate.sh` (portable bash: node for JSON, git grep, awk — runs locally diff --git a/docs/develop/DECISIONS.md b/docs/develop/DECISIONS.md index 3dc9c5a..289ab5a 100644 --- a/docs/develop/DECISIONS.md +++ b/docs/develop/DECISIONS.md @@ -2,6 +2,85 @@ Newest-first. Every assumption made under PARTIAL clarity lands here, dated. +## 2026-09-20 — S10-B06: the agent runs the field exercise, on clones (human-directed) + +Reverses part of 2026-09-19 ("field exercise by the human"): the human asked the agent to run +the script itself. Done under three constraints the agent set and the human did not object to: + +- **The real workspace and its repositories are never written to.** "Modifying the frozen + product repositories" is a never-elevated gate, the real trees carried uncommitted work, and + the script's discard step (`git clean -fd`) would have been destructive there. The exercise + ran on local clones (`--no-hardlinks`) **outside this public repository**, in the agent's + temporary scratchpad, with `origin` removed from every clone — otherwise a push from a clone + would have written into the real repository. Clones deleted afterwards. +- **Real skill loading, not a subagent reading a file:** headless Claude Code sessions with + `--plugin-dir` on the branch; the status run with a read-only tool allow-list, so a write + attempt would have been denied and logged. +- **What the agent cannot substitute stays with the human:** whether every requirement and + story in the status is one they recognise (B7), whether it is the status they used to ask + for by hand (B9), and the form tool (A4, not observable headless). B06 stays `BLOCKED` on + those, a much smaller ask than the original. + +Limitation recorded: clones see only what is committed on the checked-out branches; the +human's uncommitted work is invisible to them. + +Protocol §4's local line is amended accordingly. Product data seen during the exercise stays +in the scratchpad; nothing of it is committed here, and the handoff entry is anonymized. + +## 2026-09-19 — Sprint 10 planned: gap-closing planners + status skills (planner, human present) + +Planned by closing gaps with the human batch by batch, through the host's question form — +the behavior the sprint encodes. **Ratified `PROPOSAL` → `ACTIVE` by the human the same day**, +after reading the batch list; the planner wrote the state change on that instruction, it did +not decide it. Human answers, per unit: + +- **Sprint.** S09 reconciled to `DONE` as the branch's first commit (PR #5 had merged; the + plan had not caught up). Layers: planner change = **core** (RFC + field evidence); status + skills = **new skill** (this entry is the required record; read-only, the loop is + untouched, so no RFC). One issue (#8), one branch, one PR, one commit per batch. Outward + acts (issue, Discussion, branch push, PR) **authorized for this session only**. +- **B01.** Evidence lives in a repo file, linked from the RFC by commit permalink. Quotes in + English marked translated, Spanish original only for the load-bearing few, product + anonymized. No RFC category exists → Ideas with an `[RFC]` prefix, and rfc-process.md says + so. Work proceeds on the branch; the **merge** waits on the RFC's "accepted" summary. +- **B02.** No human present → the batch is written `BLOCKED` with each gap's decision and + suggested answer; never `READY`, never carried on the recommendation. What counts as a gap: + **the planner's judgment, no written threshold** — held conservatively. The rule lives once, + in `cdev-planner`; `cdev-monorepo-planner` points at it by path. A question closes + something undecided: the human's prompt is the intent and is never handed back for + confirmation. +- **Monorepo skills' evidence.** No workspace fixture will be built. A recorded **field + exercise by the human** stands in for the sandbox (protocol §4 gains the line; sandbox is + recorded `not-run`), gathered once, in its own batch (B06), on a throwaway objective whose + output is discarded — real plans receive nothing from an unmerged skill. +- **The plan's format does not change** (reverses the planner's first draft, which had a + per-sprint block of ID'd requirements and user stories with per-batch coverage). Human's + reasoning: sprints and batches already carry the intent in free form; a formalized list + must be kept current while a feature is still being discovered, and that maintenance is + what drifts. Consistent with doc 07: it would restate the plan (singularity) where field + rule 4 says derive on read. Nothing new is asked of the planner beyond gap closing; the + execution loop is untouched — status reads SPRINTS → DECISIONS → AGENT_PROGRESS, newest + wins. If field use shows decision changes going unrecorded, that is a future RFC with its + own evidence. +- **B03.** Percentages are **estimates**, as accepted in the field, labelled as such. Delta + comes from git on request (`since`), nothing persisted. Default scope: the `ACTIVE` sprint. + **No isolation machinery**: status is a read operation inside the conversation; CDev is a + procedure and does not guard the human against their own use of context. +- **B04.** System-level axes plus one compact line per repository. +- **B05.** Version bump to 0.2.0 rides inside the PR; tag, release and marketplace pin after + the merge, from `main`, by the human. + +Planner's own assumptions (not asked — judged derivable; the human may veto): +axis order functional → non-functional → user stories (the human's 2026-09-19 statement +supersedes the August order); `cdev-monorepo-status` points at `cdev-status` by path, by +analogy with the planners' single-home answer; PR merges by merge commit, not squash, to +keep one commit per batch (PR #5 precedent); the walkthrough is not extended. + +Finding recorded, not acted on: the monorepo skills have never been sandbox-exercised in this +repository, and S01-B04 closed `DONE` with sandbox `not-run` over skill changes, against +protocol §4's letter. Standing verification debt; B06's field evidence is the first proof +any monorepo skill here will have. + ## 2026-08-16 — AGENTS.md is the canonical repo guide (S09-B01, human-directed) - **Layer: host binding + docs.** Doc 07 §1.2 already says the guide's filename is convention diff --git a/docs/develop/PRODUCT.md b/docs/develop/PRODUCT.md index 6b0cf35..aa2c1e1 100644 --- a/docs/develop/PRODUCT.md +++ b/docs/develop/PRODUCT.md @@ -21,4 +21,8 @@ without asking. ABSENT areas produce open questions, never batches.** | Public README (five-minute comprehension) | **DEFINED** | strategy §6–§10, §22-2 | — | | Visual identity | **PARTIAL** | strategy §21 gives direction (`/cdev` wordmark + checkpoint line, no generic AI imagery); execution assumed agent-made SVG, human approves the result | Final asset approval | | Community structure (field reports, RFC, labels, Discussions content) | **DEFINED** | strategy §12–§14, §22-3 | Custom Discussions categories are web-UI manual | +| Planner gap closing (per batch, before writing) | **DEFINED** | Issue #8; field evidence `docs/develop/reports/s10-field-evidence.md` (S10-B01); human answers in DECISIONS 2026-09-19 | RFC acceptance gates the merge, not the work | +| Status skills — system level (`cdev-monorepo-status`) | **DEFINED** | Three field occurrences fix the request and the accepted output shape; DECISIONS 2026-09-19 | — | +| Status skills — single repo (`cdev-status`) | **PARTIAL** | No field occurrence of a three-axis status in a single repo: the shape is extrapolated from the system-level one (assumption recorded in the evidence file's "not evidenced" section) | First real use may correct the shape | +| A workspace (multi-repo) sandbox fixture | **ABSENT** | Human decision 2026-09-19: not built; field exercise stands in | Do not build unless asked | | Launch | **PARTIAL** | strategy §22-4 fixes channels and message; copy is draftable — publishing itself is always a human act | Human publishes each post | diff --git a/docs/develop/SPRINTS.md b/docs/develop/SPRINTS.md index 030714c..d3f20d3 100644 --- a/docs/develop/SPRINTS.md +++ b/docs/develop/SPRINTS.md @@ -227,12 +227,15 @@ Report `s07.md`. **Acceptance:** checks pass; report exists. --- -## Sprint 09 — Agent internationalization `ACTIVE` +## Sprint 09 — Agent internationalization `DONE` Objective: conditioned repositories usable by any coding agent, not just Claude Code. First externally-visible feature to flow through the public branch policy (branch → PR → main). -### B01 — AGENTS.md as the canonical repo guide `IN_PROGRESS` +### B01 — AGENTS.md as the canonical repo guide `DONE` + +*Closed by the human merge of PR #5 (`ec82495`, 2026-08-16); plan reconciled with git on +2026-09-19, human-approved — the handoff entry had recorded the close, the plan had not.* **Layer: host binding + docs** (doc 07: the guide's filename is convention, not core — no RFC required; classification recorded in DECISIONS). `AGENTS.md` becomes the guide every @@ -261,3 +264,242 @@ named human decision (publish or not). Report `s08.md`; sprint closes with the publish blockers listed. **Acceptance:** report exists; blockers name each pending post. + +--- + +## Sprint 10 — Measurable intent: gap-closing planners and status skills `ACTIVE` (ratified by the human, 2026-09-19) + +Objective: a sprint's open decisions are closed with the human before each batch is written, +and progress is measurable at any time from the repository alone — engineered at read time +from the raw chain sprint → batch → handoff, never from a maintained list of requirements. +The plan's format does not change (human decision, 2026-09-19: formalized requirements must +be kept current while a feature is still being discovered, and that maintenance is what +drifts). Source: issue #8; field evidence mined from the maintainer's prompt history. + +Delivery: one branch (`feat/8-status-and-gap-closing-planners`), **one commit per batch**, one +PR carrying `Closes #8` and declaring both layers (core + new skill). Merging is the human act +and additionally waits on the RFC's "accepted" summary — work proceeds on the branch meanwhile +(blocked-but-not-idle). Outward acts of this sprint (Discussion, issue, branch push, PR) were +authorized in-session on 2026-09-19; in any later session they are gates again. + +### B01 — Field evidence and the RFC `DONE` + +**Layer: docs — the prerequisite the core layer demands** (RFC + recorded field evidence). +Write `docs/develop/reports/s10-field-evidence.md`: the two habits as the record shows them. +(a) Planner gap-closing: 16 launches, 10 with a hand-written instruction, 5 spelling out the +per-batch protocol; the 2026-08-16→17 incident (bare launch, five plan files, zero questions, +rollback, the agent's own "fixed without asking"); the two other failure shapes (questions +dumped up front as prose; sprint-level questions letting a batch gap surface after writing); +the 2026-09-01 reference run (ask → write → ask → write). (b) Three-axis status: three +requests, one session, produced from in-session context (two with zero file reads), the +agent's own "derived / estimated" statement, the accepted output shape. (c) A **"not +evidenced"** section: no three-axis status in a single repo, no cold-start status ever, no +recorded hallucination incident — that concern is prospective and is stated as such. +Quotes in English marked as translated, the Spanish original in italics only for the four or +five load-bearing ones, product anonymized, pointer = date + prompt index in the local history. +Then: push the branch, open the RFC as a Discussion in **Ideas** titled `[RFC] …` following the +five template headings and linking the evidence by commit permalink; comment on #8 with the +link. `docs/community/rfc-process.md` gains the interim rule (until an RFC category exists, +RFCs go to Ideas with the `[RFC]` prefix). + +**Acceptance:** the evidence file exists and every claim carries its pointer; the "not +evidenced" section exists; product-name sweep (protocol §3 patterns) over the file returns +zero; `bash scripts/validate.sh` passes (links resolve); the Discussion is live, in Ideas, +`[RFC]`-prefixed, five headings present, permalink resolving; #8 shows the linking comment; +rfc-process.md states the interim rule. Skill checks: n/a — no skill touched. + +### B02 — Planners close gaps per batch, before writing `DONE` (depends: B01) + +**Layer: core methodology** (the RFC of B01; the PR's merge waits on its acceptance). +One new section in `skills/cdev-planner/SKILL.md` — the rule's **single home** — placed in +Mode 1 between placing the work and writing it: + +- The batch grouping is shown to the human first. +- Then, for each batch in order and **before writing it**: the decisions the batch would + otherwise fix on its own are put as questions, each with suggested answers and one marked + recommended. Ask → record the answers → write that batch → next batch. A batch that raises + no gap asks nothing. Permissions and tool connections the batch will need are gap sources. +- What counts as a gap is the planner's judgment — no written threshold (human decision, + 2026-09-19) — held conservatively: assume almost nothing; never ask what repository evidence + already settles. What it judges not worth a question is still recorded as a dated assumption. +- A question closes something undecided. The human's prompt is the statement of intent: the + planner interprets it and never hands it back for confirmation. +- Sprint-level decisions may be asked once up front; they never replace the per-batch rounds. + Never one questionnaire for every batch, never a question about a batch already written. +- A free-text answer is an answer. Answers land in `DECISIONS.md`, dated, per batch. +- **No human present** (the planner invoked from an unattended loop): a batch with open gaps + is written `BLOCKED`, each gap naming the minimum human decision and the suggested answer. + Never `READY`, never carried forward on the recommendation. +- Host binding, stated as such: where the host offers a structured question tool it is used; + otherwise numbered questions with lettered options, one batch per message. + +`skills/cdev-monorepo-planner/SKILL.md` does **not** restate the rule: it points at that +section by path (resolved to the real path, the way `cdev` reaches `profiles/`), applies it per +SYSTEM_BATCH, and lists only its own gap sources — repo participation, cross-repo contract +terms, the sync-point artifact, implementation/deploy order, verification level. The two +execution loops' planner invocations are re-read for contradiction with the `BLOCKED` rule +(field rule 5). Protocol §4 gains the local line: while no workspace fixture exists, a recorded +field exercise by the human stands in for the sandbox exercise of a monorepo skill, and the +sandbox check is recorded `not-run`. `CHANGELOG.md` gains the behavior bullet. + +**Acceptance:** (1) *Attended sandbox, `cdev-planner`:* conditioned fixture, an objective +spanning at least three batches of which one raises no gap, a driver answering as the human. +The recorded timeline shows the grouping first; for every gapped batch its questions — each +with two or more suggested answers and one recommended — **precede** that batch's write in +`SPRINTS.md`; the gap-free batch is written unasked; nothing reaches `SPRINTS.md` before the +first answer; `DECISIONS.md` holds the dated answers. (2) *Unattended variant:* same fixture, +no human — gapped batches are `BLOCKED` with decision + suggested answer, none `READY`. +(3) *Baseline:* the attended scenario run once against `main`'s planner, the difference +recorded. (4) The rule's text appears once: `grep` finds it in `cdev-planner` only, and a path +pointer in `cdev-monorepo-planner`. (5) Protocol checks 1–3 pass. `cdev-monorepo-planner`: +sandbox `not-run` (declared, no fixture) — its evidence is the human field exercise of B06. + +### B03 — `cdev-status`: progress on three axes, engineered at read time `DONE` + +**Layer: new skill / capability** — read-only, does not alter the loop, so no RFC; the +required record is the dated DECISIONS entry (2026-09-19). New `skills/cdev-status/SKILL.md`: + +- Requires a conditioned repo; otherwise proposes `bootstrap` and stops. +- Scope: the `ACTIVE` sprint by default; an argument names another sprint, or `all` for a + sprint-by-sprint rollup of the project. +- Reads the raw chain, in order: repo guide → `SPRINTS.md` (the sprint's objective and every + batch's text and state) → `DECISIONS.md` → the `AGENT_PROGRESS.md` entries of that sprint's + batches → `git` log and status → whatever files the sprint or its batches reference + (contracts, reports, a testing document where one exists). Where a later record changes an + earlier decision, the newest wins and is the one cited. +- Engineers the three axes **at read time**, in this order: functional requirements (what the + sprint's objective and batches commit the system to do) → non-functional requirements (the + qualities and constraints they commit to) → user stories, built over the first two against + the sprint's objective, first person, marked new or enriched. Every item cites where it + came from. Nothing is written back: the plan holds no requirement list to maintain. +- State per item: met · partial, with an **estimated** percentage, the reason and the owning + batch · pending, with the owning batch. Each axis carries an estimated percentage over the + sprint's total; a method note says the items are derived and the numbers are estimates. +- Output, the shape accepted in the field: title → method note → §1 functional requirements + (`State | Requirement`, heading with the percentage and batches X of N) → §2 non-functional + requirements (same table) → §3 user stories grouped complete / partial / empty → executive + reading (batches closed, the three percentages, where the remaining work converges, live + risks: blocked batches and pending human decisions) → what is left to reach 100%. +- `since `: reads the plan and the handoff at that point of the git history, + applies the same item list to both states, shows "(before NN%)" and marks what changed. No + argument, no delta. Nothing is persisted. +- An axis the repository does not support reads **"not derivable"** and names what is missing. + It is never filled from general knowledge. +- Disagreement between plan, handoff and git is flagged, never resolved (a `DONE` whose entry + records a `not-run` check reads "met, unverified"). +- Read-only, always: it edits no file and marks no state. Something the conversation surfaces + that belongs in the plan is the planner's job, not this skill's. No isolation machinery — + status is a read operation inside the conversation; CDev is a procedure and does not guard + the human against their own use of context (human decision, 2026-09-19). +- Answers in the language the human is using. + +`CHANGELOG.md` gains the bullet. + +**Acceptance:** (1) *Cold-start sandbox:* a conditioned fixture whose active sprint has at +least four batches in mixed states (`DONE` with handoff evidence, `DONE` with a `not-run` +check, `IN_PROGRESS`, `READY`, one `BLOCKED`) and one DECISIONS entry that changes a planned +decision; a **fresh subagent with no planning context** runs the skill. Its answer has the +three axes in the stated order; every item cites a path that exists; partials carry +percentage + reason + owning batch; the changed decision appears in its newest form citing +DECISIONS; the `not-run` item reads unverified; the executive reading is present; and +`git status` in the fixture is clean afterwards. (2) *`since`:* with a batch closed between +two fixture commits, the delta appears and the changed item is marked; without the argument +there is none. (3) *Not derivable:* a sprint carrying no non-functional signal yields that +axis as "not derivable" naming what is missing — no invented item. (4) Unconditioned repo → +proposes `bootstrap`, stops. (5) Protocol checks 1–3 pass; `claude plugin validate .` passes; +the skill lists as `cdev:cdev-status`. + +### B04 — `cdev-monorepo-status`: the same three axes for a SYSTEM sprint `DONE` (depends: B03) + +**Layer: new skill / capability** (same record as B03). New +`skills/cdev-monorepo-status/SKILL.md`. It does **not** restate the three-axis method or the +output shape: it points at `cdev-status` by path (resolved to the real path) and adds only +what is system-level: + +- Requires a conditioned workspace (`workspace/repos.yaml` + a global `docs/develop/`); + otherwise proposes `bootstrap-monorepo` and stops. +- Scope: the `ACTIVE` SYSTEM sprint of the global `SPRINTS.md`; an argument names another. +- Sources, beyond those of `cdev-status`: the SYSTEM_BATCHes and their references, the + contracts under `workspace/contracts/`, and — **local truth** — each affected repository's + own `SPRINTS.md` and `AGENT_PROGRESS.md`, reached through the bidirectional references and + read in the repository itself. Workspace↔repository divergence is flagged and the + repository's state is the one reported. The state snapshot file never decides anything. +- Output: the three axes at system level, then one compact table — repository · its local + batches for this SYSTEM sprint · state · blockers. +- A repository that cannot be reached reads "not derivable" for that repository, by name. +- Read-only, as B03. + +`CHANGELOG.md` gains the bullet. + +**Acceptance:** protocol checks 1–3 pass; `claude plugin validate .` passes; the skill lists +as `cdev:cdev-monorepo-status`; `grep` finds the three-axis method stated in `cdev-status` +only, and a path pointer here. Sandbox: `not-run` (declared — no workspace fixture); its +evidence is the human field exercise of B06. + +### B05 — Live docs and version 0.2.0 `DONE` (depends: B02, B03, B04) + +**Layer: periphery / docs.** The surfaces that name the skill set learn there are nine: +`README.md` (command table and "which command when"), `docs/08-installation.md` (command +table), `CONTRIBUTING.md` ("the seven" → "the nine"), and `docs/09` / `docs/10` where they list +commands. Documents 01–07 are the extraction record and stay untouched; the walkthrough is not +extended (every command in it must be replayed — not worth it for a read operation). In the +**same commit**: `.claude-plugin/plugin.json` → `0.2.0` (semver per CONTRIBUTING: compatible +capabilities) and `CHANGELOG.md` gathers this sprint's bullets under `## 0.2.0`. Tag, GitHub +Release and the marketplace pin happen **after the merge, from `main`**, and are the human's — +commands left ready per the maintainer's release checklist (annotated tag, explicit push). + +**Acceptance:** `grep -rn -iE '\bseven\b|7 skills'` over the live surfaces returns nothing +stale; both new commands appear in README and doc 08; `plugin.json` version and the CHANGELOG +heading agree; `bash scripts/validate.sh` and `claude plugin validate .` pass; the release +commands exist, unexecuted, in the handoff entry. + +### B06 — Human field exercise of the monorepo skills `BLOCKED` (depends: B02, B04) + +*Blocked 2026-09-19 — the script exists (`docs/develop/reports/s10-field-exercise.md`). +2026-09-20: at the human's request the agent ran it on local clones of the real workspace +(never the real trees) — observations A1–A3, A5, A6, A8 and B1–B6, B8 held; A7 did not occur; +two defects found and fixed (handoff entry). **Minimum human decision, now much smaller:** +read the status that run produced and say (B7) whether every requirement and story in it is +one you recognise as yours, and (B9) whether it is the status you used to ask for by hand; +optionally run the planner once interactively to see the form tool (A4).* + +**Layer: field evidence** — stands in for the sandbox exercise no workspace fixture allows +(protocol §4, local line added in B02). The agent writes the script: how to load the branch +(`claude --plugin-dir `), what to run, what to observe. The **human** runs it, +once, in their own workspace; this repository's agent never touches those repositories. +(a) `cdev-monorepo-planner` on a **throwaway objective**: does it follow the pointer into +`cdev-planner`, show the grouping, ask per SYSTEM_BATCH before writing each, with suggested +answers and a recommendation? What it wrote is then discarded with git in the workspace and +the repositories — real plans receive nothing from an unmerged skill. (b) +`cdev-monorepo-status`, cold, on the real `ACTIVE` SYSTEM sprint (read-only): three axes in +order, items citing sources, the per-repository table, local truth over the workspace's view. +The human reports back; the outcome lands in the handoff as field evidence, product +anonymized. This batch is `BLOCKED` on the human from the moment the script exists — the loop +moves on to B07's preparable parts and does not wait idle. + +**Acceptance:** the script exists; the handoff entry records, per observation, what the human +saw (held / broke, quoted where it broke); any break is either fixed on the branch and +re-observed, or carried as a named blocker. The sprint does not close and the PR is not merged +without this entry. + +### B07 — Sprint verification, report and the pull request `BLOCKED` (depends: B01–B06) + +*Blocked 2026-09-19 — everything the agent can do is done: full protocol sequence green, +report written (`reports/s10.md`), draft PR #10 open against `main`. It cannot close before +its dependency B06. **Minimum human decisions:** (1) run the field exercise and report back +(B06); (2) write the "accepted" summary on the RFC, Discussion #9. Then: the agent records +the field entry, finishes the report's debt table, and the merge is the human's.* + +**Layer: docs.** Full protocol sequence over the final skill set (nine skills); sprint report +`docs/develop/reports/s10.md` — what was added, what was deliberately *not* built (the +requirement lists, the isolation machinery, the workspace fixture) and why, the verification +debt that remains (monorepo sandbox `not-run`, covered by field evidence). Pull request +against `main` from the template: What · Layer (**core**, linking the RFC, + **skill**) · +Evidence checklist · `Closes #8`. Merge by **merge commit**, not squash — the branch carries +one commit per batch by design, as PR #5 did. Opening the PR was authorized in-session on +2026-09-19; in a later session it is prepared, not executed. + +**Acceptance:** all protocol checks pass or are recorded `not-run` with their reason; the +report exists; the PR is open (or its body and command are ready, with the blocker named), +CI `validate` green on it. **Merging is the human's**, and waits on two things the PR body +names: the RFC's "accepted" summary and B06's field entry. diff --git a/docs/develop/reports/s10-field-evidence.md b/docs/develop/reports/s10-field-evidence.md new file mode 100644 index 0000000..90ae88d --- /dev/null +++ b/docs/develop/reports/s10-field-evidence.md @@ -0,0 +1,236 @@ +# Sprint 10 — field evidence + +The record behind issue #8 and its RFC: two habits the maintainer developed by hand over +three months of driving real work with CDev, mined on 2026-09-19. It is written the way the +method's own field reports are (docs 05–06): what the record shows, what it does not, and one +product, anonymized. + +## Sources and their limits + +- **Prompt history** — the local log of every prompt the maintainer typed, all projects, + 2026-06-06 → 2026-09-19 (1,139 prompts). The human's words only; no agent answers. Pointer: + `H#N` = line index in that log; times are local (UTC+2). +- **Surviving transcripts** — 16 full sessions, in three projects only. Everything else was + already gone: for any prompt before 2026-08-16, how the agent actually responded **cannot + be checked**. Pointer: `T:`; times are UTC. +- The log and the transcripts are local and private; they are not in this repository and the + pointers are for the maintainer's own re-verification. The load-bearing quotes below were + re-read against the source before this file was written. +- Quotes are **translated from Spanish**. The original is kept, in italics, only for the few + the argument rests on. Typos in the originals are the maintainer's and are left alone. + +--- + +## A. The planners, and an instruction typed by hand + +### What the record shows + +25 prompts mention a planner skill. Removing prompts that only discuss the skill, one slip +corrected within the minute, and merging a launch with its continuation and a re-send with its +original leaves **16 distinct planner launches**. Of those: + +- **10 carry a hand-written instruction to close gaps through questions.** +- **5 of the 10 spell out a per-batch, iterative protocol** — all five on the multi-repo + planner, all from 2026-08-11 onward. +- **6 carry no such line.** Two of those six produced a whole plan with zero questions; one of + them is the incident below. One produced two rounds of questions anyway — without the line, + whether the planner asks is not predictable. +- The same habit predates the planner skills: six earlier prompts attach "ask me the necessary + questions" to conditioning or sprint-analysis work (`H#264`, `H#265`, `H#540`, `H#750`, + `H#756`, `H#838`). + +On 2026-09-13 the maintainer launched a planner without the line (`H#1123`) and re-sent the +identical prompt six minutes later with one sentence appended (`H#1124`): "plan, then ask me +the questions to close gaps". The line is not decoration; its absence is corrected. + +### The instruction, in the maintainer's words + +> "What we are going to do now is plan each System batch, and during that planning, in each +> one, you are going to ask me how to decide the gaps that are left open — I repeat, for each +> batch." — `H#898`, 2026-08-11 +> +> *"…planificar cada System batch y durante esa planificacion en cada uno me vas a preguntar +> como decidir los gaps que se vayan quedando abiertos, repito, por cada batch."* + +> "…during the planning of each sprint, the gaps generated by each batch being planned are +> reviewed sequentially; those questions must be answered by me, with the suggested decisions, +> during the planning of the batch; iteratively, sprint by sprint, batch by batch (but if a +> batch generates no gap, nothing is asked — though it is almost impossible that every batch +> of a sprint generates no questions and decisions to take)." — `H#1010`, 2026-08-17 +> +> *"…se revisa de forma secuencial que gaps genera cada batch que se esta planificando, esas +> preguntas deben ser contestadas por mi con las desiciones sugeridas durante la planificacion +> del batch, de forma iterativa esto se hace sprint por sprint, batch por batch (pero sin un +> batch no genera gap no se pregunta…)"* + +> "As you well know, this process involves gap detection, suggestions and direct questioning +> with me. […] but assume almost nothing, be conservative […] After the grouping we will have, +> for each batch, several question steps for me to resolve. There we apply the iterative step +> of me answering you, to close each batch's gaps. And finally, everything clarified, we take +> this to our `docs/develop` structure." — `H#1038`, 2026-08-21 +> +> *"…no asumas casi nada, se conservador […] tendremos por cada batch varios pasos de +> preguntas a resolver por mi […] todo aclarado, pasamos a llevar esto a nuestra estructura"* + +> "Let's go batch by batch using your form feature, suggesting several answers for each +> question." — `H#1039`, 2026-08-21 +> +> *"vamos batch por batch usando tu funcionalidad de formulario, sugiriendome varias +> respuestas por cada pregunta"* + +> "During the creation of the two or three batches you are going to add, you will iterate +> between each batch, consulting me directly on each gap as it arises." — `H#1077`, 2026-09-01 + +Distilled — every element has a quote above: + +| Element | What is asked for | +|---|---| +| When | During the planning of each batch and **before it is written** ("everything clarified, *then* we take this to `docs/develop`") | +| Granularity | Sequential, batch by batch — not one questionnaire | +| Conditionality | A batch that raises no gap asks nothing | +| Content | Open decisions; suggested answers with each question; a conservative stance ("assume almost nothing"). One launch adds permissions and tool connections the work will need (`H#980`) | +| Form | The host's structured question form, several suggested answers per question | +| Stop | "Everything clarified"; the human then starts execution themselves | + +### The incident — 2026-08-16 → 17 (`T:aa662542`) + +1. A bare launch of the multi-repo planner, no instruction attached (`H#1008`). +2. The planner edited **five plan files in about twelve minutes, asking nothing**. Decisions + of its own went into the plan as settled — among them a security-relevant cookie setting, + written down as a "reasoned decision". +3. The human ratified the plan and execution began; the first batch was built. +4. Next day (`H#1010`): "there are certain things we got wrong. We will accept the current + changes, on the condition of going back for the moment and then returning to this point." + *("hay ciertas cosas con las que procedimos mal. Vamos a aceptar los cambios actuales, con + la condicion de retroceder por el momento…")* — followed by the per-batch parameter quoted + above. +5. On the interactive relaunch, the planner's **own questions named what it had assumed**: + "economic parameters I fixed without asking you" *("Parámetros económicos que fijé sin + preguntarte")*; "the plan assumed [an open application flow] without asking you"; "my + decision, without asking you" — about that cookie setting. + +The questions existed. They arrived after the plan was written and after a batch was built +on it. + +### Two further failure shapes + +- **Every question up front, as prose** (`T:b0a364f6`, 2026-08-21). Despite the gap-closing + line in the launch, the planner answered with one long message: a batch table plus a + numbered list of questions for all eight batches. Corrected by `H#1039` (above). Eight form + rounds followed, one per batch, and the plan was written only after the last answer. +- **Sprint-level questions instead of per-batch ones** (`T:b7334a46`, 2026-08-31). Two form + rounds of generic questions, then every batch written at once. Twelve minutes later the + human had to raise a batch-level gap themselves; two more questions and a re-edit of the + plan followed. No complaint in words — the cost was the rework. + +### The run that matches what is asked (`T:b7334a46`, 2026-09-01, after `H#1077`) + +Ask (4 questions) 15:01 → batch written 15:14 → ask (4) 15:15 → written 15:17 → ask (4) +15:18 → written 15:22. Asking and writing interleaved, batch by batch. Nowhere in the record +does the maintainer complain of being asked too much. + +--- + +## B. The three-axis status + +### What the record shows + +A long run of "where are we?" prompts narrows, over ten weeks, into one specific request: + +- 2026-06-12 — a coverage audit against an external requirements document (single repo). +- July — "what is left of this phase?", per phase; user stories appear as the unit of testing. +- 2026-08-03 — the first recap explicitly "according to `SPRINTS.md`" (single repo). +- 2026-08-13 — a per-batch summary "for each use case / user story changed". +- **2026-08-18 — the three axes, at once** (`T:aa662542`, multi-repo workspace): "Explain what + we have so far through the percentage of three things with respect to the sprint's total: + 1 — functional requirements; 2 — user stories (how far they get, and the ones still empty); + 3 — non-functional requirements." +- Repeated twice in the same session: "show me the current functional state the same way I + asked you before", and a day later as a named thing — "…then give me *status-funcional*". + +That is **three answered requests, in one session, over two days, on one system sprint.** +After it, surviving sessions show only generic "where did we leave off?" prompts. The habit is +real but young; the maintainer codified it retrospectively on 2026-09-19 (issue #8), adding an +order — user stories last, built over the other two — and a purpose: "this gives control over +how the sprint's objective is progressing". + +### The shape that was accepted + +Identical skeleton in all three answers; the second request ("the same way") is the acceptance +signal. No answer was ever corrected. + +- Title → a one-paragraph **method note**. +- §1 functional requirements: heading with an approximate percentage, the previous one in + parentheses, and "batches X of N"; a `State | Requirement` table — met / partial with a + percentage / pending, a marker on rows that changed, pending rows naming the batch that + will close them. +- §2 user stories: percentage and counts, then three groups — complete, partial, empty — each + story one first-person sentence; partials carry a percentage and a reason ("API only, no + panel — 50%"), empties carry their owning batch. No diagram: this grouping *was* the map. +- §3 non-functional requirements: the same table. +- An **executive reading**: batches closed, the three percentages, where the remaining work + converges, live risks (a deadline, pending human gates); in the last status, a numbered + "what is left to reach 100%". + +### How those answers were produced — the part that matters + +- Two of the three were produced with **zero file reads**. The third read files only to close + a batch. All three came from the context of the session that had planned the sprint, written + its contract and run its batches. +- The agent said so itself, in its method note: "the sprint has no formal user stories + written — I derive them from the document's objective and the contract's acceptance + checklist, and I declare it. The percentages are by item, with estimated partials — not an + exact science." *("el sprint no tiene historias de usuario formales escritas — las derivo + del objetivo del doc y del checklist beta del contrato, y lo declaro. Los % son por ítems + con parciales estimados, no ciencia exacta.")* +- The plans checked (one workspace, three single repositories) hold a free-text objective per + sprint and acceptance per batch. None holds a list of requirements or user stories. + +So the status worked, and was accepted, as **engineering done at read time over free-form +intent** — but only ever by a reader that already held the whole sprint in conversation. +Invariant 1 says the repository is the memory and the conversation holds nothing. A status +skill's job is to make that reading work from the repository alone. + +### A design the maintainer rejected, and why it is recorded here + +The planner's first draft for this sprint closed that gap from the other side: have the +planner write ID'd requirement and user-story lists into each sprint, with per-batch coverage, +so that status could be computed instead of derived. The maintainer rejected it on +2026-09-19: sprints and batches already carry the intent in free form; a formalized list must +be kept current while a feature is still being discovered, decisions change mid-implementation, +and that maintenance is what drifts. In doc 07's terms the list restates the plan (it fails +the singularity test, as the workspace's state snapshot does) where field rule 4 says derive +on read. The plan's format therefore does not change, and the RFC asks for nothing on it. + +--- + +## C. Not evidenced + +Stated so nobody reads more into this file than is there. + +- **No three-axis status was ever requested in a single repository.** `cdev-status` takes its + shape from the system-level one by extrapolation (clarity map: PARTIAL). +- **No cold-start status was ever produced** — by anyone, in any session. The central claim of + the status skills (it works from the repository alone) has no field evidence yet; Sprint 10's + sandbox exercise and the maintainer's field exercise are its first tests. +- **No hallucination or drift incident in a status answer is recorded.** The maintainer's + concern about it is prospective and is treated as such. (Adjacent, in code rather than in a + status: on 2026-06-13 an invented requirement was caught by tracing it back to the + specification's own item.) +- **No complaint about percentages being estimates.** They were declared as estimates and + accepted three times. +- For every planner launch before 2026-08-16 the human's instruction is on record but the + agent's behavior is not. +- The counts in §A come from one mining pass over a private log, by pattern and by reading; + they were spot-checked, not independently recounted. + +## D. What this supports + +- **A core rule for the planners** (the RFC): close each batch's open decisions with the + human — questions with suggested answers, batch by batch, before that batch is written; ask + nothing where there is no gap. One recorded incident with a rollback, two further failure + shapes with rework, one reference run, and an instruction the maintainer re-typed ten times + in sixteen launches because the skill did not carry it. +- **Two read-only status skills** (new capability, no RFC — the loop is untouched): the + three-axis reading that was accepted in the field, made to work from the raw chain + sprint → batch → handoff instead of from a conversation that will not be there. diff --git a/docs/develop/reports/s10-field-exercise.md b/docs/develop/reports/s10-field-exercise.md new file mode 100644 index 0000000..6b292e2 --- /dev/null +++ b/docs/develop/reports/s10-field-exercise.md @@ -0,0 +1,99 @@ +# Sprint 10 — field exercise of the multi-repo skills (script for the human) + +`scripts/sandbox.ps1` builds single repositories only, so the two multi-repo skills touched by +this sprint cannot be exercised in a fixture. Protocol §4 (local line, 2026-09-19): a recorded +field exercise by the human stands in. This is that exercise — one session, in your own +workspace. **This repository's agent never opens your workspace or its repositories**; it +wrote this script and will record what you report back. + +Nothing here needs the branch merged or the plugin reinstalled. + +## 0 · Load the branch, and prove it is the branch + +In this repository: `git checkout feat/8-status-and-gap-closing-planners`. +Then, from **your workspace's** root: + +``` +claude --plugin-dir C:\CodeWork\ideas\cdev +``` + +First prompt, before anything else: + +> Invoke the skill cdev:cdev-monorepo-planner and tell me two things only: the "Base directory +> for this skill" you were shown, and whether its text contains the phrase "Before writing each +> SYSTEM_BATCH". + +Expected: the base directory is under this repository (not the plugin cache) and the answer is +yes. Checked from this repository on 2026-09-19 — the working tree wins over the installed +0.1.1. **If yours says otherwise, stop**: the exercise would be testing the old skill. Report +that instead; it is a finding. + +## A · `cdev-monorepo-planner` on a throwaway objective + +Before starting, note the state so it can be discarded: in the workspace and in each +repository the objective could touch, `git status` must be clean (stash or commit what is +yours first). + +Launch it **bare** — no "ask me the questions" line. The point is whether the skill carries +what you have been typing by hand: + +> /cdev:cdev-monorepo-planner — plan a small SYSTEM sprint: add a "last seen" timestamp to the +> user's profile, stored by the backend and shown in the web app. + +(Any small invented objective touching two repositories works. Do not use real pending work: +an unmerged skill should not write your real plans.) + +Observe, and note for each **held / broke** (quote it where it broke): + +| # | What to watch | +|---|---| +| A1 | It read the single-repo planner's section (it should say so, or visibly read `cdev-planner/SKILL.md`) — the pointer was followed | +| A2 | The batch grouping was shown **before** any plan file was written | +| A3 | Questions came **per SYSTEM_BATCH**, before that batch was written — not one questionnaire up front, not after | +| A4 | Each question carried suggested answers, one marked recommended; it used the form tool | +| A5 | System-level decisions appeared among them: which repositories participate, contract terms, the sync-point artifact, order, verification level | +| A6 | It did not ask you to confirm what your prompt already said | +| A7 | A batch with nothing open was written without a question (may not occur — say so if it did not) | +| A8 | Your answers landed, dated, in the workspace's `DECISIONS.md` | + +Answer two or three rounds — enough to see the rhythm — then stop it. + +**Discard everything it wrote**, in the workspace and in every repository it touched: + +``` +git status # see what it wrote +git checkout -- . # tracked files back to HEAD +git clean -fd # new files it created (review the list `git clean -nd` prints first) +``` + +## B · `cdev-monorepo-status`, cold, on your real SYSTEM sprint + +Read-only — it runs on the real thing. **Use a fresh session** (same `claude --plugin-dir …` +command): a status produced by the session that planned or ran the sprint proves nothing about +reading the repository alone. + +> /cdev:cdev-monorepo-status + +Observe: + +| # | What to watch | +|---|---| +| B1 | It read `cdev-status/SKILL.md` for the method — the pointer was followed | +| B2 | Three axes, in order: functional → non-functional → user stories; every item names where it came from | +| B3 | The non-functional axis holds qualities of the *system*, not the repositories' working rules | +| B4 | One percentage per axis, declared an estimate; partial items carry a percentage, a reason and the owning batch | +| B5 | The per-repository table is there: repository · local batches for this SYSTEM sprint · state · blockers | +| B6 | Local truth: it opened each affected repository's own `SPRINTS.md` / `AGENT_PROGRESS.md`; any workspace↔repository divergence is flagged and the repository's state is the one reported; it did not take a state from the snapshot file | +| B7 | Where the repositories do not support something, it says "not derivable" and names what is missing — nothing filled in from thin air. **You are the only one who can judge this**: is there any requirement or story in it that you do not recognise as yours? | +| B8 | `git status` is clean afterwards in the workspace and in every repository — it wrote nothing | +| B9 | Is it the status you used to ask for by hand? What would you change? | + +Optional, if a batch closed recently: `/cdev:cdev-monorepo-status since ` — does +the "(before NN%)" delta match what you remember? + +## What to report back + +Per observation, **held** or **broke**, with the broken text quoted; plus B7 and B9 in your +own words. It goes into `docs/develop/AGENT_PROGRESS.md` as field evidence, product +anonymized. Anything that broke is either fixed on the branch and re-observed, or carried as a +named blocker. The sprint does not close and the pull request is not merged without this entry. diff --git a/docs/develop/reports/s10.md b/docs/develop/reports/s10.md new file mode 100644 index 0000000..5504bb9 --- /dev/null +++ b/docs/develop/reports/s10.md @@ -0,0 +1,94 @@ +# Sprint 10 — Measurable intent: gap-closing planners and status skills + +Report written 2026-09-19, updated 2026-09-20, with the sprint **not closed**: B01–B05 `DONE`, +B06 `BLOCKED` on two judgments only the human can make, B07 waiting on it. Issue #8 · RFC: Discussion #9 · branch +`feat/8-status-and-gap-closing-planners`, one commit per batch. + +## What was added + +| | What | Layer | Proof | +|---|---|---|---| +| B01 | Field evidence (`s10-field-evidence.md`) and the RFC (Discussion #9); interim rule in `rfc-process.md` (no RFC category → Ideas + `[RFC]`) | docs | Permalink and Discussion read back via the API | +| B02 | Planners close each batch's open decisions with the human before writing it. One home (`cdev-planner`); `cdev-monorepo-planner` points at it. No human → the batch is `BLOCKED`, never `READY` | **core** | Sandbox: attended (state captured at six stops: ask → write interleaved over five batches), unattended, and a baseline against `main`'s planner | +| B03 | `cdev-status` — functional / non-functional / user stories, engineered at read time from sprint → batch → handoff; read-only | new skill | Sandbox, cold, fresh subagents: cold start ×2, `since`, not-derivable, unconditioned repo | +| B04 | `cdev-monorepo-status` — the same reading for a SYSTEM sprint, by reference, plus local truth and a per-repository table | new skill | Static checks + live load; field-exercised 2026-09-20 on clones of a real workspace — see below | +| B05 | Nine skills on the live surfaces; version 0.2.0 | docs | `validate.sh` (`cdev@0.2.0`, 9 skills), `claude plugin validate .` | +| B06 | The field-exercise script for the multi-repo skills | field evidence | Run by the agent on clones, 2026-09-20, at the human's request; B7 and B9 remain the human's — `BLOCKED` | + +## What was deliberately not built, and why + +- **Requirement and user-story lists in the plan.** The planner's first draft had each sprint + carry ID'd requirements and stories with per-batch coverage, so status could be computed. + Rejected by the human: sprints and batches already hold the intent in free form, and a + formalized list must be kept current while a feature is still being discovered — that + maintenance is what drifts. In doc 07's terms it restates the plan (singularity) where field + rule 4 says derive on read. **The plan's format did not change**; neither did the execution + loop. The rigor went into the reader. +- **Isolation machinery for status** (running it in a fresh subagent so the conversation + cannot leak into it). Rejected by the human: status is a read operation inside the + conversation; CDev is a procedure and does not guard the human against their own use of + context. +- **A workspace (multi-repo) sandbox fixture.** Not built (clarity map: ABSENT). A recorded + field exercise by the human stands in — protocol §4, local line. +- **A written threshold for "what counts as a gap".** Left to the planner's judgment, held + conservatively. The cost showed up at once — see below. + +## What the exercises taught + +- **The baseline asked too.** `main`'s planner is not silent: it asked one round up front, then + wrote four batches in one go and reported five assumptions "the human has NOT seen". The + rule does not add questions so much as move them to where the decision is taken, and turn + unseen assumptions into asked ones. +- **Judgment varies between runs.** The attended planner asked what "the same URL" means; the + unattended one judged it non-blocking and wrote that batch `READY` with the question + recorded as open. The RFC's Cost section names exactly this. If field use shows decisions + still being swallowed, that is the next RFC. +- **`cdev-status` had three defects in its first text**, all found by running it, none by + reading it: working rules of the repo counted as non-functional requirements (4 of 8 rows); + an ambiguity about unverified items that one run resolved by giving every axis two figures; + statuses of ~1,100 words. Fixed and re-exercised; the brevity fix only partly worked. +- **The not-derivable clause took four attempts**, and the fault was mine three times: two + fixtures that carried the very signal the clause assumed absent, and one whose commit + message announced the answer to the agent under test. In none of the four did the skill + invent a requirement — not even input sanitising, for an HTML import feature. +- **Both hand-made fixtures contained a `DONE` batch with no work behind it** — unplanted. + Every planner run stopped to report it before planning; every status run flagged the + plan↔handoff↔git disagreement and resolved nothing. The rules held on flaws nobody staged. + +## What the field exercise taught (2026-09-20, run by the agent on clones of a real workspace) + +- **Both multi-repo skills have now been seen running**, on real data: the planner asked per + SYSTEM_BATCH before writing, followed the pointer, raised system-level and permission + decisions, and pushed back on an answer that collided with a repository's local protocol; + the status led with local truth — the workspace plan said 3 of 8 closed, the repositories 7 + of 8. +- **A status can cost as much as a batch.** The first run fanned out to three subagents and + died on the usage limit at ~8 USD with nothing delivered. "Read narrowly" brought it to + ~4 USD and 5.5 minutes — and then over-corrected: the status stopped opening contracts, + decisions and local handoffs, and said so in its own method note. Fixed to "slices, never + fewer sources"; that last wording is proven on a fixture only. +- **The honesty of the method note is what caught the over-correction.** A status that names + what it did not read can be audited; one that does not cannot. + +## Verification debt that remains + +| Debt | Why | What closes it | +|---|---|---| +| `cdev-monorepo-planner` — sandbox `not-run` | No workspace fixture | Field-exercised 2026-09-20 on clones (A1–A3, A5, A6, A8 held); the form tool (A4) unobserved | +| `cdev-monorepo-status` — sandbox `not-run` | Same | Field-exercised 2026-09-20 on clones (B1–B6, B8 held); **B7 and B9 are the human's**; the final "read narrowly" wording unexercised on a real workspace | +| The central claim of both status skills — that the reading works on a *real* sprint from the repository alone — now rests on **one** real-workspace status (system level); for a single real repository there is still none | The evidence file's §C: no cold-start status had ever been produced before this sprint | Observation B7, which only the human can make; first real single-repo use | +| Pre-existing, recorded not fixed: the multi-repo skills were never sandbox-exercised in this repo; S01-B04 closed `DONE` with sandbox `not-run` over skill changes | Found while planning (DECISIONS 2026-09-19) | Out of scope; B06 is the first proof any of them will have | + +## Contract delta for consumers (installed copies, from 0.2.0) + +- Planner runs with a human present now **ask before each batch**. A launch that used to + produce a plan in one pass will stop for answers. +- An unattended loop that invokes a planner can now find `BLOCKED` batches where it used to + find `READY` ones. +- Two new commands; nothing removed, no plan format change, no template change — + repositories conditioned under 0.1.x need no re-conditioning. + +## What the merge waits on + +1. The maintainer's "accepted" summary on the RFC (Discussion #9). +2. B06's closure: the field entry exists (2026-09-20); what is missing is the human's B7 and B9. diff --git a/skills/cdev-monorepo-planner/SKILL.md b/skills/cdev-monorepo-planner/SKILL.md index ec2e101..a92b22d 100644 --- a/skills/cdev-monorepo-planner/SKILL.md +++ b/skills/cdev-monorepo-planner/SKILL.md @@ -10,6 +10,14 @@ asked; without a clear argument, run both: gap analysis first, then materialize ## Mode 1 — Materialize an objective (objective → executable SYSTEM_BATCH) +**Before writing each SYSTEM_BATCH, close its open decisions with the human.** The rule lives +in one place — § "Closing open decisions" of the `cdev-planner` skill: resolve this skill's +base directory to its real path, read `../cdev-planner/SKILL.md`, and apply that section per +SYSTEM_BATCH (including its no-human branch). System-level sources of open decisions, beyond +that section's: which repos participate and which explicitly do not, the terms of a +cross-repo contract, the sync-point artifact, implementation and deploy order, the +verification level. + 1. **Define the batch**: `SYS--B` in the global `SPRINTS.md` with an observable objective, affected repos (and explicitly the non-affected ones if that clarifies scope), global acceptance and verification level L0–L3. It is born `PLANNED`. @@ -37,7 +45,8 @@ asked; without a clear argument, run both: gap analysis first, then materialize **goes looking for** that file (pull, not notification) and waits/rotates if it does not exist — that is how integration happens without mocking the other repo's contract. Without a declared sync point, a cross-repo dependency is not planned. -7. **Promote to `READY`** only when every required reference exists, respects the local +7. **Promote to `READY`** only when the batch's open decisions are closed, every required + reference exists, respects the local sequence, has sufficient acceptance and its sync points declared. Two independent numberings: SYSTEM Sprint/Batch ≠ local sprint/batch. Never equate them, never diff --git a/skills/cdev-monorepo-status/SKILL.md b/skills/cdev-monorepo-status/SKILL.md new file mode 100644 index 0000000..969b145 --- /dev/null +++ b/skills/cdev-monorepo-status/SKILL.md @@ -0,0 +1,55 @@ +--- +name: cdev-monorepo-status +description: Use when the user asks where a CDev Monorepo workspace stands — progress of the active SYSTEM sprint (or a named one) across its repositories, measured on three axes, functional requirements, non-functional requirements and user stories — after a wave of SYSTEM_BATCHes has run, before deciding what to run next, or when coming back to the workspace. Also when the user invokes /cdev-monorepo-status or asks "status of the system sprint", "where is the monorepo", "status funcional del monorepo", "por dónde va el sistema". +--- + +# CDev Monorepo Status + +A read-only reading of a conditioned **workspace**: how far a SYSTEM sprint's intent has been +walked across its repositories. **It edits no file and marks no state** — not in the workspace, +not in any repository. + +Requires a conditioned workspace (`workspace/repos.yaml` and a global `docs/develop/`). Not +conditioned → propose the `bootstrap-monorepo` skill and stop. + +**The method is not restated here.** The three axes, how each item is engineered at read +time, the states, the estimated percentages, the report's shape, the `since` delta and the +rules live in one place — the `cdev-status` skill: resolve this skill's base directory to its +real path, read `../cdev-status/SKILL.md`, and apply it to the SYSTEM sprint. What follows is +only what the system level adds. + +## Scope + +The `ACTIVE` SYSTEM sprint of the global `SPRINTS.md`; an argument names another, `all` rolls +up every SYSTEM sprint. Two independent numberings: a SYSTEM sprint is never a local one. + +## Sources, beyond those of `cdev-status` + +- The SYSTEM_BATCHes of the sprint and their references (repo / local sprint / local batch / + required / depends_on), and their declared sync points. +- The cross-repo contracts under `workspace/contracts/` — acceptance written there is a + first-class source of requirements. +- **Local truth.** For every affected repository, its own `SPRINTS.md` and + `AGENT_PROGRESS.md`, reached through the bidirectional references and read **in the + repository itself**. Where the workspace and a repository disagree about a state, flag the + divergence and report the repository's. The workspace's state snapshot file is a photograph + and decides nothing: never read a state from it. +- **Read narrowly, here above all — slices, never fewer sources.** A reference names the local + sprint and the local batch: read that batch **and its handoff entries** in the repository — + not the repository's whole plan or log, and nothing of a repository the SYSTEM sprint does + not reference. The sprint's contracts and the decisions about it are still read: "met" + rests on a handoff entry, and a contract's acceptance is a requirement. One pass, one + reader. + +## What the report adds + +After the three axes and before the executive reading, one compact table: + +`Repository | Local batches for this SYSTEM sprint | State | Blockers` + +A repository that cannot be reached reads **"not derivable"** for that repository, by name — +the system-level axes then say which of their items rest on it. + +The executive reading also carries the system-level risks: SYSTEM_BATCHes `BLOCKED` on a human +decision, sync points whose artifact does not exist yet, system verification recorded +`not-run` over references that read done. diff --git a/skills/cdev-planner/SKILL.md b/skills/cdev-planner/SKILL.md index 485ccb7..e0b0436 100644 --- a/skills/cdev-planner/SKILL.md +++ b/skills/cdev-planner/SKILL.md @@ -19,7 +19,9 @@ clarity map). Not conditioned → propose the right bootstrap skill and stop; do flag and reconcile before planning on top — a plan built over a drifted state is poisoned. 2. **Locate the objective in the clarity map** (`PRODUCT.md`): - **DEFINED** → plan it fully; - - **PARTIAL** → plan the clear part; record every assumption, dated, in `DECISIONS.md`; + - **PARTIAL** → plan the clear part; with a human present the unclear part becomes + questions (§ Closing open decisions); every assumption still made is recorded, dated, in + `DECISIONS.md`; - **ABSENT** → do not plan it. Write the open question instead. Inventing an ABSENT area is forbidden. 3. **Place work respecting the local order**: @@ -28,16 +30,51 @@ clarity map). Not conditioned → propose the right bootstrap skill and stop; do - belongs to a later phase → next `PENDING` sprint, or a new sprint drafted as `PROPOSAL` (a human ratifies; the planner never activates it). Never a second ACTIVE sprint, never renumber. -4. **Write each batch executable as-is**: acceptance criteria observable and written before the +4. **Close the batch's open decisions before writing it** — § Closing open decisions. This + step and the next run per batch, interleaved: ask → write → next batch. +5. **Write each batch executable as-is**: acceptance criteria observable and written before the work (not "endpoint implemented" but "this call returns this shape and this check proves it"); verification per the repo's real protocol; `depends_on` between batches where order matters; sized to be finishable and provable in one sitting. -5. **Declare gates**: any step whose blast radius exceeds the working branch (schema on a +6. **Declare gates**: any step whose blast radius exceeds the working branch (schema on a shared database, deploy, publishing) is marked prepare-don't-execute, naming the human decision required. -6. **Promote to `READY`** only when acceptance is observable, dependencies exist, and the plan - still satisfies the invariants (exactly one ACTIVE sprint, no unresolved placeholders). -7. **Record planning decisions**, dated, in `DECISIONS.md`. +7. **Promote to `READY`** only when the batch's open decisions are closed, acceptance is + observable, dependencies exist, and the plan still satisfies the invariants (exactly one + ACTIVE sprint, no unresolved placeholders). +8. **Record planning decisions**, dated, in `DECISIONS.md`. + +## Closing open decisions (before each batch is written) + +What operators call "closing gaps": the decisions a batch would otherwise fix on its own. Not +Mode 2's gap analysis, which looks for missing work in the repo. **This section is the rule's +single home**; `cdev-monorepo-planner` applies it by reference. + +**With a human present:** + +1. Show the batch grouping first — titles, one line each — before any batch is written. +2. Then batch by batch, in plan order: put that batch's open decisions as questions, each with + two or more suggested answers and one marked recommended. Record the answers, **write that + batch**, move to the next. Ask → write → ask → write. +3. A batch that raises no open decision asks nothing. +4. What counts as an open decision is your judgment — there is no written threshold. Hold it + conservatively: assume almost nothing, and never ask what the repository's evidence already + settles. The permissions and tool connections a batch will need are open decisions too. + What you judge not worth a question is still recorded as a dated assumption. +5. A question closes something undecided. The human's prompt is the statement of intent: + interpret it; never hand it back for confirmation. +6. Decisions that belong to the whole sprint may be asked once, up front. They never replace + the per-batch rounds. +7. A free-text answer is an answer. Answers go to `DECISIONS.md`, dated, per batch. + +Never one questionnaire covering every batch. Never a question about a batch already written. + +**With no human present** (invoked from an unattended loop): a batch with open decisions is +written `BLOCKED`, each one naming the minimum human decision and your suggested answer. Never +`READY`; never carried forward on the recommendation. + +*Host binding:* where the host offers a structured question tool, use it. Otherwise, numbered +questions with lettered options, one batch per message. ## Mode 2 — Gap analysis (find what to do, and what is silently missing) diff --git a/skills/cdev-status/SKILL.md b/skills/cdev-status/SKILL.md new file mode 100644 index 0000000..71f2c29 --- /dev/null +++ b/skills/cdev-status/SKILL.md @@ -0,0 +1,114 @@ +--- +name: cdev-status +description: Use when the user asks where a CDev-conditioned repository stands — progress of the active sprint (or a named one) measured on three axes, functional requirements, non-functional requirements and user stories — after several batches have run, before deciding what to run next, or when coming back to a repo. Also when the user invokes /cdev-status or asks "status of the sprint", "where are we", "how far along is this", "status funcional", "por dónde vamos", "qué llevamos del sprint". +--- + +# CDev Status + +A read-only reading of **one** conditioned repository: how far the sprint's intent has been +walked, on three axes. **It edits no file and marks no state.** The single-repo counterpart of +`cdev-monorepo-status`, which applies this skill's method by reference — this file is the +method's single home. + +Requires a conditioned repo (`docs/develop/` with `SPRINTS.md`, `AGENT_PROGRESS.md`, protocol). +Not conditioned → propose the `bootstrap` skill and stop; do not improvise a status. + +## The idea + +The plan holds no list of requirements or user stories, on purpose: a formalized list has to be +kept current while a feature is still being discovered, and that maintenance is what drifts. +The intent lives in free form — the sprint's objective, each batch's text and acceptance, the +decisions, the handoff. This skill engineers the three axes **at read time** from that raw +chain, and says where each item came from. + +## Scope + +- **No argument** → the `ACTIVE` sprint. None `ACTIVE` → say so, and read the most recently + closed one. +- **A sprint named** → that sprint. +- **`all`** → one line per sprint (state, batches closed of N, the three percentages); full + detail only for the `ACTIVE` one. +- **`since `** → adds the delta (§ Delta). + +## Read, in this order + +1. Repo guide → local protocol (what "verified" means here). +2. `SPRINTS.md` — the sprint's objective; every batch: text, acceptance, state, dependencies. +3. `DECISIONS.md` — the entries about this sprint. +4. `AGENT_PROGRESS.md` — the entries of this sprint's batches: what was done, verification per + check, blockers. +5. `git log` and `git status` — the commits carrying the sprint's units; work the plan does not + know about. +6. Whatever the sprint or its batches reference — contracts, reports, a testing document where + one exists. + +Where a later record changes an earlier decision, the newest wins and is the one cited. + +**Read narrowly — slices, never fewer sources.** Plans and handoff logs grow for months: +locate the sprint in scope and read that sprint, the decisions about it and the handoff +entries of its batches — not the whole files. Every source in the list above is still read; +what shrinks is how much of each. The reading is one pass by one reader, and its cost should +not grow with the age of the repository. Whatever you did not open, name in the method note. + +## Engineer the three axes, in this order + +1. **Functional requirements** — what the sprint's objective and its batches commit the system + to *do*. One line each, in the plan's own terms. +2. **Non-functional requirements** — the qualities and constraints they commit the *system* + to, wherever the plan, the decisions or the referenced documents state them. The + repository's working rules — its verification sequence, branch convention, gates — are not + requirements of the system: they tell you what "verified" means, they are never items. +3. **User stories** — built last, over the first two, against the sprint's objective. First + person ("As a …, I …"), each marked **new** or **enriched** (a capability that already + existed and this sprint extends). + +Every item cites its source: the sprint objective, a batch, a dated decision, a handoff entry, +a file path. + +State per item: + +- **met** — every batch carrying it is `DONE` and its handoff entry records the verification; +- **met, unverified** — the batches are `DONE` but a check that covers it is recorded `not-run`; +- **partial** — an estimated percentage, the reason, and the batch that owns the rest; +- **pending** — the owning batch. + +Percentages are **estimates**: **one figure per axis** over the sprint's total, one per partial +item. "Met, unverified" items count toward the axis figure; the executive reading says how much +of it rests on them. Say in the method note that the numbers are estimates; never present them +as measured, never give an axis two figures. + +## Report + +1. **Title** — sprint, date, batches closed X of N. +2. **Method note** — one paragraph: the items were derived at read time from the files read + (name them); the percentages are estimates. +3. **§1 Functional requirements — ~NN%** — table `State | Requirement | Source`. +4. **§2 Non-functional requirements — ~NN%** — same table. +5. **§3 User stories — ~NN% · N complete · N partial · N empty** — three groups. Complete: the + story and what proves it. Partial: percentage and reason. Empty: the owning batch. +6. **Executive reading** — batches closed, the three percentages, where the remaining work + converges, live risks: blocked batches and the human decisions they wait on, verification + recorded `not-run`. +7. **What is left to reach 100%** — numbered, by owning batch. + +Keep it a reading, not an audit: one line per item, the executive reading in a handful of +lines. A disagreement is flagged once, where it bites, not re-argued in every section. + +### Delta + +With `since`, read `SPRINTS.md` and `AGENT_PROGRESS.md` as they were at that point +(`git show :`; a batch resolves to the commit that closed it — a bare batch id +means the sprint in scope — and a date to the last commit before it). Apply the **same item +list** to both states, show "(before NN%)" beside each percentage and mark the items whose +state changed. No argument, no delta. Nothing is persisted between runs. + +## Rules + +- **Read-only, always.** If the conversation surfaces something that belongs in the plan, + say it is the planner's job; do not write it. +- An axis the repository does not support reads **"not derivable"** and names what is + missing. Never fill it from general knowledge of what such a product usually needs. +- Disagreement between plan, handoff and git is **flagged, never resolved**: a `DONE` whose + entry records a check `not-run` reads "met, unverified"; commits belonging to no batch are + listed as work the plan does not know. +- Answer in the language the human is using.