@rasensio/aidlc-content 1.21.0 → 1.23.0

package/package.json

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

package/skills/03-entry-point.md

@@ -71,12 +71,14 @@ If `.aidlc/state/` is empty or missing, offer just three options: start somethin
 Two sessions sharing one checkout collide on **git**, not on state: creating a branch in-place yanks the other session off its branch. Before creating anything, check whether another live session holds a claim:
 
 1. Read the claim files under `<git-common-dir>/aidlc/claims/` (resolve via `git rev-parse --git-common-dir`; legacy fallback: `claim:` in each `instance.yaml`). A claim is live when `renewed_at`/`claimed_at` is within `claim_timeout_minutes` (config, default 60) and it is not this session's own claim.
-2. Not a git repo, or no live claim from another session → proceed normally, no gate.
-3. Another live session found → present exactly three options and proceed with none until one is chosen:
+2. **A live claim only blocks when it shares this working directory.** The question is not "is another session live?" but "does another session share my working directory?" — a session in its own worktree, on its own branch, cannot yank you off yours or stage your files. A claim's directory is its `worktree_path` when it has one, and the primary checkout when that field is absent. A `worktree_path` naming a directory that no longer exists is a claim on the primary checkout again.
+3. A live claim that does **not** share this working directory: say so in one line and proceed with no gate. Knowing another instance is in flight is useful even when it cannot interfere; silence would be worse.
+4. Not a git repo, or no live claim sharing this working directory → proceed normally, no gate.
+5. A live claim sharing this working directory → present exactly three options and proceed with none until one is chosen:
    1. **Start in a separate worktree (recommended)** — `git worktree add -b <prefix>/<YYYYMMDD>-<name> <worktree_dir>/<repo>-<name> main` (prefix per template: bugfix→fix, micro-task/spike→chore, else feat; `worktree_dir` from the `concurrency:` config block, default `../`). Do all further work for the new instance inside that worktree; set `AIDLC_WORKTREE=1` before firing `on-instance-start` actions so the branch action no-ops. CLI shortcut: `aidlc start <template> --name <name> --worktree`.
    2. **Stop** — come back when the other instance is done.
    3. **Continue in this checkout, no code changes** — record `branch: null` in the new `instance.yaml`; entering Implementation stays blocked until a branch exists. CLI shortcut: `aidlc start <template> --name <name> --no-code`.
-4. `concurrency.mode: forbid` in config replaces the menu with a hard stop while another session is live.
+6. `concurrency.mode: forbid` in config replaces the menu with a hard stop while another session is live — **any** live session, sharing this working directory or not. Someone choosing a hard stop is choosing it for reasons this gate should not second-guess.
 
 ## Rules
 

package/skills/04-roadmap.md

@@ -141,10 +141,13 @@ Move the item to `hold/` and append the `history` entry. Dropping is an explicit
 
 Optional, opt-in, and inert until a `roadmap.sync` section exists in `.aidlc/config.yaml`. When a user asks how the roadmap can be visible to people who will not clone the repo, or how it can appear where their team already triages, the answer is `aidlc roadmap sync` — see `docs/roadmap.md`.
 
-Three things to know before you offer it:
+Four things to know before you offer it:
 
 - It is a **projection, not sync**. Disk stays the source of truth; nothing is written back to disk, so no item gains a `remote:` field and no flow above changes. The link lives on the issue as a marker carrying the item `id`.
 - **`inbox/` and `hold/` are not projected by default**, because an untriaged idea and a parked one are not decisions anybody has published. Do not widen that list on a user's behalf.
 - **Every write needs consent.** Suggest `aidlc roadmap sync --dry-run` first, always. It prints the plan, names the target repository, and touches nothing.
+- **The issue body carries the whole item** — its frontmatter facts, its prose, and links to its file and to the items it names — inside a region marked `<!-- aidlc-body:begin -->` … `<!-- aidlc-body:end -->`, regenerated on every sync. Text outside that region is preserved, so a note added to an issue description survives. When somebody asks why a projected issue is out of date, the answer is that a sync has not run since the item changed, not that the body is frozen.
+
+Editing an item's body is therefore a publishing act on a repo with `roadmap.sync` configured. That is not a reason to hesitate, but it is a reason not to paste anything into an item you would not put on the tracker. Item prose is sanitized on the way out — HTML comments removed, `@name` and `#123` made inert — so no sync notifies anybody; secrets are not sanitized, and never were. If a user's braindump contains credentials, the existing hard rule applies: flag it and leave them out of the file.
 
 `aidlc roadmap import <issue-url>` is the opposite direction, and it is one-shot: it writes one `inbox/` item with the issue linked and its executive summary left as `Not yet decided.`, which is then a normal triage. Nothing reconciles afterwards.

package/skills/80-review.md

@@ -26,10 +26,16 @@ You MUST perform this review with fresh eyes. If you authored the artifact being
 
 - `<artifact>.review.md` — Structured findings file in the instance namespace
 
