ultra-builder-pro-cli 5.0.1 → 6.0.0

package/skills/ultra-tdd/references/templates/testcontainer-postgres.ts

@@ -1,73 +0,0 @@
-/**
- * Testcontainer-Postgres starter (TypeScript / vitest or jest)
- *
- * Why this exists: Real DB in tests catches migration drift, schema bugs, and
- * concurrency issues that mocked Repositories silently miss. Prefer this to
- * `jest.fn()` / `vi.fn()` for any Repository or Service that touches data.
- *
- * Required deps:
- *   pnpm add -D @testcontainers/postgresql pg
- *
- * Verify:
- *   pnpm vitest run src/repo/__tests__/userRepo.testcontainer.test.ts
- *
- * PHILOSOPHY: enables C2 (Enabling > Defensive) — the cheaper path becomes the
- * right path, so agents stop reaching for mocks under pressure.
- */
-
-import { PostgreSqlContainer, StartedPostgreSqlContainer } from '@testcontainers/postgresql';
-import { Pool } from 'pg';
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'vitest';
-
-let container: StartedPostgreSqlContainer;
-let pool: Pool;
-
-beforeAll(async () => {
-  container = await new PostgreSqlContainer('postgres:16-alpine').start();
-  pool = new Pool({ connectionString: container.getConnectionUri() });
-  // Replace with your migration runner (drizzle/prisma/knex/raw SQL)
-  await pool.query(`
-    CREATE TABLE users (
-      id SERIAL PRIMARY KEY,
-      email TEXT UNIQUE NOT NULL,
-      created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-    );
-  `);
-}, 60_000); // pulling postgres image can be slow on first run
-
-afterAll(async () => {
-  await pool.end();
-  await container.stop();
-});
-
-beforeEach(async () => {
-  // Reset between tests so each is independent
-  await pool.query('TRUNCATE users RESTART IDENTITY CASCADE');
-});
-
-describe('UserRepo (real Postgres)', () => {
-  test('insert and fetch round-trips', async () => {
-    // Replace with your actual Repository
-    const repo = makeUserRepo(pool);
-    const created = await repo.create({ email: 'a@example.com' });
-    const found = await repo.findById(created.id);
-    expect(found).toEqual(created);
-  });
-});
-
-// Drop your real Repository factory here
-function makeUserRepo(pool: Pool) {
-  return {
-    async create(input: { email: string }) {
-      const { rows } = await pool.query(
-        'INSERT INTO users (email) VALUES ($1) RETURNING *',
-        [input.email],
-      );
-      return rows[0];
-    },
-    async findById(id: number) {
-      const { rows } = await pool.query('SELECT * FROM users WHERE id = $1', [id]);
-      return rows[0] ?? null;
-    },
-  };
-}

package/skills/ultra-tdd/references/templates/vertical-slice.ts

