@minhduydev/mdpi 0.3.0

package/dist/template/.pi/skills/jira/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: jira
+description: Use when interacting with Jira issues or Confluence docs — searching tickets, creating issues, updating status, or reading wiki pages. MUST load before any Atlassian integration. Requires network access to Atlassian MCP.
+---
+
+# Jira & Confluence Integration (MCP)
+
+## When to Use
+
+- When you need to search or update Jira/Confluence content via Atlassian MCP.
+
+## When NOT to Use
+
+- When the project does not use Atlassian Cloud or MCP access is unavailable.
+
+
+## Key Features
+
+- **OAuth 2.1 Authorization** - Secure browser-based authentication
+- **Rovo Search** - Unified search across Jira and Confluence
+- **Real-time Data** - Direct connection to Atlassian Cloud
+- **Permission-aware** - Respects existing user access controls
+
+## Available Tools
+
+### Universal Search (Recommended)
+
+- `search` - **Rovo Search** - Search Jira and Confluence content (use this by default)
+- `fetch` - Get details by ARI (Atlassian Resource Identifier) from search results
+
+### Jira
+
+- `getJiraIssue` - Get issue details by key or ID
+- `createJiraIssue` - Create new issues
+- `editJiraIssue` - Update existing issues
+- `transitionJiraIssue` - Change issue status
+- `addCommentToJiraIssue` - Add comments to issues
+- `addWorklogToJiraIssue` - Log work time
+- `searchJiraIssuesUsingJql` - Search with JQL queries
+- `getTransitionsForJiraIssue` - Get available status transitions
+- `getVisibleJiraProjects` - List accessible projects
+- `getJiraProjectIssueTypesMetadata` - Get issue types for a project
+- `getJiraIssueTypeMetaWithFields` - Get field metadata for issue type
+- `getJiraIssueRemoteIssueLinks` - Get remote links
+- `lookupJiraAccountId` - Find user account IDs
+
+### Confluence
+
+- `getConfluencePage` - Get page content by ID
+- `createConfluencePage` - Create new pages
+- `updateConfluencePage` - Update existing pages
+- `searchConfluenceUsingCql` - Search with CQL queries
+- `getConfluenceSpaces` - List spaces
+- `getPagesInConfluenceSpace` - List pages in a space
+- `getConfluencePageDescendants` - Get child pages
+- `getConfluencePageFooterComments` - Get footer comments
+- `getConfluencePageInlineComments` - Get inline comments
+- `createConfluenceFooterComment` - Add footer comment
+- `createConfluenceInlineComment` - Add inline comment on specific text
+
+### Utility
+
+- `atlassianUserInfo` - Get current user info
+- `getAccessibleAtlassianResources` - Get cloudId for API calls
+
+## Quick Start
+
+### 1. Configuration
+
+The MCP server uses OAuth 2.1 - no API tokens needed. Configuration in `mcp.json`:
+
+```json
+{
+  "jira": {
+    "command": "npx",
+    "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"]
+  }
+}
+```
+
+### 2. Get Cloud ID
+
+Most tools require a `cloudId`. Get it from your site URL or use the utility:
+
+```typescript
+// Get accessible resources and cloudId
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "getAccessibleAtlassianResources"),
+  (arguments = "{}"),
+);
+```
+
+Or use your site URL directly as cloudId (e.g., `"ibet.atlassian.net"`).
+
+### 3. Use MCP Tools
+
+```typescript
+// Universal search (recommended for discovery)
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "search"),
+  (arguments = '{"query": "authentication bug"}'),
+);
+
+// Get issue details
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "getJiraIssue"),
+  (arguments = '{"cloudId": "your-site.atlassian.net", "issueIdOrKey": "PROJ-123"}'),
+);
+
+// Search with JQL
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "searchJiraIssuesUsingJql"),
+  (arguments = '{"cloudId": "your-site.atlassian.net", "jql": "project = PROJ AND status = Open"}'),
+);
+
+// Create issue
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "createJiraIssue"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "projectKey": "PROJ", "issueTypeName": "Bug", "summary": "Login fails on mobile"}'),
+);
+
+// Transition issue status
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "transitionJiraIssue"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "issueIdOrKey": "PROJ-123", "transition": {"id": "21"}}'),
+);
+
+// Get Confluence page
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "getConfluencePage"),
+  (arguments = '{"cloudId": "your-site.atlassian.net", "pageId": "123456789"}'),
+);
+
+// Search Confluence with CQL
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "searchConfluenceUsingCql"),
+  (arguments = '{"cloudId": "your-site.atlassian.net", "cql": "title ~ \"Onboarding\""}'),
+);
+```
+
+## Common Workflows
+
+### Daily Standup
+
+```typescript
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "searchJiraIssuesUsingJql"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "jql": "assignee = currentUser() AND updated >= -1d"}'),
+);
+```
+
+### Bug Triage
+
+```typescript
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "searchJiraIssuesUsingJql"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "jql": "type = Bug AND priority in (High, Critical) AND status != Done"}'),
+);
+```
+
+### Sprint Planning
+
+```typescript
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "searchJiraIssuesUsingJql"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "jql": "project = PROJ AND sprint in openSprints()"}'),
+);
+```
+
+### Quick Discovery with Rovo Search
+
+```typescript
+// Best for finding content when you don't know exact location
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "search"),
+  (arguments = '{"query": "authentication implementation"}'),
+);
+
+// Then fetch details using ARI from results
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "fetch"),
+  (arguments = '{"id": "ari:cloud:jira:cloudId:issue/10107"}'),
+);
+```
+
+## JQL Examples
+
+```sql
+-- My open issues
+assignee = currentUser() AND status != Done
+
+-- High priority bugs
+project = PROJ AND type = Bug AND priority in (High, Critical)
+
+-- Recently updated
+project = PROJ AND updated >= -7d
+
+-- Current sprint
+project = PROJ AND sprint in openSprints()
+
+-- Unassigned in backlog
+project = PROJ AND assignee is EMPTY AND status = "To Do"
+```
+
+## CQL Examples (Confluence)
+
+```sql
+-- Pages with title containing "guide"
+title ~ "guide"
+
+-- Pages in specific space
+space = "TEAM" AND type = page
+
+-- Recently modified
+lastModified >= now("-7d")
+
+-- Pages by creator
+creator = currentUser()
+```
+
+## Content Format Options
+
+For Confluence pages, you can specify content format:
+
+- `"markdown"` - Markdown format (easier to read/write)
+- `"adf"` - Atlassian Document Format (native format)
+
+```typescript
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "getConfluencePage"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "pageId": "123456", "contentFormat": "markdown"}'),
+);
+```
+
+## Transition Workflow
+
+To change issue status, first get available transitions:
+
+```typescript
+// 1. Get available transitions
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "getTransitionsForJiraIssue"),
+  (arguments = '{"cloudId": "your-site.atlassian.net", "issueIdOrKey": "PROJ-123"}'),
+);
+
+// 2. Use transition ID to change status
+skill_mcp(
+  (skill_name = "jira"),
+  (tool_name = "transitionJiraIssue"),
+  (arguments =
+    '{"cloudId": "your-site.atlassian.net", "issueIdOrKey": "PROJ-123", "transition": {"id": "31"}}'),
+);
+```
+
+## Resources
+
+- GitHub: https://github.com/atlassian/atlassian-mcp-server
+- Docs: https://www.atlassian.com/platform/remote-mcp-server
+- Admin Guide: https://support.atlassian.com/security-and-access-policies/docs/understand-atlassian-rovo-mcp-server/
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll update Jira after the work is done" | Real-time updates prevent status misalignment. Update as you work. |
+| "The ticket has enough information" | Underspecified tickets produce wrong implementations. Clarify before starting. |
+| "I don't need to link PRs to tickets" | Traceability from ticket to code is the foundation of project visibility. |
+
+## Red Flags
+
+- Ticket status not updated for >24 hours during active work
+- Implementation deviates significantly from ticket description
+- PR merged without linking to Jira ticket
+- Acceptance criteria in ticket ignored during implementation
+- Multiple tickets worked simultaneously without status tracking
+
+## Verification
+
+After completing Jira-linked work:
+
+- [ ] Ticket status reflects actual work state
+- [ ] PR is linked to the Jira ticket
+- [ ] Acceptance criteria in the ticket are all satisfied
+- [ ] Comments on the ticket document key decisions made during implementation
+- [ ] Time tracking (if used) is updated

