@rasensio/aidlc-content 1.32.0 → 1.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/00-overview.md

@@ -197,6 +197,11 @@ With no interactive terminal, write the file, say where it is, and end the turn.
 
 When the user shares an idea tangential to the current work, offer to record it in `.aidlc/roadmap/inbox/` (see **aidlc-roadmap**) and continue the current phase — do not derail into ideation. Capture touches no instance state, so it is safe at any point in any phase.
 
+Safe for the instance is not the same as free for the person, so two rules bind every item an instance writes, exactly as they bind the capture flow:
+
+- **Merge first.** If an open item already owns the area, append a dated `## Received from <instance>` section to that item instead of writing a new one.
+- **No item enters `inbox/` without its six-line executive summary** (the labels are in **aidlc-roadmap**). Write it from what you know; `Not yet decided.` is a valid value for any label, an absent section is not. An item nobody can triage from the top of the file is not a captured idea, it is a decision deferred onto somebody else.
+
 ## Amendments — changing a completed phase's artifact
 
 A completed phase's artifact is changed **only through an amendment**, never edited in

package/skills/04-roadmap.md

@@ -35,7 +35,15 @@ Projects have more than one person proposing work, with mixed technical depth, s
 
 **The directory an item sits in is its status.** There is no `status` field, and you must never add one — two representations of one fact drift apart, and a wrong status is indistinguishable from a right one. Changing status means moving the file.
 
-`hold/` holds both parked and declined items. That conflation is deliberate; `history` and the git log distinguish them when anyone asks.
+`hold/` holds both parked and declined items, and **the history entry says which**. One directory is deliberate — a sixth status would have to be threaded through every count, every move and every projection — but "not now" and "not ever" are different decisions, and until the reason was written down they were indistinguishable on disk. So every move into `hold/` carries a reason, prefixed `parked — ` or `declined — `:
+
+```yaml
+history:
+  - { status: backlog, at: 2026-09-22 }
+  - { status: hold, at: 2026-09-23, reason: "parked — gated on the accounts table" }
+```
+
+The consequence worth stating: **agreed work waiting on a trigger belongs in `hold/`, parked, not in `backlog/`.** `backlog/` means "could start now", and an item gated on something that does not exist yet sitting there makes every count of what is ready wrong. Parking it is not dropping it, and the reason is what proves that.
 
 ## Item Format
 
@@ -59,7 +67,7 @@ history:
 - **`id`** is assigned once and never recomputed. Renaming the file or moving it between statuses leaves it unchanged. The `item-` prefix keeps it textually distinct from the filename so nothing derives one from the other.
 - **`source`** records how the item was written: `human` directly, `agent` drafted by an AI agent from someone's description, `import` migrated from an older format.
 - **`depends_on`** names other items by `id`, so a dependency survives its target moving. Build order is derived from this graph when needed — there is no global `order` field, because concurrent capture from independent sessions cannot coordinate a sequence.
-- **`history`** is append-only and advisory. Append `{ status, at }` when you move an item. An absent or incomplete history is never an error, and current status always comes from the directory — never from the last history entry.
+- **`history`** is append-only and advisory. Append `{ status, at }` when you move an item. An absent or incomplete history is never an error, and current status always comes from the directory — never from the last history entry. An entry may carry a third key, `reason`, and a move into `hold/` must; always write it **inside double quotes**, because the entry is a flow mapping and a reason containing a comma or a colon ends it early and takes the whole item's frontmatter with it.
 
 Bodies are otherwise free-form. Items authored through the portable skill carry four further headings — Problem, Who it's for, What success looks like, Out of scope — which is a useful shape, not a validated one.
 
@@ -104,6 +112,8 @@ The first section of the body, before anything else, is `## Executive Summary`
 
 This exists so a triage decision can be made from the top of the file. An item whose value cannot be stated in six lines is an item nobody can decide about, and it will sit in `inbox/` until somebody re-derives the case from scratch.
 
+**The rule binds every path that writes into `inbox/`, not just this skill's capture flow.** That includes an item written by an instance mid-phase, one drafted from a conversation that never touched capture, and one you write by hand. It was already the rule here and it was already followed here; what went wrong is that the other paths were never told. On 2026-09-23, 13 of the 18 items in one project's inbox had no summary — every one of them written by an instance, none of them triageable without re-deriving the case first. `Not yet decided.` is a valid value for any label; an absent section is not a valid item. `aidlc doctor` reports `inbox/` items missing one, by name and by missing label; it never writes one, because an invented case reads exactly like a real one.
+
 Four rules keep it honest:
 
 - **`None` is a real answer for revenue, and often the correct one.** Lifecycle plumbing earns nothing directly. Writing `Indirect` for everything makes the field useless, which is worse than leaving it blank because it reads as answered. This is also the cheapest available check against the self-repair trap: a meta-feature that has to write `Revenue — None` and `Customer value — none, it observes the lifecycle` has declared itself.
