ultra-builder-pro-cli 0.10.0 → 0.11.0

package/skills/learn/SKILL.md

@@ -1,118 +1,58 @@
 ---
 name: learn
-description: "Extract one reusable pattern from the current session into a valid user skill, with explicit user approval before writing."
-user-invocable: true
+description: Extract one verified reusable workflow from completed work into a portable user skill after explicit approval. Use when the user asks to preserve a repeatable method that does not belong in project guidance or ordinary documentation.
 ---
 
-# learn — Phase 3.6
+# Capture a reusable skill
 
-Mine the current session for a reusable pattern and save it as a Speculation-
-grade skill under `~/.claude/skills/learned-<name>-unverified/SKILL.md`. User
-confirmation is mandatory before the write — never silently persist.
+Create a focused workflow from evidence in the current task. Do not capture prompts,
+transcripts, private memory, or one-off incident details.
 
-## Trigger conditions
+## Placement gate
 
-Run `/learn` after solving a non-trivial problem where the approach is
-generalizable (not a one-off typo or outage-specific fix).
+Before drafting, decide whether the material belongs in a skill:
 
-## What to extract
+- durable repository convention: update the nearest project guidance instead;
+- product or architecture fact: update project documentation instead;
+- external live data or action: use an MCP integration instead;
+- repeatable procedure with non-obvious steps, references, or scripts: create a skill.
 
-| Kind | Example |
-|------|---------|
-| **Error resolution** | Root cause + fix that applies to similar errors |
-| **Debugging technique** | Non-obvious steps, effective tool combos |
-| **Workaround** | Library quirk / API limitation / version-specific fix |
-| **Project-specific pattern** | Codebase convention / integration pattern discovered this session |
+Stop when the candidate is a typo fix, transient outage, generic advice, unsupported
+hypothesis, or a duplicate of an existing skill.
 
 ## Workflow
 
-### Step 1 — Review session
-
-Scan recent messages / tool outputs for extractable patterns. Prefer
-patterns that saved meaningful time or would have, had they been known upfront.
-
-### Step 2 — Identify the highest-value candidate
-
-Multiple candidates? Pick one. Keep skills focused — **one pattern per file**.
-
-### Step 3 — Draft skill body
-
-Use the **learned-skill template** below. Mark confidence as `Speculation`
-and append `-unverified` to the skill directory name.
-
-### Step 4 — User confirmation
-
-Present a concise summary (pattern name, one-sentence description, trigger,
-proposed filename) to the user and ask to approve the save. Options:
-- A: "Save it" → Step 5
-- B: "Edit first" → accept user revisions, re-confirm
-- C: "Don't save" → abort
-
-### Step 5 — Write file
-
-Path: `~/.claude/skills/learned-<pattern-slug>-unverified/SKILL.md`.
-Never overwrite an existing learned skill directory — increment the slug
-(`learned-pattern-slug-2-unverified/`) if it already exists.
-
-## Learned-skill template
-
-```markdown
----
-name: learned-<pattern-slug>-unverified
-description: Use when <specific trigger for this reusable pattern>.
----
-
-# <Descriptive Pattern Name>
-
-**Extracted**: <YYYY-MM-DD>
-**Confidence**: Speculation (unverified)
-**Context**: <one-sentence applicability>
-
-## Problem
-<what problem does this pattern solve — be specific>
-
-## Solution
-<the pattern / technique / workaround>
-
-## Example
-<code example if applicable — else a transcribed command sequence>
-
-## Trigger Conditions
-<what situations should activate this skill>
-
-## Verification Status
-- [ ] Human review passed
-- [ ] Multiple successful uses
-```
-
-## Verification upgrade path
-
-1. **Speculation** (this skill writes this level) — freshly extracted, unverified
-2. **Inference** — after human review passes, rename the directory to remove
-   `-unverified` and update the frontmatter name
-3. **Fact** — after multiple successful uses confirm the pattern
-
-## What NOT to extract
-
-- Simple typo fixes
-- One-time issues (API outage, transient CI flake)
-- Patterns too project-specific to reuse (belongs in project docs, not a skill)
-- Anything already captured in CLAUDE.md or equivalent project instructions
-
-## Approval boundary
-
-Ask the user directly before writing. No Ultra MCP or legacy interaction wrapper is involved.
-
-## What this skill DOES NOT do
-
-- Does NOT modify state.db
-- Does NOT save without user approval
-- Does NOT extract more than one pattern per run
-
-## Integration
-
-| | |
-|---|---|
-| **Input** | current session transcript / recent tool outputs |
-| **Output** | `~/.claude/skills/learned-<slug>-unverified/SKILL.md` |
-| **Next** | user may promote after review; `/learn` again later when another pattern appears |
+1. Identify one coherent procedure that succeeded in the current work. Preserve the
+   trigger, decisive steps, non-obvious failure modes, inputs, outputs, and validation
+   command; remove task-specific names, dates, branches, and conclusions.
+2. Search the current host's user skill directory for overlap. Extend an existing
+   skill only when its job and trigger remain coherent.
+3. Draft a portable skill directory:
+
+   ```text
+   <skill-name>/
+     SKILL.md
+     scripts/       # only deterministic reusable helpers
+     references/    # only conditional detailed guidance
+     assets/        # only reusable templates or resources
+   ```
+
+4. Keep `SKILL.md` focused on the procedure. Its frontmatter contains only `name` and
+   `description`; the description states both what the skill does and when to use it.
+   Move detailed schemas, long examples, and optional branches into focused resources
+   and say exactly when to load them.
+5. Present the proposed name, trigger, file inventory, and concise draft to the user.
+   Write nothing until the user approves.
+6. Write to the current host's user skill directory without overwriting an unrelated
+   skill. Add host-specific UI or invocation metadata outside `SKILL.md` when the host
+   supports it.
+7. Run the available Agent Skills validator and at least one positive and one negative
+   trigger check. Report any behavior that remains unverified.
+
+## Quality gate
+
+The captured skill must be reusable without the original conversation, grounded in
+observed evidence, concise enough to compete safely for context, and explicit about
+validation. Create one skill per coherent job, not one skill per fact.
+
+This workflow never modifies Ultra state and never runs automatically at task close.