@@ -1,66 +0,0 @@
-/**
- * Vertical-Slice integration test (TypeScript)
- *
- * Why this exists: proves HTTP entry → use case → domain → DB → response works
- * end-to-end. ONE such test per feature is the difference between "single tasks
- * pass / project doesn't run" (the failure mode v7 was built to fix) and
- * actual deliverable software.
- *
- * Required deps:
- *   pnpm add -D supertest @testcontainers/postgresql pg vitest
- *
- * Verify:
- *   pnpm vitest run src/__tests__/auth.vertical-slice.test.ts
- *
- * PHILOSOPHY: enables C4 (Incremental Validation) — the `vertical_slice`
- * dimension in progress.json is satisfied by tests like this.
- */
-
-import { PostgreSqlContainer, StartedPostgreSqlContainer } from '@testcontainers/postgresql';
-import { Pool } from 'pg';
-import request from 'supertest';
-import { afterAll, beforeAll, describe, expect, test } from 'vitest';
-
-// Replace with your real app/server factory
-import { buildApp } from '../app';
-
-let container: StartedPostgreSqlContainer;
-let pool: Pool;
-let app: ReturnType<typeof buildApp>;
-
-beforeAll(async () => {
-  container = await new PostgreSqlContainer('postgres:16-alpine').start();
-  pool = new Pool({ connectionString: container.getConnectionUri() });
-  // Run migrations
-  await pool.query(`CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT UNIQUE)`);
-  app = buildApp({ db: pool });
-}, 60_000);
-
-afterAll(async () => {
-  await pool.end();
-  await container.stop();
-});
-
-describe('vertical slice: POST /signup', () => {
-  test('inserts a row, returns 201, body matches input email', async () => {
-    const before = await pool.query('SELECT count(*) FROM users');
-    const beforeCount = parseInt(before.rows[0].count, 10);
-
-    const res = await request(app)
-      .post('/signup')
-      .send({ email: 'vertical@example.com' })
-      .expect(201);
-
-    // 1. response shape
-    expect(res.body.email).toBe('vertical@example.com');
-    expect(res.body.id).toBeGreaterThan(0);
-
-    // 2. real DB write occurred
-    const after = await pool.query('SELECT count(*) FROM users');
-    expect(parseInt(after.rows[0].count, 10)).toBe(beforeCount + 1);
-
-    // 3. data is persistable / queryable
-    const row = await pool.query('SELECT email FROM users WHERE id = $1', [res.body.id]);
-    expect(row.rows[0].email).toBe('vertical@example.com');
-  });
-});

package/skills/ultra-tdd/references/test-execution.md

@@ -1,23 +0,0 @@
-# Test execution evidence
-
-Resolve the canonical command from package scripts, CI configuration, repository
-guidance, or framework files. When two commands prove different contracts, keep the
-distinction visible instead of choosing the easier one.
-
-For every baseline, red, and green run record:
-
-- exact command and working directory;
-- start time, duration, and exit code;
-- runner-reported pass, fail, skip, and coverage counts when available;
-- first useful failure with tight source or test location;
-- whether it reproduces and whether it is product, test, environment, or flaky evidence;
-- raw output path under `.ultra/evidence/<task-id>/` and the lowercase SHA-256 of its
-  exact bounded stable bytes when the output matters.
-
-Do not weaken flags, skip a relevant failure, edit test configuration to obtain green,
-or claim success when the command did not finish with exit zero. A concise evidence
-record may cite the raw log; it must not copy an entire transcript into task context.
-Before citing one, require a repository-contained ordinary regular non-symlink file,
-opened nonblocking and no-follow with an 8 MiB ceiling and unchanged path/descriptor
-identity around the read. Hash that one snapshot; a missing, escaped, special, symlinked,
-oversized, or replaced receipt is a typed evidence gap, not a successful run record.

package/skills/ultra-test/SKILL.md