+Write **one findings file per required artifact** of the phase under review. The phase's required artifacts are listed in `phase-<name>.yaml` in the instance directory — read them from there rather than from a list in this skill, because they vary per template and a project may override a template under `.aidlc/templates/`.
+
+This is what the review gate checks: it looks for a findings file for each required artifact of the gated phase, so a phase with two required artifacts needs two files. Optional artifacts are yours to judge — the gate does not ask about them.
+
+The split is also the better review. Reviewing `design.md` and `tasks.md` into one pooled file lets a finding about one hide behind the other; separating them forced `agent-portability`'s findings about its architecture diagram apart from its findings about the design, and two of those turned out to be real defects that the pooled form had obscured.
+
 ## Instructions
 
 1. **Read the target artifact completely.** Do not skim.
-   - When reviewing a design artifact and the instance has a `tasks.md`, review it together with the design: breakdown completeness (every design section covered by a task), task sizing (commit-sized units), and AC linkage (tasks reference the criteria they satisfy). Record its findings in the design review's findings file — no separate `tasks.review.md`.
+   - When the phase requires a `tasks.md` as well as a `design.md`, review the breakdown **with the design in hand** — breakdown completeness (every design section covered by a task), task sizing (commit-sized units), and AC linkage (tasks reference the criteria they satisfy) are all judgements about the design/breakdown pair, not about `tasks.md` alone. Read both, then record the breakdown's findings in its own findings file.
 2. **Load guidance.** Read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills. A newly installed layer takes effect immediately, so do not assume the layers named in this skill are the only active ones.
 3. **Check for installed compliance controls.** Run `aidlc compliance list`. If nothing is installed, skip this step and the compliance findings stream below entirely — there is nothing to check and no file to write. If a pack is installed, run `aidlc compliance check` to get the controls that apply to this phase, each with what it requires, where to look, and its fail condition. Apply those fail conditions **as written**: they are the pack's, and reinterpreting one turns a stated control into your opinion.
 4. **Examine for each dimension:**
@@ -51,7 +57,7 @@ You MUST perform this review with fresh eyes. If you authored the artifact being
    - **Issue**: Clear description of the problem
    - **Suggestion**: A concrete resolution or question to ask
    - **Status**: `open` (always for new findings)
-6. **Save the findings file** as `<artifact>.review.md` in the instance namespace.
+6. **Save the findings file** as `<artifact>.review.md` in the instance namespace — one per required artifact, per **Required Artifacts** above.
 7. **Write the compliance findings stream**, only when a pack is installed. It is a
    **separate file**: `<artifact>.compliance.md`, never mixed into
    `<artifact>.review.md`. The separation is load-bearing — the phase transition gate
@@ -115,7 +121,7 @@ satisfies nothing, and a control appearing in neither section counts as unchecke
 
 ## Exit Criteria
 
-- Findings file exists in the instance namespace
+- A findings file exists in the instance namespace for **every required artifact** of the phase under review, as listed in `phase-<name>.yaml`
 - Every dimension was considered (even if no issues found — state "no issues" for that dimension)
 - Findings are actionable (each has a concrete suggestion or question)
 - When a compliance pack is installed: `<artifact>.compliance.md` exists and every

package/tutorials/deep-dive-making-it-yours.md

@@ -1,6 +1,6 @@
 ---
 title: "Making it yours"
-description: "How a lesson from one job reaches the next one, turning a repeatable chore into a skill instead of a project, keeping the repository healthy, and running the same setup on five different assistants."
+description: "How a lesson from one job reaches the next one, turning a repeatable chore into a skill instead of a project, keeping the repository healthy, and running the same setup on six different assistants."
 order: 17
 slug: deep-dive-making-it-yours
 series: deep-dive
@@ -61,9 +61,9 @@ Two tiers, and the split is the interesting bit. **Safe** repairs apply on their
 
 The same pass runs during `aidlc update`, with one difference that's a deliberate design choice: `doctor` exits non-zero when confirmable work is pending, and `update` never fails for it. A command you run to check health should be able to fail; a command you run to get the latest version should not fail because of unrelated tidying.
 
-## Step 6: The same setup on five assistants
+## Step 6: The same setup on six assistants
 
-The lifecycle instructions live once, in `.aidlc/skills/`, as plain markdown. Setup packages that same text into whatever native format each assistant expects — Claude Code, Cursor, Kiro, Codex, Windsurf all get files in their own convention, generated from one canonical body.
+The lifecycle instructions live once, in `.aidlc/skills/`, as plain markdown. Setup packages that same text into whatever native format each assistant expects — Claude Code, Cursor, Kiro, Codex, Windsurf and GitHub Copilot all get files in their own convention, generated from one canonical body.
 
 ```bash
 npx @rasensio/aidlc init --platform claude-code

package/tutorials/getting-started.md

@@ -7,7 +7,7 @@ slug: getting-started
 
 ## Step 1: Install and Set Up AIDLC
 
-AIDLC works with Claude Code, Cursor, Windsurf, Kiro, and Codex. One command sets everything up — run it interactively to choose platforms, scope, and a default template, or pass `--platform` to skip the prompts:
+AIDLC works with Claude Code, Cursor, Windsurf, Kiro, Codex, and GitHub Copilot. One command sets everything up — run it interactively to choose platforms, scope, and a default template, or pass `--platform` to skip the prompts:
 
 ```bash
 # Interactive setup — choose platforms, scope, and default template