ultra-builder-pro-cli 0.5.0

package/skills/security-rules/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: security-rules
+description: Ultra Builder Pro security rules
+user-invocable: false
+---
+
+# Security Rules
+
+These rules are mandatory for all code review and security-related work.
+
+## Input Validation
+
+All external input MUST be validated:
+- **Syntactic**: correct format (email, date, UUID)
+- **Semantic**: valid in business context (start < end, price > 0)
+- Validate early, reject invalid input immediately
+
+## Forbidden Patterns
+
+| Pattern | Risk | Alternative |
+|---------|------|-------------|
+| SQL string concatenation | SQL Injection | Parameterized queries (`$1`, `?`) |
+| User input → HTML directly | XSS | textContent, sanitizer library |
+| Hardcoded secrets/keys | Credential leak | Environment variables, secret manager |
+| Trust client-supplied role | Privilege escalation | Derive from session/token server-side |
+| Dynamic code evaluation with user input | Code injection | Use safe parsers (JSON.parse, etc.) |
+| Regex with user input | ReDoS | Validate/escape regex input |
+
+## Required Practices
+
+| Area | Rule |
+|------|------|
+| SQL | Parameterized queries only |
+| Output | Escape/sanitize all user-derived content |
+| Auth | Use established auth libraries |
+| Secrets | Environment variables or secret manager |
+| Sessions | Secure, HttpOnly, SameSite cookies |
+| CORS | Explicit allowlist, never wildcard in production |
+| File upload | Validate type, size, sanitize filename |
+
+## Error Handling Security
+
+- Never expose stack traces to end users
+- Never include sensitive data in error messages
+- Log security events with sufficient context for investigation
+- Use typed errors, not generic messages
+
+## Review Checklist
+
+When reviewing code, check for:
+1. SQL injection vectors (string concatenation in queries)
+2. XSS vectors (unescaped user input in HTML/templates)
+3. Hardcoded credentials, API keys, or secrets
+4. Missing authentication/authorization checks
+5. Missing input validation on external boundaries
+6. Insecure direct object references (IDOR)
+7. Missing rate limiting on sensitive endpoints
+8. Sensitive data in logs or error messages
+9. Missing CSRF protection on state-changing operations
+10. Insecure deserialization

package/skills/testing-rules/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: testing-rules
+description: Ultra Builder Pro testing discipline rules
+user-invocable: false
+---
+
+# Testing Rules
+
+These rules are mandatory for all test-related work.
+
+## TDD Workflow
+
+RED → GREEN → REFACTOR (all new code).
+
+## Test Strategy
+
+| Layer | Test Type | Mock Strategy |
+|-------|-----------|---------------|
+| Functional Core | Unit Test | No mocks needed (pure input→output) |
+| Imperative Shell | Integration | Testcontainers (real DB/services) |
+| External APIs | Test Double | With `// Test Double rationale: [reason]` |
+
+## Forbidden Patterns
+
+These patterns are **never** acceptable:
+
+| Pattern | Why Forbidden | Alternative |
+|---------|---------------|-------------|
+| `jest.fn()` for Repository/Service/Domain | Invalid test — doesn't prove production works | Testcontainers |
+| `class InMemoryRepository` | Diverges from real DB behavior | Real DB container |
+| `class MockXxx` / `class FakeXxx` | Hides integration issues | Direct instantiation or Testcontainers |
+| `jest.mock('../services/X')` | Skips real collaboration | Test real collaboration |
+| `it.skip('...database...')` | "Too slow" is not valid | Testcontainers are fast enough |
+
+## Coverage Requirements
+
+- 80% overall minimum
+- 100% Functional Core (pure logic must be fully tested)
+- Critical paths for Imperative Shell
+
+## Dev/Prod Parity
+
+Tests must use real dependencies:
+- Real database via Testcontainers (not in-memory substitutes)
+- Config via environment variables
+- Mock tests passing ≠ production working
+
+## Detection Checklist
+
+When analyzing test files, flag:
+1. Any `jest.fn()` usage on Repository, Service, or Domain classes
+2. Any `InMemory*` or `Mock*` or `Fake*` class definitions
+3. Any `jest.mock()` calls on internal modules
+4. Any skipped tests with database/slow excuses
+5. Missing error case coverage
+6. Missing edge case coverage

