incitaciones 0.11.1 → 0.13.0

package/content/distilled/documentation/references/review-documentation/SKILL.md

@@ -16,7 +16,7 @@ Goal: does this topic have a single, clear intent? Checks: is it a Tutorial, How
 
 ### Pass 2: EPPO & Standalone Utility
 
-Goal: can a foraging reader land here and succeed? Checks: are context and prerequisites established in the first two sentences? Does it rely on "previous chapter" knowledge without links? Issue prefix: [EPPO-001].
+Goal: can a foraging reader land here and succeed? Checks: are context and prerequisites established in the first two sentences? Does it rely on "previous chapter" knowledge without links? Is domain jargon defined at first use or via a glossary? (Jargon rule: `../research-documentation/references/checklist.md` and `../implement-documentation/references/anti-patterns.md` — cross-reference, do not duplicate here.) Issue prefix: [EPPO-001].
 
 ### Pass 3: Cognitive Scannability (Info Mapping)
 
@@ -24,11 +24,11 @@ Goal: can the reader scan the page in under 10 seconds and find the key answer?
 
 ### Pass 4: Accuracy, "Whole Game" & Fail-States
 
-Goal: is the content technically sound and resilient? Checks: are code snippets verified? Does it show the complete result? Are common errors documented? In tutorials, is the Martini Glass pattern followed (guided context then open exploration)? Issue prefix: [ACC-001].
+Goal: is the content technically sound and resilient? Checks: are code snippets verified? Does it show the complete result? Are common errors documented? In tutorials, is the Martini Glass pattern followed (guided context then open exploration)? If the subject is a runnable tool/API: spot-check documented claims against the artifact itself (the method statement goes in the Final Report provenance block). For entry-point pages (README / landing / quickstart): is there a quickstart reaching a first verified success in minutes (time-to-first-success; see `../research-documentation/references/metrics.md`)? Issue prefix: [ACC-001].
 
 ### Pass 5: Excellence & AI-Readiness
 
-Goal: is it production-ready and optimized for AI agents? Checks: is there a TL;DR for LLMs? Are headers semantically unique for RAG? Is the Answer First (Pyramid Principle) in the TL;DR and first paragraph? Use `references/ai-readiness-criteria.md` for the deep AI-readiness checks (`llms.txt`, RAG chunking, dual-audience, schema sync). Issue prefix: [EXCL-001].
+Goal: is it production-ready and optimized for AI agents? Checks: is there a TL;DR for LLMs? Are headers semantically unique for RAG? Is the Answer First (Pyramid Principle) in the TL;DR and first paragraph? Use `references/ai-readiness-criteria.md` for the deep AI-readiness checks (`llms.txt`, RAG chunking, dual-audience, schema sync). Are claims marked by status — documented / interpreted / proposed / unknown — with unverified claims not stated as fact? Issue prefix: [EXCL-001].
 
 ## Final Report
 
@@ -36,10 +36,13 @@ Goal: is it production-ready and optimized for AI agents? Checks: is there a TL;
 - Top 3 Findings.
 - Verdict: Ready, Needs Revision, or Needs Rework.
 - Rationale.
+- Provenance: which revision/commit of the subject was reviewed (mark UNKNOWN if unpinned — never guess) and the review method (runtime-verified vs read-only).
+- Optional (entry-point pages: README / landing / quickstart): audience-barrier table (reader type × barriers × recommended approach).
 
 ## Rules
 
 - Reference exact locations (file, section, paragraph).
+- Cross-referenced criteria live in sibling mode references — do not copy them into this file; link instead.
 - Validate issues exist; do not flag "potential" issues without evidence.
 - The canonical theory lives in `content/research-documentation-frameworks.md`; `references/ai-readiness-criteria.md` is an operational excerpt that links back to it.
 

package/content/distilled/documentation/references/review-documentation/references/ai-readiness-criteria.md

