@mohammadhprp/system-prompt 0.11.1 → 0.11.2

package/framework/skills/tlc-spec-driven/references/lessons.md

@@ -0,0 +1,115 @@
+# Lessons - Self-Improving Layer
+
+**Purpose**: Turn verification failures into reusable, project-local guidance that actually changes future behavior - without the lessons file rotting into a dead log.
+
+**The split that keeps it alive**: the agent (you) supplies *judgment* - read the failure, phrase the lesson, cite its grounding. The script `scripts/lessons.py` owns everything *mechanical* - IDs, recurrence counting across distinct features, candidate→confirmed promotion, pruning, demotion, and rendering. Hand-kept bookkeeping is exactly what rots, so it is not your job; the script's job.
+
+**What feeds it**: only the execution signals already produced by the Verifier in [validate.md](validate.md) and written to `.specs/features/[feature]/validation.md`. No signal → no lesson. This is the hard gate: a lesson with no grounding in a real verification outcome is an opinion, and the script refuses it.
+
+**Scope discipline (critical)**: this layer captures *execution* lessons that are project-local and grounded in a signal. It does **NOT** capture methodology opinions about the SDD process itself ("we should always discuss earlier"). Those are maintainer decisions that ship in a version bump - never auto-written. If a candidate lesson is really about how to run the skill rather than about this codebase, do not record it.
+
+---
+
+## Files
+
+| File | Owner | Purpose |
+| ---- | ----- | ------- |
+| `.specs/lessons.json` | script | Canonical machine state. Never hand-edit. |
+| `.specs/LESSONS.md` | script (rendered) | Human/agent-readable playbook. Read it; never write it by hand. |
+| `<skill-dir>/scripts/lessons.py` | package | The only way to mutate lessons. Invoke via the skill directory - never `python3 scripts/lessons.py` from the project root. |
+
+`confirmed` lessons are the playbook the agent loads. `candidate` lessons are tracked but NOT trusted until corroborated across `promote_threshold` distinct features (default 2). `quarantined` lessons failed when applied and are ignored.
+
+**Invocation:** resolve `<skill-dir>` as the directory that contains this skill's `SKILL.md`, then run `python3 <skill-dir>/scripts/lessons.py ...`. The store under `.specs/` is still relative to the project root (use `--root` when cwd differs).
+
+---
+
+## WRITE - distill lessons (runs inside Execute, after validation)
+
+This is **not a new phase**. It is the final action of the Verifier step in [validate.md](validate.md), grafted onto a step that already always runs. Do it immediately after `validation.md` is written, before reporting completion.
+
+### When to write
+
+Walk the just-written `validation.md`. For each **grounded** signal, record one lesson:
+
+| validation.md signal | `--signal` value |
+| -------------------- | ---------------- |
+| An acceptance criterion failed or had no evidence | `ac_gap` |
+| A discrimination-sensor mutant survived (weak test) | `surviving_mutant` |
+| A criterion flagged ⚠️ Spec-precision gap | `spec_precision_gap` |
+| A `// SPEC_DEVIATION` marker was added during implement | `spec_deviation` |
+| The build-level gate check failed | `gate_fail` |
+
+If `validation.md` is a clean PASS with no surviving mutants, no spec-precision gaps, and no deviations → **write nothing**. A clean run produces no lessons. This is correct, not a miss.
+
+### How to write
+
+For each signal, phrase the lesson as **one terse, actionable, codebase-general sentence** - a rule a future feature could apply, not a restatement of this bug. Then call the script:
+
+```bash
+python3 <skill-dir>/scripts/lessons.py add \
+  --feature "[feature folder name]" \
+  --signal  "[signal value from table above]" \
+  --source  "[file:line | AC id | mutant id | SPEC_DEVIATION ref from validation.md]" \
+  --text    "[the one-sentence lesson]" \
+  --scope   "[optional: path/layer/tag, e.g. billing, routes, repo-layer]"
+```
+
+**Phrasing rules** (they make recurrences actually merge - dedup is exact-after-normalization, not semantic):
+
+- Write the general rule, not the incident. ✅ `"Assert the exact persisted status value, not just that a status field exists"` ❌ `"The subscription test on line 88 was too weak"`.
+- Be canonical and terse. Two lessons that mean the same thing must read the same way, or the script counts them as different and neither gets promoted.
+- One lesson per signal. Don't bundle.
+
+`--source` is **mandatory**. The script exits non-zero if it is empty - that is the grounding gate working, not an error to route around.
+
+### Self-check (do not skip)
+
+After distilling, if `validation.md` contained any FAIL, surviving mutant, spec-precision gap, or SPEC_DEVIATION but you recorded zero lessons, state plainly in chat: *"Validation had signal X but no lesson was recorded - recording now / here's why it's out of scope."* Silent skipping is how the file dies.
+
+### Demotion
+
+If a `confirmed` lesson was loaded for this feature (see READ below) and the *same* failure recurred anyway, the guidance is not working:
+
+```bash
+python3 <skill-dir>/scripts/lessons.py penalize --id L-NNN
+```
+
+Two penalties quarantine it. Use sparingly and only on real repeats.
+
+---
+
+## READ - load lessons (runs at Specify and Design)
+
+A lessons file nobody reads is dead by definition. Loading is **mandatory**, not optional.
+
+At the start of **Specify** (and again at **Design** for Large/Complex), load the confirmed lessons relevant to this feature:
+
+```bash
+# All confirmed lessons:
+python3 <skill-dir>/scripts/lessons.py list --status confirmed
+
+# Or filter by the area this feature touches:
+python3 <skill-dir>/scripts/lessons.py list --status confirmed --scope billing
+python3 <skill-dir>/scripts/lessons.py list --status confirmed --query "idempotency"
+```
+
+Apply the returned lessons as guidance while writing the spec / design. Do **not** load `candidate` or `quarantined` lessons as guidance - they are not trusted. Keep the loaded set small; this runs inside the <40k token budget.
+
+---
+
+## Fallback when code execution is unavailable
+
+Some harnesses cannot run Python. Only then: maintain `.specs/LESSONS.md` by hand, following the exact same rules - grounded entries only, candidate→confirmed after 2 distinct features, prune stale candidates. **This path is degraded**: hand bookkeeping is the failure mode this layer exists to avoid, so prefer the script wherever a code tool exists. State once in chat that you are in the no-script fallback so the user knows accounting is best-effort.
+
+---
+
+## Disable
+
+This layer is additive and self-gating (no signal → no write). To turn it off for a project, delete `.specs/lessons.json` and `.specs/LESSONS.md` and skip the WRITE/READ steps. The core Specify→Design→Tasks→Execute flow is unaffected.
+
+---
+
+## Known limitation
+
+Deduplication is exact-after-normalization (Unicode casefold, diacritic-stripped, punctuation-stripped, any-script alnum preserved) - there are no embeddings (stdlib-only, zero-dependency by design). Near-duplicate lessons phrased differently will not merge and will each sit as separate candidates that never promote. Mitigation: follow the phrasing rules above. A future version may add embedding-based dedup.

