@rasensio/aidlc-content 1.4.0 → 1.6.0

package/package.json

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

package/skills/00-overview.md

@@ -40,8 +40,8 @@ All state lives in `.aidlc/state/<instance-name>/`. Read and write state as foll
 
 ### Writing State
 
-1. **Before mutating state**, check for an existing Instance_Claim in `instance.yaml`. If another session holds the claim and it is not stale, warn and request override confirmation.
-2. Claim with `aidlc claim <instance>` (release with `aidlc release <instance>`) — it updates `instance.yaml` and appends the claim event to `sessions.ndjson` in one step. Without the CLI, do both writes yourself: set the claim fields in `instance.yaml`, then append `{"event":"claim|release","session_id":"...","id_source":"agent","agent":"<platform>","timestamp":"<ISO 8601 UTC>"}` to `.aidlc/state/<instance>/sessions.ndjson`. Never rewrite that file — append only. If the CLI warns your claim is near timeout, run `aidlc claim --renew <instance>`.
+1. **Before mutating state**, check for an existing Instance_Claim. Claims live in `<git-common-dir>/aidlc/claims/<instance>.yaml` (resolve via `git rev-parse --git-common-dir`) so every worktree of the repo sees the same claims; outside a git repo (or on instances not yet migrated) the claim is the `claim:` field in `instance.yaml`. If another session holds a non-stale claim, warn and request override confirmation.
+2. Claim with `aidlc claim <instance>` (release with `aidlc release <instance>`) — it writes the claim file and appends the claim event to `sessions.ndjson` in one step. Without the CLI, do both writes yourself: write the claim file (fields: `session`, `claimed_at`, `id_source`, optional `renewed_at`/`worktree_path`), then append `{"event":"claim|release","session_id":"...","id_source":"agent","agent":"<platform>","timestamp":"<ISO 8601 UTC>"}` to `.aidlc/state/<instance>/sessions.ndjson`. Never rewrite that file — append only. If the CLI warns your claim is near timeout, run `aidlc claim --renew <instance>`. Renew at every phase transition and before long-running operations — a claim older than `claim_timeout_minutes` counts as stale.
 3. Update phase state files as you produce artifacts.
 4. Append a transition record to `transitions.log` only on successful phase transitions. When completing a phase, set `metrics.elapsed_seconds` in its `phase-<name>.yaml` from `entered_at` → `completed_at` — cost and time reports read it.
 5. After a successful phase transition, fire lifecycle actions: `on-phase-exit` for the phase you left, then `on-phase-enter` for the phase you entered (see **Lifecycle Actions**).
@@ -58,8 +58,9 @@ Each line in `transitions.log` is a JSON object:
 
 The `aidlc start` CLI automates this; when it is not available, create the instance directly:
 
+0. **Concurrency gate first** (see the entry-point skill): when another live session holds a claim in this checkout, offer worktree / stop / no-code before creating anything.
 1. Pick a template and scope (see **aidlc-getting-started** for template selection and per-template artifacts). The initial phase follows the scope: full → ideation, standard → requirements, micro → implementation.
-2. Choose a URL-safe instance name and create `.aidlc/state/<name>/`. If the directory already exists, stop and ask for a different name.
+2. Choose a URL-safe instance name and create `.aidlc/state/<name>/`. If the directory already exists, stop and ask for a different name. In a git repo, also register the instance in `<git-common-dir>/aidlc/registry/<name>.yaml` (fields: `name`, `branch`, `worktree_path`, `created_at`) — create-exclusively, never overwrite; if the file exists, another session owns the name.
 3. Write `instance.yaml`:
    ```yaml
    name: <instance-name>
@@ -71,6 +72,7 @@ The `aidlc start` CLI automates this; when it is not available, create the insta
    claim: null
    scope_history: []
    ```
+   For a worktree instance add `branch: <its-branch>`; for a no-code instance add `branch: null` (blocks Implementation entry until a branch exists). Omit the field entirely otherwise.
 4. For each phase the template defines within the scope, write `phase-<name>.yaml`:
    ```yaml
    phase: <phase-name>
@@ -85,7 +87,7 @@ The `aidlc start` CLI automates this; when it is not available, create the insta
        status: not-started
    metrics: { elapsed_seconds: 0, artifact_count: 0 }
    ```