package/skills/ultra-deliver/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: ultra-deliver
+description: "Release preparation — verify /ultra-test passed, update docs, build, version-bump, tag, push. Writes .ultra/delivery-report.json."
+runtime: all
+cli_fallback: "direct user interaction"
+---
+
+# ultra-deliver — Phase 3.5
+
+Release the current working tree. Driven entirely by file-level artifacts
+(`.ultra/test-report.json` as the gate; `.ultra/delivery-report.json` as the
+output). No state.db writes.
+
+## Prerequisites (Pre-Delivery Validations — both BLOCKING)
+
+### Validation 1 — `/ultra-test` passed
+
+Read `.ultra/test-report.json`:
+- File must exist → else: "Run `/ultra-test` first" → **EXIT**
+- `passed === true` → else: show `blocking_issues`, **EXIT**
+- `git_commit === current HEAD` → else: "Code changed since last test;
+  re-run `/ultra-test`" → **EXIT**
+
+### Validation 2 — No uncommitted changes
+
+`git status --porcelain` must be empty. If dirty, ask through the current
+Host's native user-interaction surface:
+- A: "Auto-commit all changes" → `git add -A && git commit -m "chore: pre-delivery cleanup"`
+- B: "Review changes first" → `git diff --stat` → re-ask
+- C: "Block delivery" → **EXIT**
+
+Commit failure (conflicts, hook rejection) → surface error and **EXIT**.
+
+## Workflow
+
+### Step 1 — Documentation Update (MANDATORY)
+
+**1.1 CHANGELOG.md** (required):
+1. `git log --oneline <last-tag>..HEAD`
+2. Categorize by Conventional Commit type: `feat:` → Added, `fix:` → Fixed,
+   `chore:` → Maintenance, `refactor:` → Changed, `docs:` → Documentation,
+   `test:` → Tests, `perf:` → Performance.
+3. Insert a new version section at the top of CHANGELOG.md.
+4. Verify: Read CHANGELOG.md; confirm new version section exists.
+
+**1.2 Technical debt report** (required):
+1. Grep source for `TODO:` / `FIXME:` / `HACK:` / `XXX:`.
+2. Generate / refresh `.ultra/docs/technical-debt.md`:
+   ```markdown
+   # Technical Debt (<date>, <commit>)
+   | File | Line | Kind | Note |
+   |------|------|------|------|
+   | src/foo.ts | 42 | TODO | "remove after v1.3" |
+   ```
+3. Verify: file reflects current grep output.
+
+**1.3 README.md** (conditional — public API changed):
+1. Diff exported API signatures since last release (`git diff <last-tag>..HEAD -- 'src/**'`)
+2. If signatures changed, update README usage examples
+3. Verify examples match the new API
+
+**Checklist**:
+- [ ] CHANGELOG.md updated
+- [ ] technical-debt.md refreshed
+- [ ] README.md reflects current API (if applicable)
+
+Any unchecked → fix, then continue.
+
+### Step 2 — Production Build
+
+Detect build command (priority order):
+1. `package.json → scripts.build` → `npm run build` (or `pnpm build`/`yarn build`
+   based on lockfile)
+2. `Makefile` → `make build` or `make release`
+3. `Cargo.toml` → `cargo build --release`
+4. `go.mod` → `go build ./...`
+5. Nothing detected → ask the user for the command
+
+Non-zero exit → block with stderr captured, then ask the user:
+- A: "Fix error and retry"
+- B: "Abort delivery"
+
+### Step 3 — Version + Release (MANDATORY — all 5 sub-steps)
+
+**3.1 Determine version bump**:
+- `git log <last-tag>..HEAD --oneline` → analyze commit types
+- `feat:` → minor, `BREAKING CHANGE:` / `!:` → major, else patch
+- Display `<old> → <new>`; allow an explicit user override.
+
+**3.2 Update version in project files**:
+- `package.json`, `Cargo.toml`, `pyproject.toml`, etc.
+- Verify: read the file; confirm new version.
+
+**3.3 Release commit**:
+```bash
+git add -A
+git commit -m "chore(release): v<X.Y.Z>"
+```
+Verify with `git log -1 --oneline`.
+
+**3.4 Git tag**:
+```bash
+git tag v<X.Y.Z>
+```
+Verify with `git tag -l v<X.Y.Z>`.
+
+**3.5 Push to remote**:
+```bash
+git push origin main     # release commit
+git push origin v<X.Y.Z> # version tag
+```
+Verify with `git ls-remote --tags origin | grep v<X.Y.Z>`.
+
+**Release checklist**:
+- [ ] Version determined and displayed
+- [ ] Version file updated and verified
+- [ ] Release commit created and verified
+- [ ] Git tag created and verified
+- [ ] Commit and tag pushed and verified on remote
+
+Any failure → stop immediately; do NOT continue; surface last-step error.
+
+### Step 4 — Persist `.ultra/delivery-report.json`
+
+```jsonc
+{
+  "timestamp": "<ISO8601>",
+  "version": "<X.Y.Z>",
+  "git_tag": "v<X.Y.Z>",
+  "git_commit": "<HEAD SHA>",
+  "changelog_updated": true,
+  "technical_debt_refreshed": true,
+  "build_success": true,
+  "pushed": true
+}
+```
+
+### Step 5 — Report
+
+Print a tight release summary: tag, commit, files touched in CHANGELOG,
+outstanding technical-debt count, next suggested action (deploy / announce).
+
+## Deliverables Checklist (final)
+
+- [ ] `/ultra-test` passed (verified via test-report.json)
+- [ ] Uncommitted changes handled
+- [ ] CHANGELOG + technical-debt refreshed (README if API changed)
+- [ ] Production build exit 0
+- [ ] Version bumped, tagged, pushed
+- [ ] delivery-report.json written
+
+## MCP → CLI fallback matrix
+
+| Purpose | MCP tool | CLI fallback |
+|---------|----------|--------------|
+| Resolve dirty-tree action | none | current Host's native user-interaction surface |
+| Override version bump | none | current Host's native user-interaction surface |
+
+## What this skill DOES NOT do
+
+- Does NOT run tests (that is `/ultra-test`'s job)
+- Does NOT publish to npm / crates.io / PyPI (Phase 9 handles distribution)
+- Does NOT mutate state.db
+
+## Integration
+
+| | |
+|---|---|
+| **Input** | `.ultra/test-report.json` (gate), current repo |
+| **Output** | `.ultra/delivery-report.json`, git tag + remote push |
+| **Next** | Deploy target (Railway / Vercel / etc.) or release announcement |

package/skills/ultra-dev/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: ultra-dev
+description: "Agile development execution with TDD workflow. Writes state through live task MCP tools, reviews through native host subagents, and checkpoints through workflow-state plus lifecycle hooks."
+runtime: all
+mcp_tools_required:
+  - task.update
+  - task.get
+  - task.list
+cli_fallback: "task update"
+---
+
+# ultra-dev — Phase 3.4
+
+Drive one task from `pending → completed` using a strict TDD loop, gated by
+`/ultra-review`. **state.db is the authority**: status transitions go through
+MCP `task.update`; the projector regenerates `tasks.json` and context-md
+frontmatter. The skill only writes context-md **bodies** (Change Log,
+Completion, Dual-Write notes).
+
+## Design decisions vs pre-Phase-3
+
+- **Single-write status**: Step 1.5 / Step 5 stop touching `contexts/task-{id}.md`
+  frontmatter or the "`> **Status**: xxx`" line. Only MCP `task.update` fires;
+  projector rewrites frontmatter; humans read body for history.
+- **Native review path**: `/ultra-review all` delegates bounded review work to
+  the current Host's installed review agents. Review is not an MCP service.
+- **No `/compact` dependency**: Step 4.4 writes `.ultra/workflow-state.json`;
+  trusted lifecycle hooks preserve and restore it around compaction when the
+  Host exposes those events.
+
+## Prerequisites
+
+- `.ultra/tasks/tasks.json` exists (from `/ultra-plan`)
+- At least one task with `status=pending`
+- `state.db` initialized (first `task.*` call will init if missing)
+
+## Arguments
+
+- `$1`: task id (optional; default = first `pending` task in topological order)
+
+## Workflow
+
+### Step 0 — Workflow Resume Check
+
+Read `.ultra/workflow-state.json` if present.
+- If `branch` matches current `git branch --show-current` → resume from the
+  step after `status`
+- If `review_session` is set → skip re-running review
+- Otherwise → proceed to Step 0.5
+
+### Step 0.5 — Design Approval Gate (first run only)
+
+Fires when `.ultra/workflow-state.json` does NOT exist.
+
+1. `task.list` → confirm plan present; if empty, instruct `/ultra-plan` and **EXIT**
+2. If ANY task has `status` in (`in_progress`, `completed`) → plan was already
+   approved → skip this gate
+3. Present plan overview (totals, P0/P1/P2, Walking-Skeleton position)
+4. Ask through the current Host's native user-interaction surface:
+   - A: "Confirm, start implementation" → continue to Step 1
+   - B: "Revise plan first" → suggest `/ultra-plan` → **EXIT**
+5. On approval, write workflow-state:
+   ```jsonc
+   {"command":"ultra-dev","task_id":0,"branch":"","step":"0.5","status":"design_approved","ts":"<ISO8601>"}
+   ```
+
+### Step 1 — Task Selection
+
+```jsonc
+// MCP: task.list (or runtime args supply id)
+{ "status": "pending" }
+```
+
+Pick the first result (dependency-resolved) or the one matching `$1`.
+Read `.ultra/tasks/contexts/task-{id}.md` body for the Implementation /
+Acceptance sections. Use the Acceptance list as the initial todo set.
+
+### Step 1.5 — Status → in_progress (single-write)
+
+```jsonc
+// MCP: task.update  (R: do NOT touch context-md frontmatter or "> **Status**" line)
+{ "id": "<id>", "patch": { "status": "in_progress" } }
+```
+
+**CLI fallback**: `ultra-tools task update <id> --status in_progress`.
+
+Projector runs after the write → `tasks.json` + `contexts/task-{id}.md`
+frontmatter re-generated with `status: in_progress`. **Do not hand-edit either.**
+
+### Step 2 — Environment Setup
+
+**Unmerged-completed recovery**: `git branch --list 'feat/task-*'`; for each,
+extract task id, look up status via `task.get`. If any completed task has an
+unmerged branch → ask the user:
+- "Merge task-{id} to main first" (recommended)
+- "Delete branch (abandoned)"
+- "Skip, continue with new task"
+
+**Branch setup**:
+
+| Current branch | Action |
+|----------------|--------|
+| `main` / `master` | `git pull origin main && git checkout -b feat/task-{id}-{slug}` |
+| `feat/task-{id}-*` (same task) | continue (resume checkpoint) |
+| other | ask the user: switch to main + new branch / continue current |
+
+**Dependencies**: soft-warn only; parallel work is allowed.
+
+### Step 3 — TDD Cycle
+
+**Subagent isolation (complexity ≥ 7)**: optional — delegate a bounded TDD
+cycle through the current Host's native subagent surface; the subagent returns
+a summary and the primary agent owns verification.
+
+**Mid-TDD checkpoint (complexity ≥ 6)**: after GREEN phase, write a
+checkpoint. See Step 4.4 for the preferred MCP route.
+
+**RED** — write failing tests:
+- Mine Acceptance list for test specs
+- Cover 5 dimensions: functional / boundary / exception / security / integration
+- At least one integration test per boundary-crossing module
+- Run; confirm failure
+
+**GREEN** — minimum code to pass:
+- Production-ready (no TODO / placeholder)
+- Run; confirm pass
+
+**REFACTOR** — SOLID / DRY / KISS / YAGNI; tests stay green.
+
+**Checkpoint after Step 3.3**:
+```jsonc
+{"command":"ultra-dev","task_id":<id>,"branch":"<branch>","step":"3.3","status":"tdd_complete","ts":"<iso>"}
+```
+→ `.ultra/workflow-state.json`
+
+### Step 4 — Quality Gates
+
+| Gate | Requirement |
+|------|-------------|
+| Tests green | 0 failures |
+| Coverage | ≥80% overall; 100% functional-core; critical paths for shell |
+| Mock policy | Core logic: no mocks; external: testcontainers/stub OK |
+| No degradation | Zero fallback or demo code |
+| Integration test | Boundary-crossing code has ≥1 real integration test |
+| Entry-point reachable | New modules trace to a handler/listener/cron |
+| Spec compliance | Each Acceptance criterion implemented AND tested |
+
+Checkpoint `step="4"`, `status="gates_passed"`.
+
+### Step 4.4 — Pre-Review Checkpoint
+
+1. Write `.ultra/workflow-state.json` with `step=4.5, status=pre_review`.
+2. Let trusted Host lifecycle hooks preserve and restore that state when
+   compaction events exist.
+3. On Hosts without compaction hooks, resume directly from the same file.
+
+**Gate**: the skill MUST NOT require `/compact`; it MUST work when the
+runtime cannot compact.
+
+### Step 4.5 — Ultra Review (MANDATORY)
+
+Invoke `/ultra-review all`. The workflow uses the current Host's installed
+review agents and writes the unified review artifact. The primary agent owns
+the final verdict and re-runs relevant tests after fixes.
+
+**MAX_REVIEW_ITERATIONS = 2**
+
+| Verdict | Iter | Action |
+|---------|------|--------|
+| APPROVE | any | → Step 5 |
+| COMMENT | any | review P1s, fix if warranted, → Step 5 |
+| REQUEST_CHANGES | 1 | fix ALL P0, re-run tests, `/ultra-review recheck` |
+| REQUEST_CHANGES | 2 | stall check → escalate or fix |
+
+**Stall detection before iter 2**: if `curr_count >= prev_count` (P0+P1 not
+shrinking) → write `UNRESOLVED.md`, WARN user, proceed to Step 5.
+
+**Verification gate before Step 5**:
+- SUMMARY.json verdict ≠ `REQUEST_CHANGES`
+- All P0 resolved
+- Tests still green
+
+Checkpoint `step="4.5", status="review_done", review_session=<id>, review_iteration=<N>`.
+
+### Step 5 — Status → completed (single-write)
+
+**Prerequisites**: Step 4 + Step 4.5 green.
+
+```jsonc
+// MCP: task.update
+{
+  "id": "<id>",
+  "patch": {
+    "status": "completed",
+    "completion_commit": "_pending_"  // overwritten in Step 6 after commit
+  }
+}
+```
+
+**CLI fallback**: `ultra-tools task update <id> --status completed`.
+
+Projector regenerates frontmatter. **Then** write the context-md **body**
+Completion section (skill responsibility, not projector):
+
+```markdown
+## Completion
+- **Completed**: <YYYY-MM-DD>
+- **Commit**: _pending_   # filled in Step 6
+- **Summary**: <one-line delivery summary>
+```
+
+**Do not** hand-edit `> **Status**` anywhere in the body — frontmatter owns it.
+
+### Step 5.5 — Pre-Commit Checklist (BLOCKING)
+
+Before `git commit`, verify every item:
+
+- [ ] `task.get` confirms `status="completed"`
+- [ ] context-md body has updated Completion section
+- [ ] All tests pass
+- [ ] Ultra Review verdict ≠ `REQUEST_CHANGES`
+- [ ] New modules reach a live entry point (no orphan)
+- [ ] Boundary-crossing code has integration test
+
+Any unchecked → fix; do NOT commit.
+
+### Step 6 — Commit + Merge
+
+1. `git status` → show diff
+2. Ask through the current Host's native user-interaction surface:
+   - A: "Commit + Merge to main" (recommended)
+   - B: "Commit only, create PR later"
+   - C: "Review diff first" → `git diff --stat` → re-ask
+
+3. On approval:
+   ```bash
+   git add -A
+   git commit -m "feat(scope): description"
+   ```
+
+4. Record commit hash via MCP:
+   ```jsonc
+   { "id": "<id>", "patch": { "completion_commit": "<sha>" } }
+   ```
+   Update context-md body Completion line to the real hash; amend:
+   ```bash
+   git add .ultra/tasks/contexts/task-<id>.md
+   git commit --amend --no-edit
+   ```
+   (The amend is OK here — the first commit is a local, not-yet-pushed commit
+   in the feature branch. Never amend pushed commits.)
+
+5. `git fetch origin && git rebase origin/main`; resolve any conflicts.
+
+6. Re-run tests after rebase. Fail → fix → amend → repeat 5-6.
+
+7. If Option A chosen:
+   ```bash
+   git checkout main && git pull origin main
+   git merge --no-ff feat/task-<id>-<slug>
+   git push origin main && git branch -d feat/task-<id>-<slug>
+   ```
+
+Checkpoint `step="6", status="committed", commit=<sha>`.
+
+### Step 7 — Report
+
+- Commit hash
+- Project progress (`task.list` → `completed/total`)
+- Next task suggestion (first remaining `pending` in topological order)
+
+## Dual-Write Mode
+
+Triggered when implementation reveals spec gaps or requirement changes.
+
+**Classification (mandatory before updating specs)**:
+
+| Kind | Meaning | Action |
+|------|---------|--------|
+| **EXPANSION** | new requirement surfaced | update spec + Change Log |
+| **CORRECTION** | spec error/ambiguity | update spec + Change Log |
+| **REDUCTION** | removing/weakening scope | **STOP** → ask the user for approval |
+
+**REDUCTION gate** — options:
+- A: "Approve reduction, update spec"
+- B: "Keep original scope, find alternative implementation"
+- C: "Split into separate task, defer to next cycle"
+
+Update `.ultra/specs/` immediately so parallel tasks see current truth.
+Log in context-md body Change Log:
+
+```markdown
+| <date> | <KIND> | <change desc> | specs/<file>#<section> | <reason> |
+```
+
+**Principle**: `specs/` is source of truth; `contexts/` tracks implementation
+history. Specs may grow (EXPANSION) or be corrected (CORRECTION). Specs must
+never silently shrink (REDUCTION without gate).
+
+## MCP → CLI fallback matrix
+
+| Purpose | MCP tool (phase) | CLI / runtime fallback |
+|---------|------------------|------------------------|
+| Select pending task | `task.list` (2) / `task.get` (2) | `ultra-tools task list --status pending` |
+| Status → in_progress | `task.update` (2) | `ultra-tools task update <id> --status in_progress` |
+| Pre-review checkpoint | none | write `.ultra/workflow-state.json`; lifecycle hooks restore it |
+| Run review | none | `/ultra-review all` + Host-native review agents |
+| Status → completed | `task.update` (2) | `ultra-tools task update <id> --status completed` |
+| Ask user | none | current Host's native user-interaction surface |
+
+## What this skill DOES NOT do
+
+- Does NOT write `tasks.json` directly (projector owns it)
+- Does NOT edit context-md frontmatter (projector owns it)
+- Does NOT require the runtime to support `/compact`
+- Does NOT advertise review or checkpoint operations as MCP tools
+
+## Integration
+
+| | |
+|---|---|
+| **Input** | `.ultra/tasks/tasks.json`, `.ultra/tasks/contexts/task-<id>.md` body, state.db |
+| **Writes** | state.db (via `task.update`), context-md body (Completion + Change Log), workflow-state.json checkpoints |
+| **Next** | `/ultra-dev <next-id>` or `/ultra-test` when all Walking Skeleton + critical-path tasks complete |