@@ -118,9 +128,10 @@ Older items may predate this section. Add it when you next touch such an item
 1. **Resolve the roadmap root.** Always write to the **primary checkout's** `.aidlc/roadmap/`, never a worktree's copy: resolve via `git rev-parse --git-common-dir` (the directory containing that path is the primary checkout). Outside a git repo, use the current project root. Create `inbox/` if missing.
 2. **Name the file.** `YYYYMMDD-<slug>.md` — today's date plus a short (2–4 word) slug.
 3. **Handle collisions.** If the filename already exists in *any* status directory, ask one question — extend the existing item or new item? On extend, append a dated `## Update (YYYY-MM-DD)` section to it where it is; on new, suffix the slug (`-2`). Never silently overwrite.
-4. **Write the file** into `inbox/`, with `source: human`, `promoted_to: null`, and one `history` entry dated today. Record `depends_on` only if the braindump itself names other items; never ask for dependencies. Do not interrogate the user for structure — capture friction kills inboxes; one braindump in, one file out.
-5. **Draft the executive summary from the braindump, do not extract it by interview.** You write those six lines; the user does not. Ask at most one question, and only when the braindump says nothing about who wants this or why — a good one is "would this make money, save money, or is it just something that needs doing?". Anything still unknown is `Not yet decided.`, which is the point of having the label.
-6. **Confirm and return.** Report the file path and the `Recommendation` line, then return to whatever was happening. Showing the recommendation lets the user correct a wrong read immediately, while the context is still in front of them.
+4. **Merge first.** Before writing a new file, check whether an open item — anything in `inbox/`, `backlog/` or `in-progress/` — already owns the area this is about. If one does, append a dated `## Received from <source>` section to **that** item and stop; say which item it went to. This is about *subject*, where step 3 is about *filename*: four of those eighteen items were findings about areas an existing item already owned, one of them literally asking somebody to triage another item. Merging them took minutes and removed four files. A new file is the right answer when no open item owns the area — which is most of the time, and the check costs one read of a list you are already looking at.
+5. **Write the file** into `inbox/`, with `source: human`, `promoted_to: null`, and one `history` entry dated today. Record `depends_on` only if the braindump itself names other items; never ask for dependencies. Do not interrogate the user for structure — capture friction kills inboxes; one braindump in, one file out.
+6. **Draft the executive summary from the braindump, do not extract it by interview.** You write those six lines; the user does not. Ask at most one question, and only when the braindump says nothing about who wants this or why — a good one is "would this make money, save money, or is it just something that needs doing?". Anything still unknown is `Not yet decided.`, which is the point of having the label.
+7. **Confirm and return.** Report the file path and the `Recommendation` line, then return to whatever was happening. Showing the recommendation lets the user correct a wrong read immediately, while the context is still in front of them.
 
 **Hard rule:** capture never reads or writes anything under `.aidlc/state/` — no claims, no phase files, no transitions log. Two sessions capturing simultaneously just produce two files; no locking exists or is needed. Do not auto-commit; staging is the user's.
 
@@ -130,13 +141,17 @@ If the user includes credentials, tokens, or secrets in a braindump, flag it and
 
 List each status directory, reading **only frontmatter and the containing directory** — never item bodies. Show each item's date, title, status, and dependencies. Group by status in lifecycle order and give a count per status. Flag `inbox/` items first: they are waiting on a decision only a human can make. Then flag `backlog/` items whose dependencies are all `done` — those are the natural next candidates. Offer to open, triage, promote, or drop.
 
+For a `hold/` item, show whether it is **parked or declined**, with its reason, from the last `history` entry — that entry is in the frontmatter, so this costs nothing extra. An item with no reason recorded is reported as `hold — reason not recorded`, never guessed at: parked and declined are opposite answers, and a wrong one either revives work somebody killed or buries work somebody agreed to.
+
 The frontmatter-only rule holds for browsing, which is a list and must stay cheap enough to run over the whole roadmap. **Triage** below is the one flow allowed into the body, and only as far as the executive summary.
 
 A filename appearing in two status directories is an error: report it rather than guessing which one is current.
 
 ## Triage
 