package/skills/security-rules/SKILL.md

@@ -1,60 +1,38 @@
 ---
 name: security-rules
-description: Ultra Builder Pro security rules
-user-invocable: false
+description: Evaluate changed trust boundaries for exploitable input, authorization, secret, data-exposure, and supply-chain failures. Use only when an assigned review scope contains a security-relevant boundary.
 ---
 
-# 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
+# Review security-relevant changes
+
+Follow data from an attacker-controlled or less-trusted source to a protected action,
+secret, identity, or output. Report plausible exploit paths, not isolated pattern
+matches.
+
+## Review procedure
+
+1. Identify trust boundaries, protected assets, principals, and state-changing actions
+   in the diff.
+2. Trace input validation, canonicalization, authorization, and output handling through
+   the real call path.
+3. Verify authorization is derived from trusted server state and applies to the
+   requested resource, tenant, or object.
+4. Inspect persistence and command boundaries for injection, unsafe deserialization,
+   path traversal, and unbounded resource use.
+5. Inspect logs, errors, telemetry, and client responses for secret or sensitive-data
+   disclosure.
+6. Inspect changed authentication, cryptography, dependency, file-upload, webhook, and
+   cross-origin behavior when present.
+7. Check the failure path: rate limits, replay or idempotency, partial writes, rollback,
+   and audit evidence where the risk requires them.
+
+## Finding threshold
+
+Report only when the current code supports a triggering input and a meaningful impact.
+Include the source-to-sink path, affected asset, exploit preconditions, and a bounded
+fix. Distinguish a missing defense from a defense implemented elsewhere in the live
+path.
+
+Treat confirmed secret exposure, authorization bypass, injection with material impact,
+and destructive cross-tenant access as blocking. Calibrate other issues from their
+actual reachability and blast radius rather than a fixed pattern-to-severity table.

package/skills/testing-rules/SKILL.md

@@ -1,56 +1,32 @@
 ---
 name: testing-rules
-description: Ultra Builder Pro testing discipline rules
-user-invocable: false
+description: Review whether changed behavior has meaningful, trustworthy, and proportionate test evidence across its real boundaries. Use only when assigned to a test review or delivery verification scope.
 ---
 