package/framework/skills/tlc-spec-driven/references/memory.md

@@ -0,0 +1,144 @@
+# Memory Layer
+
+**File:** `.specs/STATE.md`
+
+A single file with two section-scoped parts. Each section has its own lifecycle; writes are always targeted - never whole-file overwrites.
+
+---
+
+## Sections
+
+### `## Decisions` - append-only log
+
+Records **project-level** decisions only: conventions, patterns, constraints, or cross-cutting technology choices that future features must follow or supersede.
+
+**Not project-level → stays in the feature's `design.md` Tech Decisions table.**  
+Heuristic: would a different feature need to know about this? If yes → project-level. If no → feature-local.
+
+**Record sparingly - the log stays useful only by staying small.** Even a project-level decision earns an `AD-NNN` entry only when all three hold:
+
+1. **Hard to reverse** - changing course later carries real cost.
+2. **Surprising without context** - a future reader will look at the result and wonder "why did they do it this way?"
+3. **The product of a real trade-off** - there were genuine alternatives and you chose one for specific reasons.
+
+If any one is missing, skip it: an easily-reversed choice you will just reverse; an unsurprising one nobody questions; a no-alternative choice records nothing beyond "we did the obvious thing." What typically qualifies: architectural shape, integration patterns between areas, technology choices that carry lock-in, boundary and ownership decisions, and deliberate deviations from the obvious path. A choice that clears all three but is only feature-local still stays in `design.md`.
+
+**Format** (one entry per decision):
+
+```markdown
+## Decisions
+
+### AD-001
+- **Decision**: [what was decided - one sentence]
+- **Reason**: [why this option was chosen]
+- **Trade-off**: [what was given up]
+- **Scope**: [which features / packages / layers this governs]
+- **Date**: YYYY-MM-DD
+- **Status**: active | superseded by AD-NNN
+```
+
+**Supersession rule:** When a new decision replaces an old one, append a new `AD-NNN` entry and update the old entry's `status` field to `superseded by AD-NNN`. Never delete old entries - the history is the audit trail.
+
+---
+
+### `## Handoff` - pause snapshot (~500 tokens, overwritten each pause)
+
+Captures mid-task / in-flight state so work can resume without re-reading the full task history. It complements `tasks.md` and git evidence: on resume, the Handoff is a starting hypothesis that must be reconciled against the real branch, commits, and working tree (see Resume below).
+
+**Format:**
+
+```markdown
+## Handoff
+
+- **Feature**: [feature name / .specs path]
+- **Phase / Task**: [e.g., Phase 2 / T4 - implement repository layer]
+- **Completed**: [comma-separated task IDs or "none"]
+- **In-progress** (file:line): [e.g., `src/billing/subscription.service.ts:88` - mid-write]
+- **Next step**: [one sentence - exactly what to do next]
+- **Blockers**: [none | description]
+- **Uncommitted files**: [list or "none"]
+- **Branch**: [git branch name]
+```
+
+---
+
+## File shape
+
+```markdown
+# STATE
+
+## Decisions
+
+[AD-NNN entries…]
+
+## Handoff
+
+[latest snapshot…]
+```
+
+If the file does not yet exist, create it with both section headers and empty bodies.
+
+---
+
+## Read / Write Triggers
+
+| Trigger | Section | Operation |
+| ------- | ------- | --------- |
+| Design phase, Step 1 (Load Context) | `## Decisions` | **Read** - conform to active decisions or supersede |
+| Design phase, Tech Decisions step | `## Decisions` | **Append** - only for project-level decisions |
+| Pause work / end of session | `## Handoff` | **Replace** - overwrite Handoff section only |
+| Resume work / start of session | `## Handoff` | **Read** - load snapshot, then reconcile with git before acting |
+| Resume work / start of session | `## Decisions` | **Read** - re-confirm active constraints before designing |
+
+---
+
+## Section-scoped write rule (critical)
+
+One file holds two lifecycles. Writes MUST target their section only:
+
+- **Design appends** to `## Decisions`. It MUST NOT touch `## Handoff`.
+- **Pause replaces** `## Handoff`. It MUST NOT rewrite, reorder, or drop any entry in `## Decisions`.
+
+The correct technique: locate the target section header, replace only the content between it and the next `##` header (or end of file). Never overwrite the full file.
+
+Violating this rule causes one of two failures:
+1. A pause write clobbers the decisions log → decisions are silently lost.
+2. A design append touches the handoff snapshot → mid-task state is corrupted.
+
+Both are silent data loss. The section-scoped write rule is the single correctness invariant of this memory layer.
+
+---
+
+## Pause / Resume Procedure
+
+### Pause
+
+1. Locate the `## Handoff` section in `.specs/STATE.md`.
+2. Replace its body (everything between `## Handoff` and the next `##` or EOF) with the current snapshot.
+3. Do NOT modify anything above or before `## Handoff`.
+4. Commit or stash outstanding changes as appropriate.
+
+### Resume
+
+1. Read `.specs/STATE.md` - both sections.
+2. Re-confirm active decisions from `## Decisions` - nothing superseded since last session?
+3. Read `## Handoff` - treat it as a **hypothesis** for feature, phase/task, next step, blockers, uncommitted files, branch - not as ground truth by itself.
+4. **Reconcile with git before editing anything:**
+   - Current branch vs Handoff `Branch`
+   - `git status --porcelain` (uncommitted / unexpected paths)
+   - Recent commits on the branch (messages and touched files)
+   - `tasks.md` completion marks and, when present, gate evidence / commit references
+5. **Resolve conflicts with evidence, not narrative:**
+   - A task with a green gate and an atomic commit already on the branch → do **not** redo it; mark it complete in `tasks.md` if the file still shows it open, then continue from the next incomplete task
+   - Partial unverified work in the working tree → preserve it, re-run the relevant gate, then finish the status+commit cycle
+   - Stale or missing Handoff → rebuild next-step from git + `tasks.md`, then propose that to the user
+   - Unexplained local changes you cannot map to the current task → STOP and ask; do not discard them
+6. Propose the reconciled next step to the user before writing any code.
+
+---
+
+## AD-NNN numbering
+
+- Numbers are sequential, project-scoped, and permanent - never reused.
+- The counter starts at `AD-001`. Check existing entries before assigning the next number.
+- If `.specs/STATE.md` does not exist, the first decision is `AD-001`.