-Moving an `inbox/` item to `backlog/` means "we agree to do this". Moving it to `hold/` means "not now". Move the file and append the matching `history` entry. Triage is the one flow that exists purely because more than one person can submit work — do not skip it by promoting straight from `inbox/` unless the user says so.
+Moving an `inbox/` item to `backlog/` means "we agree to do this". Moving it to `hold/` means "not now", and carries a reason prefixed `parked — ` or `declined — `. Move the file and append the matching `history` entry. Triage is the one flow that exists purely because more than one person can submit work — do not skip it by promoting straight from `inbox/` unless the user says so.
+
+Work you agree with but cannot start — gated on a trigger, a decision, or something that does not exist yet — goes to `hold/` as `parked`, not to `backlog/`. Parking it with its trigger written down is the whole difference between a backlog you can read as "ready" and one where two of eleven entries are waiting on something.
 
 Triage is the one flow that reads into the body, and it reads **the executive summary and nothing else**. Six labelled lines per item is what makes triaging a full inbox in one sitting possible; opening whole items is what makes triage something nobody ever gets round to. Show the summary, say which way you would go and why, and let the human decide. If an item has no executive summary, write one from what the item says before asking for a decision — a decision made without one is a decision made twice.
 
@@ -159,7 +174,7 @@ When the instance completes, the `roadmap-done` lifecycle action moves the item
 
 ## Drop
 
-Move the item to `hold/` and append the `history` entry. Dropping is an explicit act — never delete or overwrite an item to get rid of it.
+Move the item to `hold/` and append the `history` entry, with a reason prefixed `declined — `. Dropping is an explicit act — never delete or overwrite an item to get rid of it, and never leave the reason off: `hold/` holds parked work too, and an unexplained entry there is a decision nobody can tell apart from the opposite one.
 
 ## Projecting to GitHub Issues
 

package/skills/90-retrospective.md

@@ -30,9 +30,11 @@ Run the retro **before** any completion cleanup (worktree removal, claim release
 3. **Ask — one round-trip.** Three questions in a single message: what surprised us? what would we do differently? what took longer than expected? For **Micro scope**, compress to one question: "anything surprising, worth doing differently, or slower than expected?" Declining the retro is fine: remove the marker, write nothing.
 4. **Write `retrospective.md`** in the instance state dir: the answers; instance metadata (template, scope); per-phase durations (pair each transitions.log `to: X` with the next `from: X`; fall back to the phase YAML's `entered_at`/`completed_at`; note inconsistencies rather than guessing); and the cost summary when available.
 5. **Distill lessons — 0 to 3.** A lesson is a durable, project-general observation ("NDJSON merge=union false-dedups identical same-second events"), not an instance anecdote ("we finished late"). If nothing generalizes, write no lesson — an empty distillation is a valid outcome.
-6. **Confirm, then append.** Show the distilled entry verbatim and get one confirmation for the whole entry. Never append unconfirmed text — lessons are auto-loaded into every future session, so this confirmation is the injection gate. Redact anything resembling credentials or secrets. On confirm, append to the lessons layer per the write rules below.
-7. **Commit** `retrospective.md` and the lessons append to the **current branch** now, before any worktree cleanup runs.
-8. **Remove the retro-pending marker** if one exists.
+6. **Cap the follow-ups — 0 to 2 queued roadmap items.** Rank what the work turned up and queue at most the top two into `.aidlc/roadmap/inbox/`, each with its six-line executive summary (see **aidlc-roadmap**). **Zero is a valid outcome**, and often the right one. This is the same cap, in the same shape, as the 0–3 on lessons, and it exists because the lessons cap alone was half a brake: the framework capped what an instance *learned* and capped nothing about what it *queued*, so closing an instance reliably grew the backlog. One measured project emitted five to nine items per close; triage kept three of eighteen.
+7. **Record the rest as observed, not queued.** Everything past the cap goes into `retrospective.md` under `## Observed, not queued`, one line each. **The cap is on queued items, not on observations** — a retro that noticed nine things writes nine and queues two. Findable, attributable, and costing nobody a triage decision. If one of them matters later, it is already written down; promote it then, with the same summary rule.
+8. **Confirm, then append.** Show the distilled entry verbatim and get one confirmation for the whole entry. Never append unconfirmed text — lessons are auto-loaded into every future session, so this confirmation is the injection gate. Redact anything resembling credentials or secrets. On confirm, append to the lessons layer per the write rules below.
+9. **Commit** `retrospective.md` and the lessons append to the **current branch** now, before any worktree cleanup runs.
+10. **Remove the retro-pending marker** if one exists.
 
 ## Lessons Layer — Write Rules
 
@@ -85,5 +87,6 @@ Run only in the **primary checkout** (not a linked worktree — check `git rev-p
 ## Rules
 
 - The retro never blocks completion: it is non-blocking, declinable, and its absence is never an error.
+- The follow-up cap is never a reason to *not notice* something. Merge first — if an open roadmap item already owns the area, append a dated `## Received from <instance>` section to it rather than spending one of the two slots on a file that duplicates it.
 - Never write lessons without the step-6 confirmation. Never record credentials or secrets.
 - Lessons are historical observations, not directives — phrase them as what was learned, not as instructions to obey.