-# 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
+# Review test evidence
+
+Evaluate what the tests prove about the accepted behavior. Line coverage and the mere
+presence of a test file are supporting signals, not the contract.
+
+## Procedure
+
+1. Map each changed behavior and acceptance claim to a test or other executable check.
+2. Confirm the test can fail for the intended defect and observes a public or stable
+   contract rather than implementation trivia.
+3. Inspect happy, error, boundary, state-transition, and concurrency cases according to
+   the risk introduced by the diff.
+4. Verify integration seams with the most realistic practical boundary. Prefer real
+   persistence and protocol behavior when their semantics matter.
+5. Accept test doubles at costly, unavailable, or nondeterministic external boundaries
+   when the double preserves the documented contract and the reason is clear.
+6. Flag mocks or fakes only when they bypass the behavior under review, encode a false
+   contract, or make a passing test unrelated to production behavior.
+7. Detect skipped checks, tautological assertions, swallowed failures, non-determinism,
+   weakened expectations, and tests that never reach the changed code.
+
+## Finding contract
+
+Name the unproven behavior, why current evidence is insufficient, the failure that can
+escape, and the smallest test or boundary check that closes the gap. Calibrate severity
+to product risk and reachability; do not impose a universal coverage percentage or a
+single test technology on every repository.

package/skills/ultra-change/SKILL.md

@@ -1,122 +1,65 @@
 ---
 name: ultra-change
-description: "Open or resume a continuous change, capture its delta and decisions, compile bounded role context, and route one executable slice."
-user-invocable: true
-runtime: all
-mcp_tools_required:
-  - change.create
-  - change.update
-  - change.get
-  - change.list
-  - change.context
-  - change.breadcrumb
-  - change.learning_propose
-  - change.learning_resolve
-  - task.create
-  - task.list
+description: Open or resume a bounded continuous change and connect its intent, delta, decisions, context, and executable tasks. Use when maintaining or extending an Ultra project after its baseline exists.
 ---
 
-# ultra-change — Delta Entry and Alignment Gate
+# Open or resume a continuous change
 
-Use this after the first baseline delivery for fixes, small features, redesigns,
-incidents, and maintenance. It keeps specifications live through a delta → implement
-→ learn → converge loop.
+Keep post-delivery work aligned through a delta, implementation, learning, and
+convergence loop.
 
 ## Authority boundary
 