-5. Fire the `on-instance-start` lifecycle actions (see **Lifecycle Actions**). Do not skip this — automation the user configured (branch creation, issue tracking, notifications) depends on it.
+5. Fire the `on-instance-start` lifecycle actions (see **Lifecycle Actions**). Do not skip this — automation the user configured (branch creation, issue tracking, notifications) depends on it. When the instance was created via the worktree flow or as no-code, set `AIDLC_WORKTREE=1` in the action environment so the branch-creation action no-ops (the worktree flow already made its branch; a no-code instance must not get one).
 6. Report the instance name, phases, state path, and any actions that fired, then begin the initial phase with its skill.
 
 ## Lifecycle Actions

package/skills/03-entry-point.md

@@ -48,13 +48,25 @@ If `.aidlc/state/` is empty or missing, offer just three options: start somethin
 | Choice | Action |
 |--------|--------|
 | Continue an instance | Follow the **aidlc-continue** skill |
-| Start something new | Ask what they are building, pick a template (see **aidlc-getting-started**), then create the instance per "Creating an Instance" in **aidlc-overview** |
+| Start something new | Run the **concurrency gate** (below), then ask what they are building, pick a template (see **aidlc-getting-started**), and create the instance per "Creating an Instance" in **aidlc-overview** |
 | Capture an idea | Follow the **aidlc-idea** skill (capture flow) |
 | Browse / promote ideas | Follow the **aidlc-idea** skill (browse/promote flow) |
 | Show status | Summarize each instance from its state files — name, template, current phase, completion %, and whether it looks stalled. When the backlog is non-empty, append the idea count (e.g. "4 ideas in backlog, 3 raw") |
 | Review an artifact | Follow the **aidlc-review** skill |
 | Help / getting started | Follow the **aidlc-getting-started** skill |
 
+## Concurrency Gate (before "Start something new")
+
+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:
+   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.
+
 ## Rules
 
 - Building the menu is read-only — never mutate state while composing it. Claims are taken by the routed skill (see aidlc-continue).

package/skills/30-design.md

@@ -29,11 +29,22 @@ Produce a technical design that satisfies the requirements. Define architecture,
 6. **Design decisions.** Record each significant decision with rationale and alternatives considered. Persist accepted decisions as `decision` entities: `aidlc knowledge add --type decision --id <slug> --name "<title>" --description "<rationale>"`.
 7. **Address non-functional concerns.** Map performance, security, and accessibility requirements to design choices.
 8. **Identify risks.** Note technical risks and mitigation strategies.
+9. **Produce the task breakdown.** For templates that require it (full-feature, quick-feature), write `tasks.md` in the instance state directory as the final design step — the design is not done until it is actionable. Decompose the design into commit-sized tasks: each one reviewable in one sitting and independently verifiable. One task per line, in this exact grammar:
+
+   ```
+   - [ ] T<n>: <title>
+   - [ ] T<n>: <title> (AC-1, AC-2)
+   - [x] T<n>: <title> (AC-3)
+   - [>] T<n>: <title> (AC-4) (deferred YYYY-MM-DD: <reason>)
+   ```
+
+   Number tasks sequentially (`T1`, `T2`, ...) — IDs are never renumbered or reused; a task overtaken by events is deferred with a reason, never deleted. Reference the acceptance criteria each task satisfies where any apply; chore or infrastructure tasks may legitimately have none (the implementation gate surfaces them as warnings, never failures).
 
 ## Exit Criteria
 
 - `design.md` exists with architecture, interfaces, and at least one design decision with rationale
 - The design addresses all acceptance criteria from `requirements.md`
+- For templates requiring it: `tasks.md` exists and every active acceptance criterion is claimed by at least one task, or the gap is deliberate
 - The user has confirmed the design direction
 
 ## Guidance

package/skills/40-implementation.md

@@ -24,7 +24,7 @@ Produce working code that satisfies the design and requirements. Follow project
 
 1. **Load context.** Read `.aidlc/context/style-guide.md` and `.aidlc/context/architecture.md` if they exist. Match the project's established patterns. If the project has a knowledge graph (`.aidlc/knowledge/` exists), also run `aidlc knowledge context --scope phase --phase implementation` and query it (`aidlc knowledge query <term>`) before re-exploring code it already describes.
 2. **Load guidance.** Read all active Guidance_Layers from `.aidlc/guidance/index.yaml`. Apply their rules during implementation.