package/framework/skills/tlc-spec-driven/references/specify.md

@@ -0,0 +1,228 @@
+# Specify
+
+**Goal**: Capture WHAT to build with testable, traceable requirements.
+
+If the feature has ambiguous gray areas (multiple valid approaches for user-facing behavior), the agent will automatically trigger the [discuss gray areas](discuss.md) process within this phase. For clear, well-defined features, it goes straight to the next phase.
+
+## Implicit-Requirement Dimensions
+
+The canonical rubric for requirements that are easy to miss. Referenced by [discuss.md](discuss.md) - defined here, not duplicated.
+
+| Dimension | What to cover |
+| --------- | ------------- |
+| Input validation & bounds | Limits, formats, sanitization |
+| Failure / partial-failure states | Timeouts, partial saves, rollbacks |
+| Idempotency / retry / duplicate handling | Safe retries, dedup keys |
+| Auth boundaries & rate limits | Who can call what, throttle rules |
+| Concurrency / ordering | Race conditions, ordering guarantees |
+| Data lifecycle / expiry | TTL, archival, deletion |
+| Observability | Logging, metrics, tracing hooks |
+| External-dependency failure | Circuit breakers, fallbacks |
+| State-transition integrity | Valid transitions, guards |
+
+---
+
+## Process
+
+### 1. Clarify Requirements
+
+**Load confirmed lessons first:** Before clarifying, load the project's confirmed lessons so past verification failures shape this spec instead of repeating. Run `python3 <skill-dir>/scripts/lessons.py list --status confirmed` (optionally `--scope [area]` or `--query [term]` for the area this feature touches) and apply what comes back as guidance. Load only `confirmed` - never `candidate` or `quarantined`. If no store exists yet or no code tool is available, skip silently. See [lessons.md](lessons.md).
+
+**Lightweight context scan first (Knowledge Verification Chain Step 1):** Before asking questions, briefly scan existing code, patterns, and neighboring features relevant to this feature. Use what you find to ground your clarifying questions in reality - not to constrain the spec to current implementation. Keep it lightweight (stay within the <40k token budget; reuse the chain, no new machinery). The spec captures WHAT is needed, not only what exists.
+
+You are a thinking partner, not an interviewer. Start open - let the user dump their mental model. Follow the energy: whatever they emphasize, dig into that.
+
+Ask conversationally (not as a checklist):
+
+- "What problem are you solving?"
+- "Who is the user and what's their pain?"
+- "What does success look like?"
+
+If needed:
+
+- "What are the constraints (time, tech, resources)?"
+- "What is explicitly out of scope?"
+
+**Facts you look up; decisions you ask.** Anything discoverable by reading the environment (the codebase, config, docs, existing conventions) you resolve yourself through the Knowledge Verification Chain - do not spend the user's attention asking for it. Reserve questions for genuine decisions that are the user's to make: scope, priorities, product behavior, trade-offs. A question you could have answered by reading the code erodes trust and wastes a turn.
+
+**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how? Make the abstract concrete: "Walk me through using this." "What does that actually look like?"
+
+**Know when to stop - then run the dimensions sweep.** When you understand what they're building, why, who it's for, and what done looks like, run a closing **implicit-requirement dimensions sweep** before offering to proceed:
+
+- **Large / Complex:** Cover every dimension above - each must resolve to a requirement OR an explicit `N/A because [reason]`. No blank entries allowed.
+- **Medium:** Cover only dimensions obviously present for this feature's domain; collapse the rest to a single `remaining dimensions N/A for this scope`.
+- **Small:** Skip the sweep entirely.
+
+The `N/A because...` escape is mandatory - it prevents inventing requirements to fill the checklist. Bound the sweep to THIS feature's scope; never add requirements outside the feature boundary.
+
+### 2. Capture User Stories with Priorities
+
+**P1 = MVP** (must ship), **P2** (should have), **P3** (nice to have)
+
+Each story MUST be **independently testable** - you can implement and demo just that story.
+
+### 3. Write Acceptance Criteria (EARS notation)
+
+Write every acceptance criterion in **EARS** (Easy Approach to Requirements Syntax). Each criterion resolves to exactly one pattern, which keeps it unambiguous and directly testable. Choose the pattern that fits the requirement instead of forcing everything into a single shape:
+
+| Pattern | Keyword | Template | Use for |
+| ------- | ------- | -------- | ------- |
+| Ubiquitous | (none) | The [system] SHALL [response] | Always-on invariants and constraints |
+| Event-driven | WHEN | WHEN [trigger] THEN the [system] SHALL [response] | A response to a discrete trigger |
+| State-driven | WHILE | WHILE [state] the [system] SHALL [response] | Behavior that holds during a state |
+| Optional-feature | WHERE | WHERE [feature is present] the [system] SHALL [response] | Behavior gated behind an optional capability or flag |
+| Unwanted-behavior | IF / THEN | IF [undesired condition] THEN the [system] SHALL [response] | Errors, failures, invalid input, timeouts |
+| Complex | combination | WHILE [state], WHEN [trigger] the [system] SHALL [response] | Richer behavior combining the above |
+
+**Why patterns beat one shape:** failure states, state transitions, and optional behavior become first-class criteria instead of footnotes squeezed into WHEN/THEN. The patterns map onto the implicit-requirement dimensions above: state-transition integrity to State-driven; failure and external-dependency failure to Unwanted-behavior; feature flags to Optional-feature.
+
+**Rules:** one requirement per criterion (never bundle two behaviors); use concrete values (a specific status code, a specific message, a bound) rather than "quickly" or "gracefully"; every criterion contains a SHALL and is measurable. `python3 <skill-dir>/scripts/validate_spec.py` flags any criterion without a SHALL and any that matches no recognized pattern.
+
+### 4. Requirement Closure Gate (before confirm)
+
+Before presenting the spec for confirmation, run the three checks below. The spec is not presentable for confirmation until every item is resolved or assumption-logged - this is the guarantee that no requirement leaves the spec silently unclear.
+
+**Scope-tiered:** Large/Complex = full gate; Medium = resolve obvious ambiguities, log the rest as assumptions; Small = skip entirely (consistent with skipping the sweep).
+
+1. **Unambiguity + precision (hard).** Every AC must (a) have a single interpretation and (b) define a precise, spec-defined expected outcome. Any AC that fails either check: resolve with the user, split it, or log it as an explicit assumption with the chosen interpretation and rationale. No AC proceeds readable two ways or with an undefined outcome.
+
+2. **Open-questions / assumptions closure.** Enumerate every unresolved decision that surfaced during clarification. Each must be either (a) resolved with the user OR (b) recorded as an **assumption** (chosen default + rationale) in the spec's Assumptions & Open Questions section. Nothing proceeds unmarked.
+
+3. **Declined gray areas become assumptions.** Any gray area the user declined to discuss or that went undiscussed is written to the spec's Assumptions & Open Questions section (agent's chosen default + rationale) - never silently dropped. See [discuss.md](discuss.md).
+
+Fix inline. This gate is bounded to THIS feature's stated dimensions and actual behavior - never to "anything imaginable." The Out of Scope table and anti-scope-creep rules remain the counterweights: the gate clarifies existing requirements, it never invents new ones.
+
+**Deterministic backing (run before you present the spec).** The structural half of this gate is enforced by a script so it cannot drift when a step is forgotten: `python3 <skill-dir>/scripts/validate_spec.py <spec-path-or-feature>` checks that required sections exist, every AC is EARS-shaped (has a SHALL), no Assumptions row has an empty default or rationale, and requirement IDs are well-formed. A non-zero exit means fix before confirming. The script checks structure; you still own the judgment calls (is the interpretation right, is the outcome precise). If no code-execution tool is available, run the same checks by reading the spec.
+
+---
+
+## Template: `.specs/features/[feature]/spec.md`
+
+```markdown
+# [Feature Name] Specification
+
+## Problem Statement
+
+[Describe the problem in 2-3 sentences. What pain point are we solving? Why now?]
+
+## Goals
+
+- [ ] [Primary goal with measurable outcome]
+- [ ] [Secondary goal with measurable outcome]
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature     | Reason         |
+| ----------- | -------------- |
+| [Feature X] | [Why excluded] |
+| [Feature Y] | [Why excluded] |
+
+---
+
+## Assumptions & Open Questions
+
+Every ambiguity is resolved or recorded here - nothing is left silently unclear.
+
+| Assumption / decision | Chosen default  | Rationale | Confirmed? |
+| --------------------- | --------------- | --------- | ---------- |
+| [ambiguity]           | [what we'll do] | [why]     | [y/n]      |
+
+**Open questions:** none - all resolved or logged above (required before the spec is confirmed).
+
+---
+
+## User Stories
+
+### P1: [Story Title] ⭐ MVP
+
+**User Story**: As a [role], I want [capability] so that [benefit].
+
+**Why P1**: [Why this is critical for MVP]
+
+**Acceptance Criteria** (each line is one EARS pattern):
+
+1. WHEN [user action/event] THEN system SHALL [expected behavior]  <!-- event-driven -->
+2. IF [invalid input / failure] THEN system SHALL [graceful handling]  <!-- unwanted-behavior -->
+3. WHILE [state holds] system SHALL [behavior during that state]  <!-- state-driven -->
+4. The system SHALL [always-on invariant]  <!-- ubiquitous -->
+
+**Independent Test**: [How to verify this story works alone - e.g., "Can demo by doing X and seeing Y"]
+
+---
+
+### P2: [Story Title]
+
+**User Story**: As a [role], I want [capability] so that [benefit].
+
+**Why P2**: [Why this isn't MVP but important]
+
+**Acceptance Criteria**:
+
+1. WHEN [event] THEN system SHALL [behavior]
+2. WHEN [event] THEN system SHALL [behavior]
+
+**Independent Test**: [How to verify]
+
+---
+
+### P3: [Story Title]
+
+**User Story**: As a [role], I want [capability] so that [benefit].
+
+**Why P3**: [Why this is nice-to-have]
+
+**Acceptance Criteria**:
+
+1. WHEN [event] THEN system SHALL [behavior]
+
+---
+
+## Edge Cases
+
+Edge cases are usually unwanted-behavior (IF/THEN) or boundary (WHEN) criteria:
+
+- IF [error scenario] THEN system SHALL [graceful handling]
+- IF [unexpected input] THEN system SHALL [validation response]
+- WHEN [boundary condition] THEN system SHALL [behavior]
+
+---
+
+## Requirement Traceability
+
+Each requirement gets a unique ID for tracking across design, tasks, and validation.
+
+| Requirement ID | Story       | Phase  | Status  |
+| -------------- | ----------- | ------ | ------- |
+| [FEAT]-01      | P1: [Story] | Design | Pending |
+| [FEAT]-02      | P1: [Story] | Design | Pending |
+| [FEAT]-03      | P2: [Story] | -      | Pending |
+
+**ID format:** `[CATEGORY]-[NUMBER]` (e.g., `AUTH-01`, `CART-03`, `NOTIF-02`)
+
+**Status values:** Pending → In Design → In Tasks → Implementing → Verified
+
+**Coverage:** X total, Y mapped to tasks, Z unmapped ⚠️
+
+---
+
+## Success Criteria
+
+How we know the feature is successful:
+
+- [ ] [Measurable outcome - e.g., "User can complete X in < 2 minutes"]
+- [ ] [Measurable outcome - e.g., "Zero errors in Y scenario"]
+```
+
+---
+
+## Tips
+
+- **P1 = Vertical Slice** - A complete, demo-able feature, not just backend or frontend
+- **EARS is code** - If you can't write a criterion as a test, rewrite it; pick the pattern (WHEN / WHILE / WHERE / IF / ubiquitous) that fits
+- **Requirement IDs are mandatory** - Every story maps to trackable IDs
+- **Edge cases matter** - What breaks? What's empty? What's huge?
+- **Out of Scope prevents creep** - If it's not here, it doesn't get built
+- **Closure gate before confirm** - Three checks: unambiguity + precision, open-questions/assumptions closure, declined gray areas logged; scope-tiered; bounded to stated dimensions; never invents requirements
+- **Confirm after the gate passes** - Present the spec for user confirmation only after the closure gate passes (no unresolved-and-unmarked items remain) and `validate_spec.py` exits clean; user approves spec before moving to discuss phase