@@ -1,244 +0,0 @@
----
-name: ultra-test
-description: Audit whole-system integrity after tasks for the active Change are complete by finding anti-patterns, coverage gaps, broken wiring, E2E failures, performance risk, and security risk. Use when preparing delivery or when locally green tasks may not form a working product.
----
-
-# NOT for running unit tests (that's `ultra-dev`). This audits whole-system integrity before delivery.
-
-This is the one end-of-change sensor allowed by PHILOSOPHY C4: an export cannot be
-called orphaned while a later task may still wire it. It is a terminal sensor, never a gate;
-the owner decides what to fix or accept.
-
-## Route modes
-
-| Mode | Entry | Observable exit | Next |
-|---|---|---|---|
-| `audit` | Explicit invocation or a valid Execution Grant after every matching task has current completion evidence | One current whole-Change report and aggregate review preserve all six audit areas, findings, omissions, identities, and dispositions | Recommend `ultra-deliver/reconcile` when current, or the owner-selected responsible route |
-| `reaudit` | Explicit invocation or a valid Execution Grant after an owner-dispositioned repair invalidates the prior report | A fresh report binds the repaired Change snapshot without hiding earlier findings | Recommend `ultra-deliver/reconcile` when current, or another bounded owner disposition |
-
-Follow `../ultra-status/references/route-contract.md`. Show a Route Card at audit entry,
-before asking for finding disposition, and at the report exit. Audit counts and review
-events populate `Position` or `Reality`; they never choose repair, convergence, or risk
-acceptance. Test does not call its own repair route.
-
-## Before you start
-
-1. If model-selected, verify the live execution grant in `../ultra-change/references/execution-grant.md` — a current session-local activation or a stably verified durable work-package grant; without either, stop.
-2. Read `../ultra-change/references/change-contract.md` and apply its **Active Change
-   authority resolution** before reading any active `intent.md` or resolving a current
-   `change_id`. This workflow requires its one valid active authority; any zero result
-   or typed diagnostic stops before audit input is read until the stated repair or retry
-   succeeds. Read `.ultra/tasks.json` and only tasks whose `change_id` matches the active
-   Change. Every matching task must be `completed` in that sole task-status authority.
-   Read each task's `context_file` Acceptance, Completion, Task Review and closing
-   `## Resume Note`.
-   Historical tasks are not part of this audit snapshot. For every current Change task,
-   require a current `ultra-task-evidence-v2` record whose context, subject, acceptance,
-   and task-review bindings satisfy `../ultra-plan/references/task-evidence-v2.md`.
-   A legacy context Status or Complexity header and v1 evidence remain migration
-   diagnostics only; recommend Dev repair rather than treating them as current Test input.
-3. Read `CONTEXT.md` for vocabulary and the relevant `.ultra/decisions/` entries.
-4. Read the active Change intent, the task evidence directories and the current Git
-   `HEAD`; old output is evidence only for the commit it names.
-   Resolve Change and task `FP-*`, `NS-*`, and `HC-*` IDs against the accepted North
-   Star revision. A stale trace is an explicit finding requiring reconciliation, not a
-   silent rewrite or automatic failure verdict.
-5. Resolve this loaded Skill's directory and run
-   `node <ultra-test-skill-dir>/scripts/worktree_digest.cjs --project <repository-root> --change-id <change_id>`
-   before and after the audit. It returns the stable Change id, exact intent SHA-256,
-   HEAD, and product-worktree digest. The product-worktree digest has one fixed boundary:
-   it excludes `.ultra/evidence/**`, whose command and external-observation entries bind
-   raw bytes as `raw_evidence_sha256` before stable exact record bytes are bound as
-   `evidence_digest`. It also excludes the report and
-   all active/archive/abandoned Change-directory metadata. Intent freshness is checked
-   separately, so publishing or refreshing evidence, writing delivery metadata, or moving
-   the same Change cannot self-invalidate its tested product snapshot. Exact task-evidence
-   and review-receipt digests remain mandatory through their existing consumers; this is
-   not a caller-configurable exclusion. This digest defines the aggregate Change subject
-   for the current whole Change; it is distinct from each task's earlier
-   completion-snapshot freshness observation.
-
-## Definition of done
-
-- All six audit areas have an evidence-backed result or an explicit material omission.
-- Wiring lists each changed export and its non-test consumers; zero matches are visible
-  as orphan findings.
-- `.ultra/test-report.json` records `change_id`, the exact current-Change `task_ids`,
-  `intent_digest`, `git_commit`, commands, findings, omissions and the owner's
-  disposition without rewriting a finding into a pass.
-- Every current task's v2 evidence and retained task-review summary is consumed; blocking
-  findings, resolutions, disagreements, and refresh references remain attributable.
-- One current aggregate Change review is referenced by session, packet digest, exact
-  admission and subject digests, execution mode, coverage, summary path, exact summary
-  SHA-256, and verdict.
-- The report names `ultra-review-findings-v4` and copies every review finding unchanged,
-  including `north_star_trace.first_principles`, `.serves`, and `.touches`, so each
-  finding carries its resolving `FP-*`/`NS-*`/`HC-*` IDs and Deliver can
-  test evidence against outcome without copying the North Star prose.
-
-## Audit six areas
-
-1. **Anti-patterns**: find tautological or empty tests and internal collaborators mocked
-   instead of exercising a public seam.
-2. **Coverage gaps**: map changed public behavior to tests and list behavior with no
-   exercising test.
-3. **Wiring Verification**: list changed exported symbols, then search each name in
-   non-test source. `0 matches = orphan` until a framework registration or generated
-   consumer is evidenced. Also trace Component→API, API→DB, Form→Handler and
-   State→Render where those boundaries exist.
-4. **E2E**: run the smallest real primary flow through its deployed or local boundary.
-5. **Performance**: measure the paths whose acceptance or risk makes latency, resource
-   use or scale material; record why anything else was omitted.
-6. **Security**: run the repository's dependency and security checks, then inspect the
-   trust boundaries changed by this Change.
-
-The six are independent read-only audits and may run in parallel through the host's
-native bounded subagents. Each returns its findings; the parent writes the one report.
-A worker never writes `.ultra/test-report.json` itself — six writers on one canonical
-file is how a report loses findings.
-
-Read `references/export-syntax.md` before collecting exports. The table finds
-candidates; repository conventions and real consumers decide what is public.
-
-After the six areas, follow `../ultra-review/SKILL.md` for an aggregate Change review.
-Read only its validated summary, preserve its findings, and carry the review session,
-packet digest, admission digest, subject digest, execution mode, coverage refs, summary
-ref, verdict, and limitations into the report. Record
-`review.finding_schema: "ultra-review-findings-v4"`; copy each finding
-object unchanged from the v4 summary, including `north_star_trace`. An incomplete review
-stays an omission; it never becomes a silent pass. Historical v3 review is evidence only:
-run a fresh v4 aggregate review before a current Test claim.
-
-Before accepting copied review metadata or findings, replay the exact frozen
-`SUMMARY.json` through the sibling `ultra-review/scripts/review_wait.py` v4 summary
-validator. Strict v4 replay is the default and requires the same session's valid
-`ADMISSION.json`; `--legacy-v4` is an explicit read mode only for immutable historical
-pre-admission evidence and cannot support a current Test claim. Then bind its
-`change_id`, ordered `task_ids`, `head`, `admission_digest`, `subject_digest`,
-`context_digest`, and
-honest nullable `worktree_digest` to the Test report's root identity and `review`
-provenance fields. The transport sensor accepts only canonical
-`.ultra/test-report.json` and the normalized repository-relative
-`.ultra/reviews/<session>/SUMMARY.json` it names. Both use the same bounded stable
-raw-byte snapshot rule: every managed path component below the real repository root is
-non-symlink, the final entry is a repository-contained regular file, and an 8 MiB + 1
-byte observation returns a typed oversize diagnostic before JSON parsing or hashing.
-The final file is opened with `O_NONBLOCK` and `O_NOFOLLOW`; its descriptor is
-immediately required to be a regular file with the inspected path identity. A type or
-identity replacement returns the existing retryable snapshot diagnostic instead of
-waiting on a special file.
-The sensor uses one report snapshot for report parsing and subject comparisons, and one
-summary snapshot for summary parsing, SHA-256, comparisons, and the waiter's stdin
-validation. After writing those exact values and findings, run
-`node <ultra-test-skill-dir>/scripts/validate_review_transport.cjs --summary <validated-summary-path> --report .ultra/test-report.json`.
-Record that exact command, exit code, and evidence reference in `commands`. A nonzero
-result is a typed transport observation: repair the report copy and rerun it; never drop,
-merge, inject, or rewrite a finding to obtain a pass. This sensor compares exact summary
-bytes, review metadata, and finding objects only. It does not reinterpret a finding or
-decide the audit verdict.
-
-Validate each task evidence record with the shipped v2 structural sensor before using
-it. For every record whose `task_review.review_mode` is `external-manual`, rerun the
-sensor with `--verify-external-receipt` and recheck the declared receipt branch — the
-bounded stable receipt bytes, its recorded SHA-256, and its task/change/subject
-identity — instead of replaying a strict summary; strict-v4 records keep their exact
-waiter and transport replay. A task's declared branch is preserved as-is in the
-ordered `task_evidence` projection, consuming each item from the sensor's
-`--projection` output verbatim: an external-manual item carries `task_review_mode`,
-`task_review_receipt_ref`, and `task_review_receipt_digest` where a strict item
-carries its session and summary digest. Never rewrite one branch into the other. The CLI establishes only JSON shape, token syntax, and
-authority designation; it does not prove current identity, provenance, freshness,
-or semantic acceptance. Test
-takes each command and external-observation `raw_evidence_ref` to bounded stable
-repository-contained bytes from an ordinary regular non-symlink file opened nonblocking
-and no-follow, with an 8 MiB ceiling and path/descriptor identity checks around the read.
-Recompute `raw_evidence_sha256` from that one snapshot and require an exact match. Then
-recompute the stable exact `evidence.json` bytes as `evidence_digest` before copying the
-ordered `task_evidence` projection; a raw or record mismatch is an evidence gap returned
-to Dev.
-Test
-takes stable bytes independently, then rechecks and recomputes the current Acceptance-section SHA-256, aligns exact criterion IDs and verification types with the current context, and aligns the task-review session and summary digest with the retained strict summary. For `owner-judgment`, require that the durable owner record exists with its cited statement and disposition readable before rechecking all cited affected artifacts.
-The `subject` is an independently captured completion-snapshot freshness observation made after the final strict task Review validates and immediately before evidence publication; `task_review` separately binds the retained strict summary. Worker Packet v1 carries no task worktree digest and its summary records `worktree_digest: null`, so Test never claims that those review artifacts prove or cryptographically bind `subject.worktree_digest`. It also never replaces that earlier observation with the later aggregate Change digest.
-The owner alone supplies an owner-judgment result. A later task may change the aggregate
-worktree without invalidating an earlier task, but any changed acceptance, owner record,
-review binding, or cited artifact that no longer supports its criterion is a mismatch.
-Any mismatch is an evidence gap: return the affected task and criterion IDs to Dev, or
-return a missing owner judgment to the owner. Test never edits task status. Dev records the reason and performs
-the explicit ledger `completed` to `in_progress` reopen; no silent demotion is allowed.
-Never turn structural sensor success into any of those consumer conclusions.
-
-This is a cooperative-workspace drift sensor, not an operating-system isolation
-primitive. Use one fixed closing protocol: one complete primary observation followed by
-one terminal seal. A persistent mismatch observed inside or before that terminal seal
-returns typed `ULTRA_SNAPSHOT_CHANGED_DURING_OBSERVATION` recovery instead of publishing
-the tuple. A cooperative write after the completed terminal seal belongs to the next
-consumer, which must perform a fresh recapture before using the tuple. Hostile writers or
-interleavings require a native Host sandbox or an isolated worktree. Never add an
-unbounded success-seeking replay.
-
-Aggregate finding disposition is bounded: P2 and P3 findings are recorded as backlog or
-residual risk and never automatically returned to Dev, and this audit writes
-non-blocking refactor observations into the report instead of reopening a completed
-task. An implementation P0/P1 found here returns to Dev as at most one new
-owner-approved repair task; there is no unbounded Test ↔ Deliver bounce, and any
-re-entry through Test after a report is consumed requires an explicit owner
-disposition.
-
-The receipt is non-authoritative derived evidence, but retain it until both Test and
-Deliver have consumed the review. If it is missing, the current session and Test claim
-are `INCOMPLETE`; start a fresh review session. Do not reconstruct it or use
-`--legacy-v4` to bypass loss from a current strict session.
-
-## Detect substantive stubs
-
-Report an empty return with no IO, a log-only function, a handler that only prevents
-default, or a component that only renders placeholder text. Pair every finding with
-the smallest real boundary or implementation that would make it observable.
-
-## Write the report
-
-Store the exact `change_id`, ordered current-Change `task_ids`, `intent_digest`,
-`git_commit`, timestamp, run count, commands and exit codes, the six area results,
-findings with paths, verified seams, material omissions, residual risk, and `passed` as
-the model's evidence-derived summary in the one canonical
-`.ultra/test-report.json`. Each command records `command`, `exit_code`, and an
-`evidence_ref`; each area records `status`, `evidence_refs`, and `omissions`. Copy the
-worktree script's `head`, `dirty`, `diff_digest`, and `intent_digest` into the report.
-That worktree identity binds the current whole Change, while ordered `task_evidence`
-items preserve each task's distinct completion-snapshot freshness observation and
-separate task-review identity.
-Copy the validated review summary's exact SHA-256 into `review.summary_digest`; the
-transport validator recomputes it before the report can be current evidence. A stale
-commit, product digest, intent digest, Change id, or task-id snapshot is labelled stale;
-it is never reused as current proof.
-
-`passed` is a one-way claim: `true` requires every current-Change task completed in the
-ledger, current v2 task evidence and task-review provenance, and no required area left
-`not_run`. Completed rows do not force `passed: true`; findings, omitted evidence, or a
-failed command may keep it false, while an explicitly dispositioned gap remains visible
-even if the model's evidence summary passes. Preserve the finding and the owner's
-disposition as separate fields. No validator result is itself semantic acceptance.
-
-Present the findings by consequence and recommend the highest-leverage response. The
-owner may fix all, fix selected findings, accept recorded risk, or reduce scope through
-the normal REDUCTION decision. Recommend the next capability. Continue only when the
-owner disposition or existing grant covers its exact mode and effects, and show the
-transition Route Card first; Test itself never manufactures that coverage.
-
-## When the owner decides
-
-The owner decides disposition and risk acceptance. A failed command, orphan or stub is
-an observation, not permission to auto-fix, weaken a test or silently change scope.
-
-## References
-
-- `../ultra-change/references/change-contract.md` — canonical Active Change authority resolution.
-- `references/export-syntax.md` — read during Wiring Verification to find exported
-  symbol candidates in TypeScript/JavaScript, Python, Go, Rust and Java.
-- `scripts/worktree_digest.cjs` — deterministic HEAD plus worktree evidence identity.
-- `../ultra-review/SKILL.md` — read for aggregate Change review after the six-area audit.
-- `../ultra-plan/references/task-evidence-v2.md` — canonical current task evidence and task-review contract.
-- `../ultra-change/references/execution-grant.md` — read only for grant-activated continuation.
-- `../ultra-status/references/route-contract.md` — owner-visible route, checkpoint, and recovery output.
-- `../ultra-think/references/autonomy-boundary.md` — read when a proposed response
-  would make an existing specification commitment stop holding.

package/skills/ultra-test/references/export-syntax.md

@@ -1,18 +0,0 @@
-# Export syntax lookup
-
-Use this table to collect candidates, then confirm public reachability through the
-repository's build system, framework registration and non-test consumers. Text matches
-are observations, not semantic proof.
-
-| Language | Candidate forms to search |
-|---|---|
-| TypeScript / JavaScript | `export function`, `export class`, `export const`, `export { name }`, `module.exports`, `exports.name` |
-| Python | top-level `def` and `class`, names in `__all__`, public package re-exports; exclude leading-underscore names unless explicitly exported |
-| Go | package-level identifiers beginning with an uppercase letter |
-| Rust | `pub fn`, `pub struct`, `pub enum`, `pub trait`, `pub use`; respect module visibility such as `pub(crate)` |
-| Java | `public` top-level types and public members reachable through the package's exposed API |
-
-For every candidate changed by the current Change, search the exact symbol in non-test
-source. Zero references is an orphan candidate. Before recording it, check declarative
-framework entry points, reflection, dependency injection, generated code and foreign-
-function bindings that may consume the symbol without a textual import.