-All change and task lifecycle writes use the live MCP tools. Do not write raw SQLite
-or mutate generated task/context projections. Provider payloads stay in their owning
-memory or graph system; Ultra stores metadata references only.
-
-## 1. Establish the change
-
-Call `change.list` and `change.breadcrumb` first.
-
-- Resume the single matching active/blocked change.
-- If several may match, require an explicit id.
-- Otherwise auto-discover repository facts, then ask only the highest-value unresolved
-  question. Do not ask the user for branch, stack, paths, or behavior already visible.
-
-Capture:
-
-- observable problem or requested outcome;
-- acceptance and explicit non-goals;
-- affected public seam or integration boundary;
-- documentation impact: `required` paths, `none` with rationale, or blocking `unknown`;
-- kind: `quick`, `standard`, `major`, or `incident`;
-- decision inventory: accepted decisions, rejected alternatives, and unresolved choices.
-
-Create with `change.create` using a stable kebab-case id. Update an existing packet
-with `change.update`; never create a parallel packet for the same outcome.
-
-## 2. Write only the delta
-
-The bounded packet is:
-
-```text
-.ultra/changes/active/<change-id>/
-  intent.md
-  delta/                 # standard and major
-  plan.md                # standard and major
-  diagnosis.md           # incident
-  context-manifest.json  # MCP projection
-  spec-learning.json     # MCP projection
-  verification.md        # convergence projection
-```
-
-`intent.md` records outcome, acceptance, non-goals, docs impact, and decisions.
-Delta files describe only differences from the baseline. An incident diagnosis must
-record symptom, earliest bad state, root-cause hypothesis, discriminating evidence,
-and recovery boundary.
-
-## 3. Create an executable slice
-
-Prefer the smallest vertical `tracer_bullet` that crosses a live public seam. Split
-only when ownership or verification is genuinely independent. Each task must declare:
-
-- one observable outcome and linked `change_id`;
-- bounded files/contracts and dependencies;
-- `public_seam` that proves reachability;
-- exact `verification_command`;
-- expected red signal for a bug/incident;
-- documentation impact.
-
-Persist tasks with `task.create`. Generated `tasks.json` is never an input authority.
-
-## 4. Compile Context Manifest v2
-
-Call `change.context` for the next task with:
-
-```json
-{
-  "id": "<change-id>",
-  "task_id": "<task-id>",
-  "role": "plan",
-  "gate": "planning",
-  "context_refs": [{"ref":"<path>","kind":"spec","reason":"defines acceptance","required":true}],
-  "budget": {"max_tokens":12000,"max_files":12},
-  "execution_contract": {
-    "slice_kind":"tracer_bullet",
-    "public_seam":"<reachable boundary>",
-    "verification_command":"<exact command>",
-    "context_budget_percent":40
-  }
-}
-```
-
-Include only files needed for the current role and gate. Missing required references,
-digest drift, file-count overflow, or a fresh-context budget over 40% blocks readiness.
-Use `expand_contract` only for an explicitly approved wider slice.
-
-## 5. Handle discoveries without silent spec drift
-
-When implementation reveals a stable requirement, invariant, or public behavior not
-in the baseline, call `change.learning_propose` with evidence and target document.
-It is a candidate, not an automatic edit. A human/primary-agent decision must approve
-or reject it; approved learning is marked applied only after the baseline was updated.
-
-## Exit contract
-
-Call `change.breadcrumb` and report the compiled task, readiness, blockers, and its
-single next action. Do not claim alignment while documentation impact is unknown,
-context is stale, or a material decision remains unresolved.
+Use Ultra MCP tools for change and task lifecycle writes. Do not write raw SQLite or
+mutate generated task and context projections. External memory or code-graph systems
+own their payloads; Ultra stores only provider references supplied by the user or host.
+
+## Workflow
+
+1. Call `change.list` and `change.breadcrumb`.
+   - Resume the single change that matches the requested outcome.
+   - Require an explicit id when several changes could match.
+   - Create a new change only when no existing packet represents the same outcome.
+2. Capture the observable outcome, acceptance, non-goals, affected public seam,
+   documentation impact, and unresolved decisions.
+3. Classify the change as `quick`, `standard`, `major`, or `incident`. Ask only for a
+   material product, risk, or recovery decision that repository evidence cannot answer.
+4. Call `change.create` with a stable kebab-case id, or `change.update` when resuming.
+5. Write the minimum artifact set required by the classification:
+
+   ```text
+   .ultra/changes/active/<change-id>/
+     intent.md
+     delta/                 # standard and major
+     plan.md                # standard and major
+     diagnosis.md           # incident
+     context-manifest.json  # generated projection
+     spec-learning.json     # generated projection
+     verification.md        # generated projection
+   ```
+
+   Delta files describe differences from the baseline, not a second copy of it.
+   Incident diagnosis records the symptom, earliest bad state, falsifiable
+   hypotheses, evidence, root cause, and recovery boundary.
+6. Create the smallest executable vertical slice with `task.create`. Each task needs
+   one outcome, bounded ownership, dependencies, a live public seam, an exact
+   verification command, and documentation impact.
+7. Compile `change.context` for the next role and gate. Include only required
+   references and the task execution contract. Treat missing references, digest or
+   HEAD drift, an exceeded context budget, and unknown documentation impact as
+   blockers.
+8. Call `change.breadcrumb` and return its single next action.
+
+## Specification learning
+
+When implementation uncovers a stable requirement, invariant, or public behavior
+missing from the baseline, call `change.learning_propose` with evidence and a target
+document. The proposal does not edit the baseline. It must be approved or rejected,
+and an approved item is marked applied only after the target document is updated and
+verified.
+
+## Completion gate
+
+Do not claim alignment while a material decision is unresolved, documentation impact
+is unknown, context is stale, or the next task is not executable from a bounded fresh
+context.