@rasensio/aidlc-content 1.3.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.3.0",
+  "version": "1.5.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/20-requirements.md

@@ -27,6 +27,7 @@ Translate the ideation output (or the user's direct request) into precise, testa
    - Specific and unambiguous
    - Testable (an observable outcome)
    - Independent (not relying on unstated assumptions)
+   - **Identified**: write every criterion as a list item `- AC-<n>: <text>` (bold variants `- **AC-<n>**: ...` and `- **AC-<n>:** ...` are also valid). Assign `AC-1`, `AC-2`, ... sequentially. IDs are never renumbered or reused — an amended criterion keeps its meaning or is retired: mark it `- AC-<n> (retired YYYY-MM-DD, superseded by AC-<m>): <text>` and issue a new ID. The testing-phase gate parses these IDs and fails on any active criterion without a referencing test.
 4. **Set scope boundaries.** Explicitly state what is NOT included.
 5. **Non-functional requirements.** Address performance, security, accessibility, and compatibility where relevant.
 6. **For complex input or open decisions**: If requirements are extensive, or unresolved decisions block the draft, create an Input_File in `.aidlc/inbox/` following the User Input Protocol in **aidlc-overview**, rather than asking many sequential questions. Prefer drafting `requirements.md` early with unresolved points marked as explicit decision blocks — users decide better reacting to a concrete draft than answering abstract questions.

package/skills/30-design.md

@@ -21,7 +21,7 @@ Produce a technical design that satisfies the requirements. Define architecture,
 
 ## Instructions
 
-1. **Review requirements.** Read `requirements.md` (or its summary if one exists). Identify the key technical challenges.
+1. **Review requirements.** Read `requirements.md` (or its summary if one exists). Identify the key technical challenges. When requirements carry `AC-n` IDs, note in each design section which criteria it addresses — that linkage is what reviewers and the testing phase trace against.
 2. **Consult the knowledge graph.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase design` for existing architecture, decisions, and conventions before re-deriving them from code.
 3. **Define architecture.** Describe the high-level structure: components, their responsibilities, and how they communicate.
 4. **Specify interfaces.** For each component boundary, define the contract (function signatures, API shapes, data types).

package/skills/50-testing.md

@@ -27,11 +27,17 @@ Verify that the implementation satisfies all acceptance criteria. Produce eviden
    - Unit tests for pure logic and edge cases
    - Integration tests for component interactions
    - Property-based tests where inputs have broad domains
+   - **Reference AC IDs.** When `requirements.md` defines `AC-n` criteria, each test names the criteria it verifies — in the test name or a comment (e.g. `// AC-3`). The testing-phase gate scans test files for these references and fails on any active criterion with none. If two instances define the same ID, qualify the reference as `<instance>/AC-n`.
 3. **Run tests.** Execute the project's test suite. All new tests must pass.
 4. **Document results.** Write `testing.md` with:
    - Test plan (what was tested and why)
    - Results (pass/fail counts, any notable findings)
    - Coverage notes (which criteria are covered, any gaps)
+   - **`ac-coverage` block for indirect coverage.** A criterion verified manually or outside scannable test files is claimed in a fenced code block whose info string is `ac-coverage`, one `AC-<n>: <evidence>` line per entry — the gate unions these with scanned references:
+
+     ```ac-coverage
+     AC-7: verified manually — see results table above
+     ```
 5. **Address failures.** If tests reveal bugs, fix the implementation. Do not skip or weaken tests to force a pass.
 
 ## Exit Criteria

package/skills/81-continue.md

@@ -16,12 +16,11 @@ 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 current phase is complete but not transitioned → evaluate transition (check gates)