package/framework/skills/tlc-spec-driven/references/sub-agents.md

@@ -0,0 +1,147 @@
+# Sub-Agent Delegation
+
+Full mechanics for phase-batch workers and the Verifier sub-agent used during Execute.
+
+## Phase-Batch Workers
+
+**Two layers - keep them distinct:**
+
+- **Phase** = the semantic / dependency unit (Foundation → Core → Integration), authored during Tasks. Indivisible.
+- **Batch** = the execution / logistics unit - one or more *consecutive whole phases* assigned to a single worker.
+
+Conflating the two (one worker per phase) is what fragments execution: a feature's dependency-layer count has nothing to do with the ideal per-worker workload. Batching by task budget separates the two concerns without breaking phases.
+
+**Trigger:** Count total tasks across all phases. If the feature packs into **more than one batch** (> ~8 tasks), offer the user phase-batch sub-agents before starting Execute. If it fits a single batch (≤ ~8 tasks), execute inline in the main window - no sub-agents spawned.
+
+**Batching algorithm (task budget ≈ 7 tasks/worker, phase-aligned):**
+
+The benchmarked sweet spot is ~7 tasks of context per worker (~20 tasks → 3 workers). Pack whole phases into that budget:
+
+1. Count total tasks `T`.
+2. If `T ≤ ~8` → inline, no sub-agents.
+3. Otherwise walk phases **in order**, accumulating whole phases into the current batch. When the batch's running task count reaches ~7 **and** phases remain, close the batch and start the next.
+4. **Never split a phase** across workers - the cut only ever lands on a phase boundary. This preserves dependency ordering and keeps a phase's tasks + shared context in one worker.
+5. If the final batch is a lone tail (1-2 tasks), fold it into the previous batch.
+
+Result ≈ `ceil(T / 7)` workers, scaling linearly. Unevenness is absorbed by greedy packing - phases never need to divide evenly. Worked examples (20 tasks):
+
+- Phases `[3,3,3,3,4,4]` → `{P1+P2=6, P3+P4=6, P5+P6=8}` = **3 workers**
+- Phases `[8,2,2,8]` → `{P1=8, P2+P3=4, P4=8}` = **3 workers** (no even split needed)
+- Phases `[5,5,5,5]` → `{P1+P2=10, P3+P4=10}` = **2 workers** (phases too coarse to hit 3 - see below)
+
+**Coarse-phase caveat:** Because the cut lands only on phase boundaries, very coarse phases limit how finely you can pack. If a single phase alone exceeds ~1.5× the budget (~10+ tasks), that is a Tasks-authoring smell - split it into real sub-phases during Tasks (at a genuine dependency/cohesion boundary), never at dispatch time.
+
+**Offer-then-confirm (never auto-spawn):**
+
+> "This feature has [T] tasks across [N] phases. I can pack them into [K] sub-agents (~7 tasks each, whole phases per worker) - every worker runs its phases in order, reports a compact summary, and the orchestrator advances to the next batch. This keeps the main window lean without over-fragmenting. Want to proceed that way?"
+
+The user must explicitly accept. If they decline (or if the feature fits one batch), execute inline.
+
+**Execution model - one worker per task-budgeted batch, sequential:**
+
+```
+Phases 1+2 (7 tasks)  ------→ Batch Worker 1 ------→ compact summary ------→ orchestrator updates tasks.md
+Phases 3+4 (6 tasks)  ------→ Batch Worker 2 ------→ compact summary ------→ orchestrator updates tasks.md
+Phase 5    (7 tasks)  ------→ Batch Worker 3 ------→ compact summary ------→ orchestrator updates tasks.md
+...
+```
+
+Batches run strictly sequentially: a batch never starts until the previous batch's summary shows all its tasks complete.
+
+**What a batch worker receives:**
+
+- The task definitions for **every** phase in its batch (from `tasks.md`)
+- The Test Coverage Matrix and Gate Check Commands (from `tasks.md`)
+- `references/coding-principles.md`
+- Relevant `spec.md` and `design.md` context for the feature (not all specs)
+
+**What a batch worker does:**
+
+Executes ALL tasks in its assigned batch **in order** - finishing every task in one phase before starting the next phase in the batch - following the `implement.md` cycle for each task (implement → gate → atomic commit). It does NOT spawn further sub-agents. After completing all tasks in the batch, the worker reports a **compact summary** to the orchestrator:
+
+```
+Batch (phases [N]-[M]) complete:
+- Tasks done: [list with commit hashes]
+- Tests: [N passed, 0 failed]
+- Deviations/blockers: [none | description]
+```
+
+No raw logs, no full test output - only the above fields keep the main context clean.
+
+**No nesting:** Batch workers execute their tasks themselves. They never spawn sub-sub-agents. Execution is strictly sequential within and across batches - there is no intra-phase or intra-batch parallelism.
+
+**The orchestrating agent's role during Execute:**
+
+1. Count total tasks and pack phases into task-budgeted batches (~7 tasks each) - if that yields more than one batch, offer batch sub-agents and wait for the user to accept
+2. Dispatch the next batch to a worker (or execute inline if not using sub-agents)
+3. Receive the compact summary
+4. Update `tasks.md` with results
+5. If all tasks in the summary show complete: dispatch the next batch
+6. If a task failed: the worker has already stopped; decide fix/escalate before dispatching the next batch
+
+**Failure handling:** If a task in a batch fails (gate does not pass, blocker hit), the worker stops and includes the failure in its summary. The next batch does not start until the current batch's summary shows all tasks complete. The orchestrator decides: fix and re-run, or escalate to the user.
+
+**Context sizing signal:** If a batch's task list would likely push the worker's context beyond ~40k tokens, close the batch at an earlier phase boundary (fewer phases per worker). If a *single* phase alone would blow the budget, that phase is too coarse - split it during Tasks per the granularity guidance in `references/tasks.md`.
+
+---
+
+## Verifier Sub-Agent
+
+**Always-on, never prompted - one per feature completion.** The Verifier is a separate role from the batch worker. It runs once - after the last task of the feature is committed - as an independent quality gate, dispatched automatically by the orchestrator. It is **not** gated behind the batching offer; it always runs. Do NOT ask the user whether to run validation; it is mandatory.
+
+**Author ≠ verifier:** The agent (or batch worker) that wrote the code and tests is the author. The Verifier is a fresh sub-agent dispatched by the orchestrator after the final commit. It does not inherit the author's context, mental model, or assumptions. This separation is what makes the gate trustworthy.
+
+**What the Verifier receives:**
+- `spec.md` for the feature (ACs = source of truth)
+- The git diff surface for the feature (scoped to the feature branch or commit range)
+- The test files in scope
+- `references/validate.md` as its operating checklist
+
+**What the Verifier does (full process in `validate.md`):**
+1. **Spec-anchored coverage check** - re-derives coverage evidence-or-zero: every AC traced to `file:line` + assertion expression. For each covered criterion, confirms the test's asserted value matches the **spec-defined expected outcome** (not just that an assertion exists). Where the spec does not define a precise outcome, flags a **spec-precision gap** rather than passing silently.
+2. **Discrimination sensor** - injects a small behavior-level fault (flip a condition, change a return value, off-by-one, remove a required side effect) in an **isolated scratch** (temporary `git worktree` or temp file copies - never `git stash`), runs the relevant tests there, confirms they FAIL (kill the mutant), discards the scratch, and verifies the real worktree's `git status --porcelain` matches the pre-sensor baseline. Tiered by risk: lightweight (1-3 mutations) for standard features; expanded (≥5 mutations or full mutation tooling) for P0/critical paths. Surviving mutants become fix tasks.
+3. Applies the **payload/conjunction rule**: checks payload fields are asserted on value/state, not just that the call occurred.
+4. **Writes the persisted report** to `.specs/features/[feature]/validation.md` - PASS/FAIL, per-AC evidence (`file:line` + assertion + spec outcome), sensor result (killed/survived per mutation), gate exit results, diff/commit range.
+5. **Returns a compact verdict in chat** to the orchestrator.
+6. Does **NOT** write, modify, or fix any code or tests - the real working tree is never mutated (sensor mutations run in scratch state only).
+
+**What the Verifier reports back (compact chat format):**
+```
+## Validation: [feature name] - [PASS ✅ | FAIL ❌]
+
+**Spec-anchored check**: [N/N ACs matched spec outcome | M spec-precision gaps flagged]
+**Gate**: [X passed, 0 failed]
+**Sensor**: [N mutations injected, N killed, N survived]
+**Report**: `.specs/features/[feature]/validation.md`
+
+**Ranked gaps** (if FAIL):
+1. [Gap description] - [AC or criterion] - [file:line or "no evidence"]
+2. ...
+```
+
+**Failure handling:** The orchestrator routes the ranked gaps to an implementer as fix tasks, then re-dispatches the Verifier. This fix→re-verify loop is bounded to a maximum of **3 iterations**. If gaps remain after 3 iterations, escalate to the user.
+
+**Standalone fallback:** When running without sub-agents (a single agent executing the full feature), run `validate.md` as an independent fresh-eyes pass - re-read `spec.md` and the diff from scratch, apply evidence-or-zero, run the spec-anchored check and discrimination sensor, write the report file, then run `python3 <skill-dir>/scripts/validate_state.py <feature>` to confirm the report is a real PASS, and report PASS/FAIL before marking the feature done.
+
+---
+
+## Model Tier per Role
+
+**Applies only if the harness can assign a model per sub-agent.** If it cannot, ignore this section and run everything on the default model - the workflow is correct either way. The point is to spend high-reasoning capacity where ambiguity and consequence are high, and a faster tier where the work is mechanical, instead of paying top-tier cost uniformly.
+
+Judge the tier by the work in front of the role, not by the role's title:
+
+| Role / work | Characteristic | Suggested tier |
+| ----------- | -------------- | -------------- |
+| Design phase | High ambiguity, hard-to-reverse structural decisions | High-reasoning |
+| Batch worker - core-domain or high-ambiguity phase | Non-obvious logic, tricky edge cases, novel integration | High-reasoning |
+| Batch worker - mechanical phase | Entities, DTOs, config, wiring, straightforward CRUD against a settled pattern | Faster / cheaper |
+| Verifier | Adversarial reasoning: designs mutations, re-derives coverage, judges outcome precision | Mid-to-high |
+| Specify / Tasks authoring | Structured but judgment-heavy | Mid-to-high |
+
+**Rules of thumb:**
+
+- When unsure, size up, not down. An under-powered worker on ambiguous logic produces gaps the Verifier then has to catch - more expensive than paying for reasoning once.
+- The Verifier is never the cheapest tier; a weak Verifier defeats the author ≠ verifier gate.
+- Set the tier per batch, from that batch's phases. A feature can mix tiers across batches.
+- This is advisory metadata only. No gate, commit, or verification step depends on it.