package/dist/template/.pi/skills/loop-audit/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: loop-audit
+description: Use when scoring a project's loop-engineering readiness 0-100 + L0/L1/L2/L3 from concrete repo signals (state file, verifier/gate, loop skills, safety docs, GitHub workflows, MCP, worktree evidence, cost observability, real loop activity). Emits a numeric score, a level, and ≥1 recommendation. L3 is gated on a proven committed run.
+---
+
+# Loop Audit
+
+Readiness scoring for loop-engineering. A loop is a system that prompts an agent on a schedule; before you trust one to run unattended, measure whether the project is actually loop-ready. This skill converts concrete repo signals into a **reproducible 0-100 score** and a **L0/L1/L2/L3 level**, then emits ≥1 recommendation. The score is computed from a fixed rubric (below) — it is not an opinion. L3 is capped at L2 until a real cycle has been run and committed.
+
+## When to Use
+
+- Before wiring a loop to run unattended (cron/launchd/GitHub Actions `on: schedule`).
+- Before promoting a loop from supervised to unattended.
+- On a cadence, to detect readiness drift (skills deleted, guard unregistered, state file dropped).
+- When a stakeholder asks "is this project ready to loop?"
+
+## When NOT to Use
+
+- A single interactive change with no schedule or repetition (no loop to score).
+- Scoring the *correctness* of loop output — that is `/loop-review`'s job (exit-code evidence). This skill scores *readiness*, not output quality.
+
+## The Signals
+
+Each signal is a concrete, checkable artifact. Check the repo; mark present/absent; sum the points. No signal is subjective — if you cannot point to a file/line, the signal is absent.
+
+| # | Signal | What counts as present | Points |
+|---|---|---|---|
+| 1 | **State file present** | A loop state ledger exists and is non-empty: `.pi/loops/*/STATE.json` (or `STATE.md`) with `processed`, `in_progress`, `completed`, `failures`, `lessons`, `metrics`, `last_run`, `stop_conditions_met`. A blank/template file scores 0. | 12 |
+| 2 | **Verifier/gate present** | An objective gate command is named in a VISION/contract file (`Gate:` section of `.pi/loops/*/VISION.md`) OR a gate script exists (e.g. `scripts/loop-gate.sh`, `npm test` referenced by the orchestrator). The gate must be a real command whose exit code decides pass/fail. | 14 |
+| 3 | **Loop skills present** | Count of loop-* skills/prompts installed: `loop-engineering`, `loop-audit`, `loop-cost`, `/loop-check`, `/loop-review`, `/loop-init`. 0 → 0; 1-2 → 4; 3-4 → 8; 5-6 → 12. | 12 |
+| 4 | **Safety docs** | Never-do rules + security checklist documented (in `loop-engineering` skill or a loop's `SKILL.md`): refuse-list (auth/payments/architecture), path protection, dangerous-cmd block, human-approval-required. | 10 |
+| 5 | **GitHub workflows** | A loop CI workflow exists: `.github/workflows/*loop*` referencing `pi -p` and `on: schedule`, OR the `loop-github-action.yml` template is present. | 10 |
+| 6 | **MCP / tool_call hook** | A `tool_call` hook is registered (`.pi/extensions/loop-guard.ts` in `.pi/settings.json` `extensions[]`) OR an MCP adapter is wired for loop tools. Capability-deprivation (`--tools` allowlist) documented in the orchestrator counts. | 8 |
+| 7 | **Worktree evidence** | The orchestrator uses `git worktree add` for isolation (grep the orchestrator source/template for `worktree`). | 10 |
+| 8 | **Cost observability** | Both: (a) a budget/cost doc or estimate (e.g. `loop-cost` output, a `BUDGET.md`, a cap value in the orchestrator) AND (b) a per-run log exists (a `logs/` or `.pi/loops/*/logs/` dir with at least one run log). One without the other → 6. | 12 |
+| 9 | **Real loop activity** | A proven committed run: `STATE.json.last_run` set AND at least one item in `processed[]`/`completed[]` AND a git commit/PR attributable to the loop (branch `loop/<name>/<ts>` merged or open). A scaffolded-but-never-run loop scores 0 here. | 12 |
+| | **Total** | | **100** |
+
+## Scoring (0-100 → level)
+
+Compute the raw score by summing the present signals (0-100). Then map to a level.
+
+| Level | Raw score | Extra requirements |
+|---|---|---|
+| **L0** — nothing real | 0-29 | (none) |
+| **L1** — structure, not yet run | 30-54 | (none) |
+| **L2** — capable but unproven | 55-77, **OR** score ≥78 but missing any L3 gate requirement | (none) |
+| **L3** — proven, gated, ready for unattended | ≥78 **AND** verifier/gate present (signal 2) **AND** state file present (signal 1) **AND** cost-ready (signal 8 full) **AND** real loop activity (signal 9) | **All four gate requirements must hold.** |
+
+### The L3 gate (hard)
+
+L3 is **capped at L2** until a real cycle has been run and committed. Structure alone — no matter how complete — cannot earn L3. The four gate requirements are conjunctive:
+
+1. **Verifier/gate present** (signal 2, ≥14 available; must be present at all).
+2. **State file present** (signal 1; a populated, non-template ledger).
+3. **Cost-ready** (signal 8 full — both budget doc *and* run log).
+4. **Proven committed run** (signal 9 — a real cycle, committed, not a scaffold).
+
+If raw score ≥78 but any gate requirement is missing → **L2** with a recommendation naming the missing requirement. This is the anti-Ralph-Wiggum guard: a project that *looks* ready but has never actually run a cycle is not trusted to run unattended.
+
+> **Scenario (FR4):** project has structure (score 80) but no proven runs → **L2** with recommendation "run one L1 cycle and commit state before L3".
+
+## Output Contract
+
+The skill always emits three things — no exceptions:
+
+1. **Score:** the integer 0-100, with a one-line breakdown (which signals were present and their points). Reproducible: another agent re-running the rubric on the same repo must get the same number.
+2. **Level:** one of `L0`, `L1`, `L2`, `L3`. If the raw score would map to L3 but a gate requirement fails, state the **capped** level (L2) and name the failed gate requirement.
+3. **Recommendations:** ≥1 concrete, actionable next step tied to a missing/weak signal. Each recommendation cites the signal it would raise and the points recoverable. Never empty.
+
+Output shape (markdown):
+
+```markdown
+# Loop Readiness Audit
+
+**Score:** 64/100
+**Level:** L2 (capped from L3 — missing proven committed run)
+
+## Breakdown
+| Signal | Present? | Points |
+|---|---|---|
+| State file | ✅ | 12 |
+| Verifier/gate | ✅ | 14 |
+| Loop skills | ✅ (4/6) | 8 |
+| Safety docs | ✅ | 10 |
+| GitHub workflows | ❌ | 0 |
+| MCP/tool_call hook | ✅ | 8 |
+| Worktree evidence | ✅ | 10 |
+| Cost observability | ⚠ partial (budget doc only) | 6 |
+| Real loop activity | ❌ | 0 |
+| **Total** | | **64** |
+
+## Gate check (L3)
+- Verifier/gate: ✅
+- State file: ✅
+- Cost-ready (both): ❌ (no run log)
+- Proven committed run: ❌
+→ Capped at L2.
+
+## Recommendations
+1. Add `.github/workflows/loop-*.yml` with `on: schedule` + `pi -p` to recover +10 (signal 5) and unblock CI unattended runs.
+2. Run one supervised L1 cycle end-to-end and commit `STATE.json` (branch `loop/<name>/<ts>` + PR) to recover +12 (signal 9) and satisfy the L3 proven-run gate.
+3. Emit per-run logs to `.pi/loops/*/logs/` to complete cost observability (+6, signal 8) and satisfy the cost-ready gate requirement.
+```
+
+## Verification
+
+Before claiming an audit is complete:
+
+- [ ] The output contains a numeric score 0-100 and a reproducible breakdown (every signal marked present/absent/partial with its points).
+- [ ] The output contains a level L0/L1/L2/L3. If L3 is claimed, all four gate requirements are explicitly checked and present.
+- [ ] The output contains ≥1 recommendation, each tied to a missing/weak signal with recoverable points.
+- [ ] A second pass over the same repo yields the same score (rubric is deterministic — disagreement means a signal was scored subjectively; re-check the artifact).
+- [ ] L3 is never awarded without a proven committed run (signal 9 present AND a `loop/<name>/<ts>` branch/PR exists in git).
+
+## See Also
+
+| Companion | Role |
+|---|---|
+| `loop-engineering` | Methodology this skill scores against (2-condition test, 5 building blocks) |
+| `/loop-check` | NO-GO qualification gate (run *before* a loop, not after) |
+| `/loop-review` | Maker/checker — scores a *run's* output via exit code, not project readiness |
+| `loop-cost` | Cost estimation feeding the cost-observability signal (8) |
+| `loop-orchestrator.ts`/`.sh` | Runtime whose worktree/gate/state usage signals 1, 2, 7 detect |
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "We scaffolded the whole kit, that's L3" | Structure without a proven committed run is L2 max. The gate exists to prevent this exact claim. |
+| "The score feels low" | The score is the rubric. Re-check the artifacts; if a signal is absent, it's 0 — no partial credit for "almost". |
+| "We ran a loop once manually, that's proven" | Manual ≠ committed. Proven requires a committed cycle (branch + PR/commit attributable to the loop). |
+| "L3 just needs a high score" | L3 needs score ≥78 **and** all four gate requirements. High score alone caps at L2. |
+
+## Red Flags
+
+- An L3 score with no `loop/<name>/<ts>` branch or PR in git history (gate failed; cap to L2).
+- A score with no breakdown table (not reproducible — redo the audit).
+- Zero recommendations (the contract requires ≥1; an empty recommendation list means the audit is incomplete).
+- A signal marked present with no file/line citation (subjective scoring; re-check).
+- Cost observability scored full with only a budget doc and no run log (signal 8 requires both).

package/dist/template/.pi/skills/loop-cost/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: loop-cost
+description: Use when estimating tokens/day for an unattended coding loop before it ships — computes cadence × realistic blend per L1/L2/L3, a suggested daily cap, and the early-exit-required flag (early-exit on empty watchlist < 5k tokens). Load before approving a loop's budget or setting a per-run cap.
+---
+
+# Loop Cost
+
+Token-budget skill for unattended coding loops. Answers the budget half of the loop-engineering 2-condition test: *is the cost of one wasted run small enough that the cadence does not bankrupt you?* Produces a tokens/day estimate, a suggested daily cap, and an early-exit flag the orchestrator (`loop-orchestrator.ts`) consumes from `--mode json` token events (FR13).
+
+## When to Use
+
+- You are about to qualify or ship an unattended loop and need to set a per-run cap.
+- An orchestrator asks for a daily budget number before registering a cron/GitHub Actions schedule.
+- You are sizing whether a no-op (watchlist empty) run is cheap enough to schedule hourly.
+- You are revising a cap after cadence or level changes (e.g., L2 triage promoted to L3 fix loop).
+
+## When NOT to Use
+
+- Interactive single runs with a human watching every turn — no cadence, no budget problem.
+- Estimating dollar cost or latency — this is tokens only; multiply by model price elsewhere.
+- Choosing loop qualification or confidence thresholds — those live in `loop-engineering` and `loop-guard`.
+
+## The Blend Model
+
+A loop's per-run cost is not a single number; it is a **blend** over what actually happens across runs. Each loop is assigned one Level; within that Level, runs distribute across three outcomes:
+
+| Level | Early-exit (watchlist empty / no-op) | Triage (diagnosis-only, no fix) | Full fix (edit + verify) |
+| ----- | ------------------------------------ | ------------------------------- | ------------------------ |
+| **L1** | 90% | 10% | — |
+| **L2** | 85% | 10% | 5% |
+| **L3** | 40% | 35% | 25% |
+
+**Per-run token estimates (assumptions — state yours explicitly and override for your stack):**
+
+- **Early-exit:** 2,000 tokens (read watchlist, confirm empty, write state, exit).
+- **Triage:** 12,000 tokens (read failure, reproduce attempt, write diagnosis-only comment, no edits).
+- **Full fix:** 80,000 tokens (read + reproduce + edit + run gate + revise + post).
+
+These are starting points for a pi 0.79.x maker on a mid-size TS/JS repo with a passing gate. For larger repos, heavier languages, or failing gates, raise them. Always state the assumptions used so the arithmetic is reproducible.
+
+**Expected tokens per run** = blend:
+
+```
+E[run] = p_early * T_early + p_triage * T_triage + p_fix * T_fix
+```
+
+where `p_*` are the Level's percentages (as fractions) and `T_*` the per-run estimates above.
+
+## Daily Cap Formula
+
+Given a **cadence** (runs/day) and a Level, the daily budget is:
+
+```
+tokens_per_day = cadence_per_day * E[run]
+suggested_daily_cap = ceil(tokens_per_day * safety_factor)
+```
+
+- **cadence_per_day**: scheduled runs in 24h. Hourly = 24, every-15-min = 96, nightly = 1, weekdays-only nightly = ~22.
+- **safety_factor**: 1.5 default. The blend is an *expectation*; real days cluster worse (a flaky CI + a real bug in one day). 1.5 covers one bad day without doubling cost. Lower to 1.25 for well-observed stable loops; raise to 2.0 for new loops with unknown variance.
+- **per_run_cap**: set on the orchestrator's `--mode json` token watcher to `safety_factor * T_fix` (the worst single-run case), not the blend — a single run that blows past `T_fix` is a runaway, not a bad day. FR13's "exceeds a per-run cap" kill trigger uses this number.
+
+The orchestrator accumulates usage from token events and **kills the loop when usage exceeds `suggested_daily_cap`** (FR13), recording it in state.
+
+## Early-Exit Rule
+
+**Early-exit-required flag** is set (true) when the loop's no-op case costs under the early-exit ceiling:
+
+```
+early_exit_required = T_early < 5000
+```
+
+With the default `T_early = 2,000`, the flag is **true** for every Level. If your stack pushes `T_early ≥ 5,000` (huge watchlist read, chatty state writes), the flag flips to **false** — that loop is too expensive to schedule freely and should be re-scoped or scheduled less often.
+
+When `early_exit_required` is true and the watchlist is empty, the orchestrator **must** early-exit and must not proceed to triage/fix — FR13: *"no-op (watchlist empty) → early-exit < 5k tokens."* The non-functional ceiling is a hard 5k.
+
+## Worked Examples
+
+Assumptions (used in every row): `T_early = 2,000`, `T_triage = 12,000`, `T_fix = 80,000`, `safety_factor = 1.5`.
+
+| Cadence (runs/day) | Level | E[run] arithmetic | E[run] (tokens) | tokens/day | Suggested daily cap (×1.5) | per-run cap (×1.5 of T_fix=80k) | Early-exit required? |
+| ------------------ | ----- | ----------------- | --------------- | ---------- | -------------------------- | ------------------------------ | -------------------- |
+| 1 (nightly)        | L1    | 0.90·2k + 0.10·12k + 0·80k = 1,800 + 1,200 | 3,000 | 3,000 | 4,500 | 120,000 | yes (2k < 5k) |
+| 24 (hourly)        | L1    | 0.90·2k + 0.10·12k = 3,000 | 3,000 | 72,000 | 108,000 | 120,000 | yes |
+| 1 (nightly)        | L2    | 0.85·2k + 0.10·12k + 0.05·80k = 1,700 + 1,200 + 4,000 | 6,900 | 6,900 | 10,350 | 120,000 | yes |
+| 24 (hourly)        | L2    | 0.85·2k + 0.10·12k + 0.05·80k = 6,900 | 6,900 | 165,600 | 248,400 | 120,000 | yes |
+| 1 (nightly)        | L3    | 0.40·2k + 0.35·12k + 0.25·80k = 800 + 4,200 + 20,000 | 25,000 | 25,000 | 37,500 | 120,000 | yes |
+| 24 (hourly)        | L3    | 0.40·2k + 0.35·12k + 0.25·80k = 25,000 | 25,000 | 600,000 | 900,000 | 120,000 | yes |
+| 96 (every 15 min)  | L1    | 3,000 | 3,000 | 288,000 | 432,000 | 120,000 | yes |
+| 96 (every 15 min)  | L3    | 25,000 | 25,000 | 2,400,000 | 3,600,000 | 120,000 | yes |
+
+**Reading the table:** the hourly-L3 row (600k tokens/day, 900k cap) is the warning zone — an L3 fix loop scheduled hourly is almost certainly over-budget unless you have a large API quota. The nightly-L1 row (4,500 cap) is the cheap, safe default for triage loops. The every-15-min-L3 row is a NO-GO on cost alone — re-scope to L2 or drop cadence.
+
+## Output Contract
+
+`loop-cost` produces a single budget record the orchestrator consumes:
+
+```json
+{
+  "level": "L1" | "L2" | "L3",
+  "cadence_per_day": <number>,
+  "assumptions": {
+    "T_early": 2000,
+    "T_triage": 12000,
+    "T_fix": 80000,
+    "safety_factor": 1.5
+  },
+  "E_run_tokens": <number>,
+  "tokens_per_day": <number>,
+  "suggested_daily_cap": <number>,
+  "per_run_cap": <number>,
+  "early_exit_required": true | false,
+  "verdict": "GO" | "NO-GO"
+}
+```
+
+- `verdict` is **NO-GO** if `suggested_daily_cap` exceeds your stated daily quota, or if `early_exit_required` is false, or if the loop is L3 at sub-hourly cadence (cost-only refuse, independent of the refuse-list in `loop-engineering`).
+- The orchestrator reads `suggested_daily_cap` into its `--mode json` token watcher and `per_run_cap` as the per-run kill threshold (FR13).
+
+## Verification
+
+A `loop-cost` estimate is correct iff all of these hold:
+
+1. **Arithmetic reproduces.** Re-run `E[run] = p_early·T_early + p_triage·T_triage + p_fix·T_fix` with the Level's percentages and the stated `T_*`; the result matches `E_run_tokens`. The percentages are the only Level-dependent input.
+2. **Percentages sum to 1.0 per Level.** L1: 0.90 + 0.10 = 1.00. L2: 0.85 + 0.10 + 0.05 = 1.00. L3: 0.40 + 0.35 + 0.25 = 1.00. If they don't sum to 1.00, the blend is wrong.
+3. **Cap ≥ tokens/day.** `suggested_daily_cap = ceil(tokens_per_day * safety_factor)` and `safety_factor ≥ 1.0`. A cap below `tokens_per_day` is a bug.
+4. **per_run_cap uses the worst case, not the blend.** `per_run_cap = safety_factor * T_fix`. If it equals `safety_factor * E_run_tokens`, the runaway-run protection is broken.
+5. **Early-exit flag matches `T_early`.** `early_exit_required = (T_early < 5000)`. With `T_early = 2,000` it is `true`. If `T_early` is overridden and the flag wasn't recomputed, it's stale.
+6. **Assumptions are explicit.** Every number in the output traces to an entry in `assumptions`. No hidden constants.
+
+Run the check manually: pick any Worked Examples row, substitute the Level percentages into the blend formula with the stated `T_*`, and confirm `E_run_tokens` and `suggested_daily_cap` match. If they do, the model is internally consistent; if a row is off, the skill is broken.