-3. **Plan the work.** Break the implementation into discrete steps. For Micro scope, reference the task description and acceptance criteria directly.
+3. **Execute the task breakdown.** When the instance has a `tasks.md` (produced in Design for full/quick-feature scope), read it and execute tasks in order: complete a task, then mark its checkbox `[x]` as part of the same work unit — never batch checkbox updates for later. A task that should not be done is deferred in place (`- [>] T<n>: <title> (deferred YYYY-MM-DD: <reason>)`) with a dated reason, never skipped silently or deleted; the implementation→testing gate blocks on open tasks. For bugfix scope, create the optional `tasks.md` at implementation start when the fix spans more than one commit-sized unit. For Micro scope, reference the task description and acceptance criteria directly — no task file.
 4. **Write code.** Follow the design interfaces. Match existing code style (naming, formatting, error handling patterns).
 5. **Handle sensitive operations.** Before executing any of the following, describe the action and wait for explicit user confirmation:
    - File deletions or destructive operations

package/skills/80-review.md

@@ -27,6 +27,7 @@ You MUST perform this review with fresh eyes. If you authored the artifact being
 ## 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`.
 2. **Examine for each dimension:**
    - **Ambiguities** — Vague terms, undefined behavior, unclear scope
    - **Contradictions** — Requirements that conflict with each other

package/skills/81-continue.md

@@ -16,14 +16,14 @@ Resume an in-progress lifecycle instance efficiently. Determine where work left
    - Current phase
    - Template name
    - Scope
-   - Claim status
-2. **Check claim.** If another session holds the claim:
+2. **Check claim.** Claims live in `<git-common-dir>/aidlc/claims/<instance>.yaml` (resolve via `git rev-parse --git-common-dir`); fall back to the `claim:` field in `instance.yaml` outside a git repo or for unmigrated instances. If another session holds the claim:
    - Check `renewed_at` against the staleness timeout (default: 60 minutes)
    - If stale: warn and request override confirmation before taking over
    - If active: warn and do NOT proceed without explicit override
-3. **Claim the instance.** Prefer `aidlc claim <instance>` — it sets the claim fields and appends the claim event to `sessions.ndjson` (the durable session↔instance record cost attribution depends on). Without the CLI, do both: record your session identifier and timestamp in the claim fields, then append the claim event to `.aidlc/state/<instance>/sessions.ndjson` (append-only; see the state protocol in **aidlc-overview**). Release the same way when you stop (`aidlc release <instance>`).
+3. **Claim the instance.** Prefer `aidlc claim <instance>` — it writes the claim and appends the claim event to `sessions.ndjson` (the durable session↔instance record cost attribution depends on). Without the CLI, do both: write the claim file (or `claim:` field in the fallback case), then append the claim event to `.aidlc/state/<instance>/sessions.ndjson` (append-only; see the state protocol in **aidlc-overview**). Renew (`aidlc claim --renew`) at every phase transition. Release the same way when you stop (`aidlc release <instance>`).
 4. **Determine next step.** Apply this priority:
    - If current phase has incomplete required artifacts → produce the next artifact
+   - If the current phase is implementation and a task-bearing `tasks.md` exists → resume at the lowest-numbered open (`[ ]`) task; do NOT re-derive the plan from design.md
    - If current phase is complete but not transitioned → evaluate transition (check gates)
    - If transition is allowed → move to next pending phase
    - If all phases complete → report instance complete and fire `on-instance-complete`

package/templates/bugfix.yaml

@@ -10,5 +10,8 @@ override:
     required_artifacts:
       - name: reproduction.md
       - name: requirements.md
+  implementation:
+    optional_artifacts:
+      - name: tasks.md
 gates:
   adversarial-review: []

package/templates/full-feature.yaml

@@ -16,6 +16,7 @@ phases:
   - name: design
     required_artifacts:
       - name: design.md
+      - name: tasks.md
     optional_artifacts:
       - name: architecture-diagram.md
   - name: implementation

package/templates/quick-feature.yaml

@@ -9,6 +9,7 @@ phases:
   - name: design
     required_artifacts:
       - name: design.md
+      - name: tasks.md
   - name: implementation
     required_artifacts:
       - name: code-complete.md