@rasensio/aidlc-content 1.2.0 → 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Rodrigo Asensio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,10 +19,6 @@
     "capabilities/",
     "phases/"
   ],
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run"
-  },
   "engines": {
     "node": ">=18.0.0"
   },
@@ -35,5 +31,9 @@
     "fast-check": "^3.23.2",
     "typescript": "^5.8.3",
     "vitest": "^3.1.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
   }
-}
+}

package/skills/00-overview.md

@@ -41,10 +41,11 @@ 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. Record your session identifier in the claim fields when you begin work.
+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>`.
 3. Update phase state files as you produce artifacts.
-4. Append a transition record to `transitions.log` only on successful phase transitions.
+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**).
+6. **Cost fallback (once per session):** run `aidlc cost providers status`. If no metered provider is ACTIVE for your platform, then at each phase transition record usage via `aidlc cost record --manual --instance <name> --session - --fidelity estimated --units '<json>'` when your platform surfaces usage numbers to you (e.g. a per-turn credit trailer), else `--fidelity unknown` (no `--units`). Never invent numbers — an `unknown` interval marker lets `aidlc cost sync` attribute usage later.
 
 ### Transition Records
 

package/skills/04-idea-capture.md

@@ -22,17 +22,20 @@ One file per idea: `.aidlc/ideas/YYYYMMDD-<slug>.md`, beginning with exactly thi
 ---
 status: raw          # raw | promoted | dropped
 promoted_to: null    # instance name once promoted, else null
+depends_on: []       # optional — ideas this one builds on, by file name without .md
 ---
 ```
 
 Ideas never silently vanish — they are `raw`, `promoted`, or explicitly `dropped` (the file stays in place). `status: promoted` always carries a non-null `promoted_to` naming an existing instance.
 
+`depends_on` lists other backlog ideas whose outcome this one builds on (e.g. `20260815-traceability-ids`). It is optional and defaults to empty. Build order is derived from this graph when needed — there is no global `order` field to maintain, because concurrent capture from independent sessions cannot coordinate a sequence.
+
 ## Capture
 
 1. **Resolve the backlog root.** Always write to the **primary checkout's** `.aidlc/ideas/`, 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 `.aidlc/ideas/` if missing.
 2. **Name the file.** `YYYYMMDD-<slug>.md` — today's date plus a short (2–4 word) slug derived from the idea.
 3. **Handle collisions.** If the filename already exists, ask one question — extend `<existing>` or new idea? On extend, append a dated `## Update (YYYY-MM-DD)` section; on new, suffix the slug (`-2`). Never silently overwrite.
-4. **Write the file.** Frontmatter (`status: raw`, `promoted_to: null`), then `# Idea: <title>`, `**Date:**`, and the braindump organized lightly (a Use Case section plus whatever structure the content suggests). Do not interrogate the user for structure — capture friction kills inboxes; one braindump in, one file out.
+4. **Write the file.** Frontmatter (`status: raw`, `promoted_to: null`), then `# Idea: <title>`, `**Date:**`, and the braindump organized lightly (a Use Case section plus whatever structure the content suggests). If the braindump itself references other backlog ideas, record them in `depends_on`; never ask for dependencies — the field is optional. Do not interrogate the user for structure — capture friction kills inboxes; one braindump in, one file out.
 5. **Confirm and return.** Report the file path and return to whatever was happening.
 
 **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.
@@ -41,16 +44,17 @@ If the user includes credentials, tokens, or secrets in a braindump, flag it and
 
 ## Browse
 
-List `.aidlc/ideas/*.md` reading only frontmatter and the `# Idea:` title line — not the bodies. Show each idea's date, title, and status. Offer to open, promote, or drop.
+List `.aidlc/ideas/*.md` reading only frontmatter and the `# Idea:` title line — not the bodies. Show each idea's date, title, status, and dependencies (`depends_on`). Flag raw ideas whose dependencies are all promoted — those are the natural next candidates. Offer to open, promote, or drop.
 
 ## Promote
 
 Promotion is where the backlog meets the lifecycle:
 
-1. Choose a template and scope as usual (defaults from `.aidlc/config.yaml`; see **aidlc-getting-started**).
-2. Create the instance per "Creating an Instance" in **aidlc-overview** — including firing `on-instance-start` lifecycle actions.
-3. Seed the instance with the idea file: Full scope → the idea is raw material the Ideation phase refines into `ideation.md`; Standard scope → the idea is input context for Requirements.
-4. Update the idea's frontmatter: `status: promoted`, `promoted_to: <instance-name>`.
+1. If the idea's `depends_on` names ideas that are still `raw`, say so and confirm before proceeding — promoting out of order is allowed but should be deliberate.
+2. Choose a template and scope as usual (defaults from `.aidlc/config.yaml`; see **aidlc-getting-started**).
+3. Create the instance per "Creating an Instance" in **aidlc-overview** — including firing `on-instance-start` lifecycle actions.
+4. Seed the instance with the idea file: Full scope → the idea is raw material the Ideation phase refines into `ideation.md`; Standard scope → the idea is input context for Requirements.
+5. Update the idea's frontmatter: `status: promoted`, `promoted_to: <instance-name>`.
 
 ## Drop
 

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

@@ -21,7 +21,7 @@ Resume an in-progress lifecycle instance efficiently. Determine where work left
    - 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.** Record your session identifier and timestamp in the claim fields.
+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>`).
 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)