@@ -25,6 +25,7 @@ Deep checks for Pass 5. The basic pass (TL;DR present, headers unique, Answer Fi
 - Is language precise enough for a machine? Natural-language ambiguity a human resolves from context is opaque to an agent.
 - Are error conditions and their meanings explicit?
 - Are capability boundaries stated (what the tool/API can and cannot do)?
+- Are claims marked by status (documented / interpreted / proposed / unknown) rather than stated as fact when unverified?
 
 ## Schema and spec sync (reference pages)
 

package/content/distilled/issues/references/create-issues/SKILL.md

@@ -1,4 +1,4 @@
-<!-- skill: create-issues, version: 1.4.1, status: verified -->
+<!-- skill: create-issues, version: 1.5.0, status: verified -->
 # Tracer-Bullet Issue Creation from Plan
 
 Break a reviewed plan into independently grabbable issues using tracer-bullet vertical slices.
@@ -22,9 +22,19 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
    - Prefer **vertical slices** over phase-by-phase horizontal tickets.
    - Each issue should cut through all necessary layers for one narrow capability: storage/schema, business logic, interface, tests, and observability/docs when relevant.
    - A slice must be independently verifiable or demoable.
-   - Mark each slice as:
-     - **AFK** — can be implemented and merged without human intervention.
-     - **HITL** — requires a human decision, approval, design review, copy review, policy signoff, etc.
+   - Mark each slice with a **lane** (execution mode) and a **complexity** grade:
+     - **Lane:**
+       - **AFK** — bounded, mechanically verifiable, mergeable without human intervention; the `afk` label means "safe to run autonomously", so it may only be applied when an objective gate exists (test suite, CI, or Meter command). Label: `afk`.
+       - **DESIGN** — needs an interactive design session before implementation: semantics decisions, API shape, concurrency models, trade-offs. A human works this with a strong-reasoning model, never autonomously. Label: `design`.
+       - **HITL** — pure human decision, approval, copy review, or policy signoff with little or no model work. Label: `hitl`.
+       - **REVIEW** — second-opinion pass over existing output (code review, spec audit, conformance check). Label: `review`.
+     - **Complexity (effort / model tier)** — graded by falsifiable criteria so a reviewer can gate a wrong tag:
+       - **S** — matches an existing pattern in the repo (same change shape already exists in code or a prior ticket); ≤3 files; no new public interface, dependency, or invariant; the Meter is an existing test command. Label: `complexity:s`.
+       - **M** — multi-file change within established patterns; new tests follow existing conventions; no new public API beyond the slice's own; no concurrency or protocol semantics. Label: `complexity:m`.
+       - **L** — introduces or changes an invariant, concurrency semantics, protocol conformance, or a public API; correctness requires reasoning the repo's existing tests do not already encode. Label: `complexity:l`.
+       - **XL** — unresolved semantics or cross-repo scope: two competent agents would disagree on what "done" means; do not schedule — decompose into S/M/L slices first. Label: `complexity:xl`.
+       - **Grade gate:** an S/M ticket that touches a public API, an invariant, or concurrency code is mis-tagged — retag L before publishing; an L ticket fully covered by an existing pattern plus an existing test command is mis-tagged — retag M or S.
+     - Classification signals: `decision`-type tickets or titles starting with Decide/Choose/Approve/Scope → DESIGN or HITL, never AFK; bounded bugs with a failing test or concrete repro in a repo with CI → AFK; verification/conformance sweeps → AFK; concurrency/security/semantics work → DESIGN unless a failing repro test exists; epics → XL. If the target repo has no CI or test suite, tag `no-gate` — never schedule AFK work without a gate.
    - Avoid tickets like “build backend”, “add UI”, or “refactor models first” unless the work is genuinely standalone.
    - **Title lint (hard rule — run on every drafted title before presenting):** a title must name a user-visible outcome (“CSV export works end-to-end”), not a layer. If a title names a layer or artifact — backend, frontend, API, route, button, serializer, schema, tests-only, docs-only, refactor-only — merge it into the outcome slice it serves. Layers differing is never sufficient reason to split: split by capability, never by layer.
 
@@ -33,11 +43,13 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
    - Present a numbered list before creating anything.
    - For each slice include:
      - **Title**
-     - **Type:** AFK or HITL
+     - **Lane:** AFK | DESIGN | HITL | REVIEW
+     - **Complexity:** S | M | L | XL
+     - **Gate:** Meter command or CI suite (required for AFK; `no-gate` otherwise)
      - **Blocked by:** slice numbers or “None”
      - **User stories covered**
      - **Why this is a tracer bullet:** brief end-to-end justification
-   - Ask whether the granularity, dependency graph, and AFK/HITL split look right.
+   - Ask whether the granularity, dependency graph, and lane/complexity split look right.
    - Iterate until approved.
 
 5. **Prepare issue bodies:**
@@ -90,6 +102,9 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
 - **Name the cheats:** add anti-goals wherever the gate could be gamed (test edits, new deps, API breaks).
 - **Anchor staleness:** always record `base_commit` metadata at creation; never publish a ticket anchored to nothing.
 - **Stop and ask:** if the plan only supports horizontal decomposition, propose a vertical rewrite before publishing.
+- **Lane and complexity are mandatory metadata:** every published slice carries both (`bd update <id> --label design --label complexity:m`). Route by them, not by preference: S/M AFK work defaults to the cheapest capable model tier; DESIGN and L work gets the strongest reasoning tier with elevated effort.
+- **No gate, no AFK label:** in a repo without CI/tests, tag `no-gate` *instead of* `afk` — the ticket is not scheduled autonomously until a gate exists; when one does, replace `no-gate` with `afk`.
+- **Escalation is a retag:** after two failed implementation attempts, raise complexity one grade (S→M→L); if the failure cause is semantic (unclear spec or design rather than implementation), switch the lane to `design`. Record the failure cause in the ticket either way.
 
 ## References
 - **Templates:** `references/templates.md`

package/content/distilled/issues/references/create-issues/references/criteria.md

@@ -18,7 +18,8 @@ Use these criteria to evaluate whether a plan has been translated into strong tr
 | **Baseline anchored** | Measurable claims record the pre-work value and the HEAD SHA as `base_commit` metadata for staleness detection. |
 | **Dependency hygiene** | Only real blockers are encoded; parallel work is not serialized without reason. |
 | **Workflow Mandate** | Includes the mandatory TDD and Tidy First block. |
-| **Execution mode** | Slice is explicitly marked AFK or HITL. |
+| **Execution mode** | Slice is explicitly marked with a lane (AFK/DESIGN/HITL/REVIEW) and a complexity grade (S/M/L/XL); AFK slices carry an objective gate or `no-gate` tag. |
+| **Complexity honesty** | Complexity matches the work, not the optimism: XL is used when semantics or scope are unresolved, not as a badge. |
 
 ## Tracer-Bullet Heuristics
 

package/content/distilled/issues/references/create-issues/references/templates.md

@@ -6,7 +6,9 @@ Use these templates for proposed slice breakdowns, issue descriptions, and the f
 
 ```markdown
 1. **[Title]**
-   - **Type:** [AFK|HITL]
+   - **Lane:** [AFK|DESIGN|HITL|REVIEW]
+   - **Complexity:** [S|M|L|XL]
+   - **Gate:** [Meter command / CI suite — required for AFK]
    - **Blocked by:** [None | Slice 1, Slice 2]
    - **User stories covered:** [Story A, Story B]
    - **Tracer-bullet rationale:** [Why this is a thin end-to-end slice]
@@ -71,8 +73,8 @@ Or: `None - can start immediately`
 **Plan:** [path/to/plan.md]
 
 ### Approved Slice Set
-1. **[Title]** — [AFK|HITL], blocked by [None|IDs]
-2. **[Title]** — [AFK|HITL], blocked by [None|IDs]
+1. **[Title]** — [AFK|DESIGN|HITL|REVIEW] [S|M|L|XL], blocked by [None|IDs]
+2. **[Title]** — [AFK|DESIGN|HITL|REVIEW] [S|M|L|XL], blocked by [None|IDs]
 
 ### Summary
 - **Total Issues Created:** [count]

package/content/distilled/issues/references/issue-review/SKILL.md

@@ -26,7 +26,7 @@ Treat the best issue sets as:
 - thin vertical slices rather than layer tickets
 - independently verifiable or demoable
 - minimal but sufficient dependency graphs
-- explicit about AFK vs HITL work
+- explicit about lane (AFK/DESIGN/HITL/REVIEW) and complexity (S/M/L/XL) work
 - traceable back to stories, plans, or specs
 - self-describing: tickets that create or reshape source files carry the file-header criterion (see `file-headers`) — undocumented files force agents to re-derive intent
 - machine-verifiable value claims: quantified Must gate, runnable Meter, explicit anti-goals, and a `base_commit` anchor that reveals staleness

package/content/distilled/issues/references/issue-review/references/pass-5-executability.md

@@ -6,6 +6,9 @@ Focus on:
 - Is there a machine-checkable Must gate (quantified, unit + number) backed by a runnable Meter command?
 - Are touched code files self-describing — Purpose/Responsibilities/Rationale header present and current (see `file-headers`)?
 - Are priorities and labels sensible?
+- Does every ticket carry lane and complexity metadata (`afk`/`design`/`hitl`/`review` + `complexity:s/m/l/xl`)?
+- Are lane/complexity tags consistent with the work (DESIGN or HITL work never tagged `afk`)?
+- Are AFK tickets backed by an objective gate (CI/test suite/Meter), or tagged `no-gate` and kept out of autonomous scheduling?
 - Are HITL handoff points explicit?
 - Is it clear what demo, test, or observable behavior proves completion?
 
@@ -19,6 +22,10 @@ Watch for:
 - Tickets that create or reshape source files with no file-header acceptance criterion — undocumented files force every implementing agent to re-derive intent
 - No regression suite named (pass-to-pass coverage unspecified)
 - HITL work masquerading as AFK
+- DESIGN work (semantics decisions, API shape, concurrency models) tagged or scheduled as AFK — semantics need an interactive session, not an overnight run
+- Tickets tagged `complexity:xl` (epic-sized or semantics-heavy) presented as schedulable work instead of decomposition candidates
+- AFK tickets with no objective gate and no `no-gate` tag
+- Complexity grades that fail the falsifiable criteria — an S/M ticket touching a public API, an invariant, or concurrency code is mis-tagged and must be retagged L before scheduling
 - Tickets that cannot be closed without information from another issue not listed as a blocker
 
 Prefix findings with `EXEC-`.

package/content/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026-09-30",
+  "version": "2026-10-09",
   "schema_version": "1.1",
   "prompts": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incitaciones",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Reusable prompts and skills for CLI LLM tools, with native pi package support.",
   "repository": {
     "type": "git",

package/pi-package/skills/create-issues/SKILL.md

@@ -12,7 +12,7 @@ disable-model-invocation: true
 
 #### Core Instructions (content/distilled/issues/references/create-issues/SKILL.md)
 
-<!-- skill: create-issues, version: 1.4.1, status: verified -->
+<!-- skill: create-issues, version: 1.5.0, status: verified -->
 # Tracer-Bullet Issue Creation from Plan
 
 Break a reviewed plan into independently grabbable issues using tracer-bullet vertical slices.
@@ -36,9 +36,19 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
    - Prefer **vertical slices** over phase-by-phase horizontal tickets.
    - Each issue should cut through all necessary layers for one narrow capability: storage/schema, business logic, interface, tests, and observability/docs when relevant.
    - A slice must be independently verifiable or demoable.
-   - Mark each slice as:
-     - **AFK** — can be implemented and merged without human intervention.
-     - **HITL** — requires a human decision, approval, design review, copy review, policy signoff, etc.
+   - Mark each slice with a **lane** (execution mode) and a **complexity** grade:
+     - **Lane:**
+       - **AFK** — bounded, mechanically verifiable, mergeable without human intervention; the `afk` label means "safe to run autonomously", so it may only be applied when an objective gate exists (test suite, CI, or Meter command). Label: `afk`.
+       - **DESIGN** — needs an interactive design session before implementation: semantics decisions, API shape, concurrency models, trade-offs. A human works this with a strong-reasoning model, never autonomously. Label: `design`.
+       - **HITL** — pure human decision, approval, copy review, or policy signoff with little or no model work. Label: `hitl`.
+       - **REVIEW** — second-opinion pass over existing output (code review, spec audit, conformance check). Label: `review`.
+     - **Complexity (effort / model tier)** — graded by falsifiable criteria so a reviewer can gate a wrong tag:
+       - **S** — matches an existing pattern in the repo (same change shape already exists in code or a prior ticket); ≤3 files; no new public interface, dependency, or invariant; the Meter is an existing test command. Label: `complexity:s`.
+       - **M** — multi-file change within established patterns; new tests follow existing conventions; no new public API beyond the slice's own; no concurrency or protocol semantics. Label: `complexity:m`.
+       - **L** — introduces or changes an invariant, concurrency semantics, protocol conformance, or a public API; correctness requires reasoning the repo's existing tests do not already encode. Label: `complexity:l`.
+       - **XL** — unresolved semantics or cross-repo scope: two competent agents would disagree on what "done" means; do not schedule — decompose into S/M/L slices first. Label: `complexity:xl`.
+       - **Grade gate:** an S/M ticket that touches a public API, an invariant, or concurrency code is mis-tagged — retag L before publishing; an L ticket fully covered by an existing pattern plus an existing test command is mis-tagged — retag M or S.
+     - Classification signals: `decision`-type tickets or titles starting with Decide/Choose/Approve/Scope → DESIGN or HITL, never AFK; bounded bugs with a failing test or concrete repro in a repo with CI → AFK; verification/conformance sweeps → AFK; concurrency/security/semantics work → DESIGN unless a failing repro test exists; epics → XL. If the target repo has no CI or test suite, tag `no-gate` — never schedule AFK work without a gate.
    - Avoid tickets like “build backend”, “add UI”, or “refactor models first” unless the work is genuinely standalone.
    - **Title lint (hard rule — run on every drafted title before presenting):** a title must name a user-visible outcome (“CSV export works end-to-end”), not a layer. If a title names a layer or artifact — backend, frontend, API, route, button, serializer, schema, tests-only, docs-only, refactor-only — merge it into the outcome slice it serves. Layers differing is never sufficient reason to split: split by capability, never by layer.
 
@@ -47,11 +57,13 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
    - Present a numbered list before creating anything.
    - For each slice include:
      - **Title**
-     - **Type:** AFK or HITL
+     - **Lane:** AFK | DESIGN | HITL | REVIEW
+     - **Complexity:** S | M | L | XL
+     - **Gate:** Meter command or CI suite (required for AFK; `no-gate` otherwise)
      - **Blocked by:** slice numbers or “None”
      - **User stories covered**
      - **Why this is a tracer bullet:** brief end-to-end justification
-   - Ask whether the granularity, dependency graph, and AFK/HITL split look right.
+   - Ask whether the granularity, dependency graph, and lane/complexity split look right.
    - Iterate until approved.
 
 5. **Prepare issue bodies:**
@@ -104,6 +116,9 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
 - **Name the cheats:** add anti-goals wherever the gate could be gamed (test edits, new deps, API breaks).
 - **Anchor staleness:** always record `base_commit` metadata at creation; never publish a ticket anchored to nothing.
 - **Stop and ask:** if the plan only supports horizontal decomposition, propose a vertical rewrite before publishing.
+- **Lane and complexity are mandatory metadata:** every published slice carries both (`bd update <id> --label design --label complexity:m`). Route by them, not by preference: S/M AFK work defaults to the cheapest capable model tier; DESIGN and L work gets the strongest reasoning tier with elevated effort.
+- **No gate, no AFK label:** in a repo without CI/tests, tag `no-gate` *instead of* `afk` — the ticket is not scheduled autonomously until a gate exists; when one does, replace `no-gate` with `afk`.
+- **Escalation is a retag:** after two failed implementation attempts, raise complexity one grade (S→M→L); if the failure cause is semantic (unclear spec or design rather than implementation), switch the lane to `design`. Record the failure cause in the ticket either way.
 
 ## References
 - **Templates:** `references/templates.md`
@@ -133,7 +148,8 @@ Use these criteria to evaluate whether a plan has been translated into strong tr
 | **Baseline anchored** | Measurable claims record the pre-work value and the HEAD SHA as `base_commit` metadata for staleness detection. |
 | **Dependency hygiene** | Only real blockers are encoded; parallel work is not serialized without reason. |
 | **Workflow Mandate** | Includes the mandatory TDD and Tidy First block. |
-| **Execution mode** | Slice is explicitly marked AFK or HITL. |
+| **Execution mode** | Slice is explicitly marked with a lane (AFK/DESIGN/HITL/REVIEW) and a complexity grade (S/M/L/XL); AFK slices carry an objective gate or `no-gate` tag. |
+| **Complexity honesty** | Complexity matches the work, not the optimism: XL is used when semantics or scope are unresolved, not as a badge. |
 
 ## Tracer-Bullet Heuristics
 
@@ -175,7 +191,9 @@ Use these templates for proposed slice breakdowns, issue descriptions, and the f
 
 ```markdown
 1. **[Title]**
-   - **Type:** [AFK|HITL]
+   - **Lane:** [AFK|DESIGN|HITL|REVIEW]
+   - **Complexity:** [S|M|L|XL]
+   - **Gate:** [Meter command / CI suite — required for AFK]
    - **Blocked by:** [None | Slice 1, Slice 2]
    - **User stories covered:** [Story A, Story B]
    - **Tracer-bullet rationale:** [Why this is a thin end-to-end slice]
@@ -240,8 +258,8 @@ Or: `None - can start immediately`
 **Plan:** [path/to/plan.md]
 
 ### Approved Slice Set
-1. **[Title]** — [AFK|HITL], blocked by [None|IDs]
-2. **[Title]** — [AFK|HITL], blocked by [None|IDs]
+1. **[Title]** — [AFK|DESIGN|HITL|REVIEW] [S|M|L|XL], blocked by [None|IDs]
+2. **[Title]** — [AFK|DESIGN|HITL|REVIEW] [S|M|L|XL], blocked by [None|IDs]
 
 ### Summary
 - **Total Issues Created:** [count]

package/pi-package/skills/documentation/references/review-documentation/SKILL.md

@@ -16,7 +16,7 @@ Goal: does this topic have a single, clear intent? Checks: is it a Tutorial, How
 
 ### Pass 2: EPPO & Standalone Utility
 
-Goal: can a foraging reader land here and succeed? Checks: are context and prerequisites established in the first two sentences? Does it rely on "previous chapter" knowledge without links? Issue prefix: [EPPO-001].
+Goal: can a foraging reader land here and succeed? Checks: are context and prerequisites established in the first two sentences? Does it rely on "previous chapter" knowledge without links? Is domain jargon defined at first use or via a glossary? (Jargon rule: `../research-documentation/references/checklist.md` and `../implement-documentation/references/anti-patterns.md` — cross-reference, do not duplicate here.) Issue prefix: [EPPO-001].
 
 ### Pass 3: Cognitive Scannability (Info Mapping)
 
@@ -24,11 +24,11 @@ Goal: can the reader scan the page in under 10 seconds and find the key answer?
 
 ### Pass 4: Accuracy, "Whole Game" & Fail-States
 
-Goal: is the content technically sound and resilient? Checks: are code snippets verified? Does it show the complete result? Are common errors documented? In tutorials, is the Martini Glass pattern followed (guided context then open exploration)? Issue prefix: [ACC-001].
+Goal: is the content technically sound and resilient? Checks: are code snippets verified? Does it show the complete result? Are common errors documented? In tutorials, is the Martini Glass pattern followed (guided context then open exploration)? If the subject is a runnable tool/API: spot-check documented claims against the artifact itself (the method statement goes in the Final Report provenance block). For entry-point pages (README / landing / quickstart): is there a quickstart reaching a first verified success in minutes (time-to-first-success; see `../research-documentation/references/metrics.md`)? Issue prefix: [ACC-001].
 
 ### Pass 5: Excellence & AI-Readiness
 
-Goal: is it production-ready and optimized for AI agents? Checks: is there a TL;DR for LLMs? Are headers semantically unique for RAG? Is the Answer First (Pyramid Principle) in the TL;DR and first paragraph? Use `references/ai-readiness-criteria.md` for the deep AI-readiness checks (`llms.txt`, RAG chunking, dual-audience, schema sync). Issue prefix: [EXCL-001].
+Goal: is it production-ready and optimized for AI agents? Checks: is there a TL;DR for LLMs? Are headers semantically unique for RAG? Is the Answer First (Pyramid Principle) in the TL;DR and first paragraph? Use `references/ai-readiness-criteria.md` for the deep AI-readiness checks (`llms.txt`, RAG chunking, dual-audience, schema sync). Are claims marked by status — documented / interpreted / proposed / unknown — with unverified claims not stated as fact? Issue prefix: [EXCL-001].
 
 ## Final Report
 
@@ -36,10 +36,13 @@ Goal: is it production-ready and optimized for AI agents? Checks: is there a TL;
 - Top 3 Findings.
 - Verdict: Ready, Needs Revision, or Needs Rework.
 - Rationale.
+- Provenance: which revision/commit of the subject was reviewed (mark UNKNOWN if unpinned — never guess) and the review method (runtime-verified vs read-only).
+- Optional (entry-point pages: README / landing / quickstart): audience-barrier table (reader type × barriers × recommended approach).
 
 ## Rules
 
 - Reference exact locations (file, section, paragraph).
+- Cross-referenced criteria live in sibling mode references — do not copy them into this file; link instead.
 - Validate issues exist; do not flag "potential" issues without evidence.
 - The canonical theory lives in `content/research-documentation-frameworks.md`; `references/ai-readiness-criteria.md` is an operational excerpt that links back to it.
 

package/pi-package/skills/documentation/references/review-documentation/references/ai-readiness-criteria.md

@@ -25,6 +25,7 @@ Deep checks for Pass 5. The basic pass (TL;DR present, headers unique, Answer Fi
 - Is language precise enough for a machine? Natural-language ambiguity a human resolves from context is opaque to an agent.
 - Are error conditions and their meanings explicit?
 - Are capability boundaries stated (what the tool/API can and cannot do)?
+- Are claims marked by status (documented / interpreted / proposed / unknown) rather than stated as fact when unverified?
 
 ## Schema and spec sync (reference pages)
 

package/pi-package/skills/issue-review/SKILL.md

@@ -40,7 +40,7 @@ Treat the best issue sets as:
 - thin vertical slices rather than layer tickets
 - independently verifiable or demoable
 - minimal but sufficient dependency graphs
-- explicit about AFK vs HITL work
+- explicit about lane (AFK/DESIGN/HITL/REVIEW) and complexity (S/M/L/XL) work
 - traceable back to stories, plans, or specs
 - self-describing: tickets that create or reshape source files carry the file-header criterion (see `file-headers`) — undocumented files force agents to re-derive intent
 - machine-verifiable value claims: quantified Must gate, runnable Meter, explicit anti-goals, and a `base_commit` anchor that reveals staleness
@@ -340,6 +340,9 @@ Focus on:
 - Is there a machine-checkable Must gate (quantified, unit + number) backed by a runnable Meter command?
 - Are touched code files self-describing — Purpose/Responsibilities/Rationale header present and current (see `file-headers`)?
 - Are priorities and labels sensible?
+- Does every ticket carry lane and complexity metadata (`afk`/`design`/`hitl`/`review` + `complexity:s/m/l/xl`)?
+- Are lane/complexity tags consistent with the work (DESIGN or HITL work never tagged `afk`)?
+- Are AFK tickets backed by an objective gate (CI/test suite/Meter), or tagged `no-gate` and kept out of autonomous scheduling?
 - Are HITL handoff points explicit?
 - Is it clear what demo, test, or observable behavior proves completion?
 
@@ -353,6 +356,10 @@ Watch for:
 - Tickets that create or reshape source files with no file-header acceptance criterion — undocumented files force every implementing agent to re-derive intent
 - No regression suite named (pass-to-pass coverage unspecified)
 - HITL work masquerading as AFK
+- DESIGN work (semantics decisions, API shape, concurrency models) tagged or scheduled as AFK — semantics need an interactive session, not an overnight run
+- Tickets tagged `complexity:xl` (epic-sized or semantics-heavy) presented as schedulable work instead of decomposition candidates
+- AFK tickets with no objective gate and no `no-gate` tag
+- Complexity grades that fail the falsifiable criteria — an S/M ticket touching a public API, an invariant, or concurrency code is mis-tagged and must be retagged L before scheduling
 - Tickets that cannot be closed without information from another issue not listed as a blocker
 
 Prefix findings with `EXEC-`.

package/pi-package/skills/issues/references/create-issues/SKILL.md

@@ -1,4 +1,4 @@
-<!-- skill: create-issues, version: 1.4.1, status: verified -->
+<!-- skill: create-issues, version: 1.5.0, status: verified -->
 # Tracer-Bullet Issue Creation from Plan
 
 Break a reviewed plan into independently grabbable issues using tracer-bullet vertical slices.
@@ -22,9 +22,19 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
    - Prefer **vertical slices** over phase-by-phase horizontal tickets.
    - Each issue should cut through all necessary layers for one narrow capability: storage/schema, business logic, interface, tests, and observability/docs when relevant.
    - A slice must be independently verifiable or demoable.
-   - Mark each slice as:
-     - **AFK** — can be implemented and merged without human intervention.
-     - **HITL** — requires a human decision, approval, design review, copy review, policy signoff, etc.
+   - Mark each slice with a **lane** (execution mode) and a **complexity** grade:
+     - **Lane:**
+       - **AFK** — bounded, mechanically verifiable, mergeable without human intervention; the `afk` label means "safe to run autonomously", so it may only be applied when an objective gate exists (test suite, CI, or Meter command). Label: `afk`.
+       - **DESIGN** — needs an interactive design session before implementation: semantics decisions, API shape, concurrency models, trade-offs. A human works this with a strong-reasoning model, never autonomously. Label: `design`.
+       - **HITL** — pure human decision, approval, copy review, or policy signoff with little or no model work. Label: `hitl`.
+       - **REVIEW** — second-opinion pass over existing output (code review, spec audit, conformance check). Label: `review`.
+     - **Complexity (effort / model tier)** — graded by falsifiable criteria so a reviewer can gate a wrong tag:
+       - **S** — matches an existing pattern in the repo (same change shape already exists in code or a prior ticket); ≤3 files; no new public interface, dependency, or invariant; the Meter is an existing test command. Label: `complexity:s`.
+       - **M** — multi-file change within established patterns; new tests follow existing conventions; no new public API beyond the slice's own; no concurrency or protocol semantics. Label: `complexity:m`.
+       - **L** — introduces or changes an invariant, concurrency semantics, protocol conformance, or a public API; correctness requires reasoning the repo's existing tests do not already encode. Label: `complexity:l`.
+       - **XL** — unresolved semantics or cross-repo scope: two competent agents would disagree on what "done" means; do not schedule — decompose into S/M/L slices first. Label: `complexity:xl`.
+       - **Grade gate:** an S/M ticket that touches a public API, an invariant, or concurrency code is mis-tagged — retag L before publishing; an L ticket fully covered by an existing pattern plus an existing test command is mis-tagged — retag M or S.
+     - Classification signals: `decision`-type tickets or titles starting with Decide/Choose/Approve/Scope → DESIGN or HITL, never AFK; bounded bugs with a failing test or concrete repro in a repo with CI → AFK; verification/conformance sweeps → AFK; concurrency/security/semantics work → DESIGN unless a failing repro test exists; epics → XL. If the target repo has no CI or test suite, tag `no-gate` — never schedule AFK work without a gate.
    - Avoid tickets like “build backend”, “add UI”, or “refactor models first” unless the work is genuinely standalone.
    - **Title lint (hard rule — run on every drafted title before presenting):** a title must name a user-visible outcome (“CSV export works end-to-end”), not a layer. If a title names a layer or artifact — backend, frontend, API, route, button, serializer, schema, tests-only, docs-only, refactor-only — merge it into the outcome slice it serves. Layers differing is never sufficient reason to split: split by capability, never by layer.
 
@@ -33,11 +43,13 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
    - Present a numbered list before creating anything.
    - For each slice include:
      - **Title**
-     - **Type:** AFK or HITL
+     - **Lane:** AFK | DESIGN | HITL | REVIEW
+     - **Complexity:** S | M | L | XL
+     - **Gate:** Meter command or CI suite (required for AFK; `no-gate` otherwise)
      - **Blocked by:** slice numbers or “None”
      - **User stories covered**
      - **Why this is a tracer bullet:** brief end-to-end justification
-   - Ask whether the granularity, dependency graph, and AFK/HITL split look right.
+   - Ask whether the granularity, dependency graph, and lane/complexity split look right.
    - Iterate until approved.
 
 5. **Prepare issue bodies:**
@@ -90,6 +102,9 @@ You are a Technical Project Manager. Translate a plan, spec, or PRD into thin en
 - **Name the cheats:** add anti-goals wherever the gate could be gamed (test edits, new deps, API breaks).
 - **Anchor staleness:** always record `base_commit` metadata at creation; never publish a ticket anchored to nothing.
 - **Stop and ask:** if the plan only supports horizontal decomposition, propose a vertical rewrite before publishing.
+- **Lane and complexity are mandatory metadata:** every published slice carries both (`bd update <id> --label design --label complexity:m`). Route by them, not by preference: S/M AFK work defaults to the cheapest capable model tier; DESIGN and L work gets the strongest reasoning tier with elevated effort.
+- **No gate, no AFK label:** in a repo without CI/tests, tag `no-gate` *instead of* `afk` — the ticket is not scheduled autonomously until a gate exists; when one does, replace `no-gate` with `afk`.
+- **Escalation is a retag:** after two failed implementation attempts, raise complexity one grade (S→M→L); if the failure cause is semantic (unclear spec or design rather than implementation), switch the lane to `design`. Record the failure cause in the ticket either way.
 
 ## References
 - **Templates:** `references/templates.md`

package/pi-package/skills/issues/references/create-issues/references/criteria.md

@@ -18,7 +18,8 @@ Use these criteria to evaluate whether a plan has been translated into strong tr
 | **Baseline anchored** | Measurable claims record the pre-work value and the HEAD SHA as `base_commit` metadata for staleness detection. |
 | **Dependency hygiene** | Only real blockers are encoded; parallel work is not serialized without reason. |
 | **Workflow Mandate** | Includes the mandatory TDD and Tidy First block. |
-| **Execution mode** | Slice is explicitly marked AFK or HITL. |
+| **Execution mode** | Slice is explicitly marked with a lane (AFK/DESIGN/HITL/REVIEW) and a complexity grade (S/M/L/XL); AFK slices carry an objective gate or `no-gate` tag. |
+| **Complexity honesty** | Complexity matches the work, not the optimism: XL is used when semantics or scope are unresolved, not as a badge. |
 
 ## Tracer-Bullet Heuristics
 

package/pi-package/skills/issues/references/create-issues/references/templates.md

@@ -6,7 +6,9 @@ Use these templates for proposed slice breakdowns, issue descriptions, and the f
 
 ```markdown
 1. **[Title]**
-   - **Type:** [AFK|HITL]
+   - **Lane:** [AFK|DESIGN|HITL|REVIEW]
+   - **Complexity:** [S|M|L|XL]
+   - **Gate:** [Meter command / CI suite — required for AFK]
    - **Blocked by:** [None | Slice 1, Slice 2]
    - **User stories covered:** [Story A, Story B]
    - **Tracer-bullet rationale:** [Why this is a thin end-to-end slice]
@@ -71,8 +73,8 @@ Or: `None - can start immediately`
 **Plan:** [path/to/plan.md]
 
 ### Approved Slice Set
-1. **[Title]** — [AFK|HITL], blocked by [None|IDs]
-2. **[Title]** — [AFK|HITL], blocked by [None|IDs]
+1. **[Title]** — [AFK|DESIGN|HITL|REVIEW] [S|M|L|XL], blocked by [None|IDs]
+2. **[Title]** — [AFK|DESIGN|HITL|REVIEW] [S|M|L|XL], blocked by [None|IDs]
 
 ### Summary
 - **Total Issues Created:** [count]

package/pi-package/skills/issues/references/issue-review/SKILL.md

@@ -26,7 +26,7 @@ Treat the best issue sets as:
 - thin vertical slices rather than layer tickets
 - independently verifiable or demoable
 - minimal but sufficient dependency graphs
-- explicit about AFK vs HITL work
+- explicit about lane (AFK/DESIGN/HITL/REVIEW) and complexity (S/M/L/XL) work
 - traceable back to stories, plans, or specs
 - self-describing: tickets that create or reshape source files carry the file-header criterion (see `file-headers`) — undocumented files force agents to re-derive intent
 - machine-verifiable value claims: quantified Must gate, runnable Meter, explicit anti-goals, and a `base_commit` anchor that reveals staleness

package/pi-package/skills/issues/references/issue-review/references/pass-5-executability.md

@@ -6,6 +6,9 @@ Focus on:
 - Is there a machine-checkable Must gate (quantified, unit + number) backed by a runnable Meter command?
 - Are touched code files self-describing — Purpose/Responsibilities/Rationale header present and current (see `file-headers`)?
 - Are priorities and labels sensible?
+- Does every ticket carry lane and complexity metadata (`afk`/`design`/`hitl`/`review` + `complexity:s/m/l/xl`)?
+- Are lane/complexity tags consistent with the work (DESIGN or HITL work never tagged `afk`)?
+- Are AFK tickets backed by an objective gate (CI/test suite/Meter), or tagged `no-gate` and kept out of autonomous scheduling?
 - Are HITL handoff points explicit?
 - Is it clear what demo, test, or observable behavior proves completion?
 
@@ -19,6 +22,10 @@ Watch for:
 - Tickets that create or reshape source files with no file-header acceptance criterion — undocumented files force every implementing agent to re-derive intent
 - No regression suite named (pass-to-pass coverage unspecified)
 - HITL work masquerading as AFK
+- DESIGN work (semantics decisions, API shape, concurrency models) tagged or scheduled as AFK — semantics need an interactive session, not an overnight run
+- Tickets tagged `complexity:xl` (epic-sized or semantics-heavy) presented as schedulable work instead of decomposition candidates
+- AFK tickets with no objective gate and no `no-gate` tag
+- Complexity grades that fail the falsifiable criteria — an S/M ticket touching a public API, an invariant, or concurrency code is mis-tagged and must be retagged L before scheduling
 - Tickets that cannot be closed without information from another issue not listed as a blocker
 
 Prefix findings with `EXEC-`.