ultra-builder-pro-cli 0.9.0 → 0.11.0

package/skills/learn/SKILL.md

@@ -1,117 +1,58 @@
 ---
 name: learn
-description: "Extract one reusable pattern from the current session into a valid user skill, with explicit user approval before writing."
+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,149 +1,65 @@
 ---
 name: ultra-change
-description: "Start or resume a continuous post-delivery change, compile bounded context, declare documentation impact, and route the change through implementation and convergence."
-runtime: all
-mcp_tools_required:
-  - change.create
-  - change.update
-  - change.get
-  - change.list
-  - change.context
-  - 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 — Continuous Change Entry
-
-Use this workflow for daily fixes, small features, redesigns, and incidents after
-the initial `init → research → plan → dev → test → deliver` baseline exists.
-Each piece of work becomes one durable change unit instead of an informal edit
-that drifts away from specifications and verification evidence.
-
-## Authority and provider boundary
-
-- `.ultra/state.db` is authoritative for the change, its tasks, events, incidents,
-  context snapshots, and projection status.
-- `.ultra/changes/active/<change-id>/` contains inspectable artifacts, not a
-  second state authority.
-- Memory and code graph are external providers. Pass only metadata references:
-  `provider`, `project`, `reference`, `revision`, `indexed_head`, and `status`.
-- Never paste recalled memories, graph nodes, embeddings, summaries, or provider
-  payloads into `provider_refs`. If provider data is unavailable, record
-  `status: unavailable` and continue with current-checkout evidence.
-- If any required change/task MCP operation is unavailable, stop. Do not edit
-  `state.db`, `tasks.json`, or context projections directly.
-
-## Arguments
-
-- `$1`: existing change id, or a short title for a new change.
-- Optional flags/concepts: `quick`, `standard`, `major`, `incident` and an
-  explicit documentation impact.
-
-## 1. Resume before creating
-
-Call `change.list` for `active` and `blocked` changes. If `$1` matches an
-existing id, call `change.get` and resume it. If the request clearly belongs to
-an active change, show the match and continue there rather than creating a
-duplicate.
-
-Do not resume `ready`, `archived`, or `cancelled` work as a new mutation. Create
-a follow-up change that links to the prior archive in its intent.
-
-## 2. Classify the change
-
-Choose the smallest honest kind:
-
-| Kind | Use when | Required convergence evidence |
-|---|---|---|
-| `quick` | localized fix or tiny behavior change | diff, tests, spec |
-| `standard` | normal feature or cross-file change | diff, tests, spec, docs, review |
-| `major` | architecture, public contract, migration, or broad redesign | diff, tests, spec, docs, review |
-| `incident` | canonical debug lane for a production/runtime failure | diagnosis, diff, tests |
-
-When uncertain between two kinds, choose the higher-risk kind. Classification
-changes the proof required; it must not be used to bypass evidence.
-
-## 3. Declare intent and documentation impact
-
-Before implementation, write a concise intent with:
-
-- observed problem or requested outcome;
-- acceptance behavior and non-goals;
-- affected contract/surface;
-- recovery or rollback concern when material.
-
-Documentation impact is mandatory:
-
-- `required`: list every baseline document expected to change;
-- `none`: provide a concrete rationale;
-- `unknown`: allowed only while investigating and blocks convergence.
-
-Create the change with `change.create`. Use a stable kebab-case id. External
-provider references are optional and metadata-only.
-
-## 4. Build the delta packet
-
-The change directory is the bounded execution packet:
-
-```text
-.ultra/changes/active/<change-id>/
-  intent.md
-  context-manifest.json
-  delta/                  # required for standard and major
-  plan.md                 # required for standard and major
-  diagnosis.md            # created and structurally required for incident
-  verification.md         # generated by convergence
-```
-
-For `standard` and `major`, write delta documents under `delta/` describing
-what changes relative to the current baseline. Do not copy the whole baseline.
-Write `plan.md` with live entry points, files/contracts, tests, documentation,
-and rollback. For `quick`, add only artifacts needed to make the decision and
-evidence inspectable. For `incident`, complete the generated `diagnosis.md` with
-non-empty `Reproduction`, `Hypotheses`, `Root cause`, `Regression test`, and
-`Recovery` sections. Free-form convergence evidence never substitutes for this
-durable diagnosis artifact.
-
-Create at least one task through `task.create` with `change_id` set. Split only
-when ownership, dependencies, or independent verification justify it. All task
-status changes remain MCP-authoritative.
-
-## 5. Compile task context
-
-Call `change.context` before implementation and again whenever any of these
-changes: git HEAD, task set, relevant specs, allowed paths, or provider revision.
-Supply only the minimum task/spec/path references needed for the current slice.
-
-Inspect `context-manifest.json` before handing work to an agent. A stale git head
-or task set is a hard signal to recompile. Provider `status: stale` is visible
-context, not permission to silently refresh or mutate the external provider.
-
-## 6. Route execution
-
-- For `incident`, diagnosis is the first execution slice. Route it to the bundled
-  `debugger` agent when the Host exposes native subagents; otherwise the primary
-  Host follows the same four-phase method. Supply only the compiled change/task
-  context. The primary Host owns the fix, updates `diagnosis.md`, and reruns the
-  discriminating regression test.
-- Implement one linked task with `/ultra-dev <task-id>`.
-- Run `/ultra-test` for project-level evidence.
-- Run `/ultra-review` when the change kind requires review.
-- Update baseline docs declared in `docs_impact` during the change, not after
-  memory has gone cold.
-- Finish with `/ultra-deliver`; it runs deterministic change convergence and
-  archive reconciliation before release actions.
-
-If work exposes a new requirement, update the change intent/delta and recompile
-context before continuing. Never let code become the only record of the change.
-
-## 7. Report
-
-Return the change id, kind, artifact root, linked tasks, documentation impact,
-context freshness, provider-reference status, and exact next workflow. Separate
-provider unavailability from an Ultra runtime incident.
-
-## What this skill does not do
-
-- It does not implement, test, review, release, or repair runtime state.
-- It does not own or synchronize Memory/code-graph content.
-- It does not bypass user approval for destructive or external release actions.
+# Open or resume a continuous change
+
+Keep post-delivery work aligned through a delta, implementation, learning, and
+convergence loop.
+
+## Authority boundary
+
+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.