diff --git a/.claude/skills/analog-emulation/SKILL.md b/.claude/skills/analog-emulation/SKILL.md index 49cac178e6..e585dd4afd 100644 --- a/.claude/skills/analog-emulation/SKILL.md +++ b/.claude/skills/analog-emulation/SKILL.md @@ -37,13 +37,42 @@ Each milestone follows M0's shape. Do not mark one done until all five hold: 4. **Board receipt.** Bitstream from `t27b verilog` (no hand HDL, no XDC), run on the AX7203 bench (`board-eye`, `bench-agent` skills). Record LUT, FF, DSP, BRAM, Fmax and the UART line. 5. **Oracle.** From M3 on, ngspice with the named PDK revision and corner. From M5 on, Symbiotic EDA's self-checking evaluator decides. -Then: close the sub-issue with `Closes #N`, tick it in the epic, open the next milestone's sub-issue in the same Goal / Boundary / Scenarios / Requirements shape, update the dashboard, and draft a report. +Then: close the sub-issue with `Closes #N`, tick it in the epic, open the next milestone's sub-issue in the same Goal / Boundary / Scenarios / Requirements / Success Criteria shape (the issue-shape bot closes an issue without `## Success Criteria`), update the dashboard, and draft a report. ### Technical choices that are already decided -- **Fixed step, compile-time matrices.** Linear MNA `(G + C/dt) x' = (C/dt) x + B u` folds to `x' = M x + N u` with constants; no solve and no division in fabric. M0 is the 1x1 case (`g = 1/21`). The stability invariant (quantized `M`, spectral radius < 1) belongs in the spec's tests. +- **Fixed step, compile-time matrices, delta form.** Linear MNA `(G + C/dt) x' = (C/dt) x + B u` folds to `x' = x + rnd(D x + N u)` with `D = M - I` and `N` quantized to Q.24, the sum accumulated exactly and rounded once, half away from zero. M0 is the 1x1 case (`D = -798915`, `N = 798915`), so M0 is reproduced bit for bit by construction. No solve and no division in fabric. +- **Stability is proved:** `||M_q^256||_inf < 1` in the tests (bounds the spectral radius); `||M_q||_inf < 1` alone fails for an underdamped RLC. +- **Unsigned in hardware.** `t27b verilog` refuses signed types, so the step keeps a sign flag per term with unsigned magnitudes, as M0 does. f64 is fine inside tests. - **Nonlinear devices as per-corner tables first.** `Id(Vgs, Vds)` from the PDK's PSP103 in ngspice, one table per corner (tt ff ss fs sf), one bitstream per corner. Compact-model (Verilog-A) ingest is post-v0.1 research; never promise it for v0.1. -- **Designers keep their netlist.** The entry point is a SPICE subset read by a t27 program. Unsupported input is refused with the line and the reason, never approximated silently. +- **Designers keep their netlist; the reader is a t27o front end.** The SPICE subset reader is `specs/tools/t27o/spice_convert.t27` beside `rust_convert.t27`, run as `tri t27o `, so the project has one converter, not two (DRY). Unsupported input is refused with the line and the reason, never approximated silently. Real IHP decks need `.subckt`, instance parameters (`w`, `l`, `ng`) and `.lib` corner selection early, not late. + +## Toolchain for an analog milestone + +| Step | Command | Note | +|---|---|---| +| syntax | `./target/release/t27c check ` or MCP `t27_check` | parse + typecheck only | +| tests | `./target/release/t27c test-report ` | per-test assert counts; read `vacuous passes` (must be 0); `tri test` does not check vacuity yet (#10497) | +| negative control | copy to `$TMPDIR`, break one constant, `test-report` | must FAIL before the PR | +| seal | `t27c seal --save`, then `--verify` | commit `.trinity/seals/_.json` | +| board top | `t27b verilog ` | pin attributes in the spec, no XDC; no signed types | +| board run | M0's flow, AX7203 = `xc7a200tfbg484-2`, `openFPGALoader -c digilent_hs2` | `t27c fpga-build/fpga-flash` default to Wukong (#10498) | +| converter | `tri t27o [--check]` | Rust only today; SPICE front end is M2 | +| who else | `tri topic analog spice ` | before opening an issue or a lane | +| PR verdict | `tri pr ready --required-only` | one VERDICT line | + +Sandboxed sessions: `export ZIG_GLOBAL_CACHE_DIR=$TMPDIR/zig-cache ZIG_LOCAL_CACHE_DIR=$TMPDIR/zig-local`; commit with `git -c core.hooksPath=.githooks commit`; `gh` fails TLS, use curl with `$(gh auth token)`. There is no `t27t` in this repository (searched 2026-10-18); do not invent one. + +## The overnight loop tick + +A `/loop` tick on this epic follows this order, so a new tick never undoes or duplicates the last one: + +1. **Read state.** The ledger is a comment on #10486 (the one headed "Loop ledger"). Read it, `CronList` (delete duplicate crons after a restart), and list running subagents. A lane the ledger says is running is not started again. +2. **Look for anomalies before new work.** Open PRs of this epic that are red, conflicting or stale (`tri pr ready`); a subagent that reported done but whose PR does not exist (`git ls-remote`); a merged PR whose spec is missing on master (`tri pr landed`); a seal that no longer verifies (`tri seals drift`); a ledger row older than 45 minutes still "running". Fix or file each one first (self-repair beats new work). +3. **Review on Opus, implement on Sonnet** (`specs/claw/model_route.t27`): at most 3 subagents on the 8 GB Mac; each lane in its own worktree and branch; the orchestrator reads every diff before auto-merge is enabled. +4. **Merge only green.** Auto-merge after the required checks pass. A red is inherited only if it is a subset of master's failures; `claw-sarif` failing on "permissions requested are not granted to this installation" is the known App-permission red (owner steps in `docs/claw/README.md`). +5. **Write state.** Edit the ledger row, tick the epic's Progress table, republish the dashboard, and add a learning to this skill when a trap cost more than one try. +6. **Reports** to the partner are drafted into the dashboard; they are sent only after the owner's explicit yes in chat. ## Claim guard diff --git a/.claude/skills/tri-pipeline.md b/.claude/skills/tri-pipeline.md index 333a8dea8f..42d8b088c3 100644 --- a/.claude/skills/tri-pipeline.md +++ b/.claude/skills/tri-pipeline.md @@ -1,12 +1,5 @@ --- -description: Execute tri pipeline commands for spec-first development -parameters: - - name: command - type: string - description: tri command (gen, test, verify, seal) - - name: spec - type: string - description: Path to .t27 spec file +description: Execute tri pipeline commands for spec-first development -- pointer to .claude/skills/tri-pipeline/SKILL.md --- # TRI Pipeline Skill @@ -20,42 +13,4 @@ parameters: > - What gen cannot express yet is a compiler defect. File it on #5980 with a minimal `.t27` repro instead of writing the code by hand. > - This rule overrides any step below that says to write a script or code in another language. The full text is in `AGENTS.md`, "Only t27". -The tri pipeline is the primary tool for spec-first development in t27. - -## Commands - -### `tri gen ` -Generate code from .t27 specification. -- Outputs to `gen/` directory -- Never hand-edit generated files -- Modify spec to change behavior - -### `tri test` -Run conformance tests. -- Executes all .t27 specs -- Validates invariants and test cases -- Returns TAP format results - -### `tri verify ` -Verify a single specification. -- Checks test/invariant/bench sections -- Validates generated code matches spec - -### `tri seal ` -Seal specification hash. -- Creates cryptographic seal for traceability -- Required before merge - -## Usage Flow - -1. Write .t27 spec with test/invariant/bench -2. `tri gen ` - generate code -3. `tri test` - run all tests -4. `tri seal ` - seal hash -5. Create PR with `Closes #N` reference - -## Important - -- L2 (GENERATION): Never edit files under `gen/` directly -- L4 (TESTABILITY): Every spec must have test/invariant/bench -- Use L7 (UNITY): Prefer tri over shell scripts +This file used to carry its own command list, which named `tri verify` (it does not exist) and said `tri test` runs one spec (`scripts/tri test` runs the whole-repo suite). The one maintained list is **`.claude/skills/tri-pipeline/SKILL.md`**; read that. diff --git a/.claude/skills/tri-pipeline/SKILL.md b/.claude/skills/tri-pipeline/SKILL.md index 62428eff2b..631f3093a2 100644 --- a/.claude/skills/tri-pipeline/SKILL.md +++ b/.claude/skills/tri-pipeline/SKILL.md @@ -1,7 +1,7 @@ --- id: tri-pipeline name: TRI Pipeline -description: Execute tri commands (gen, test, verify, seal, verdict) for spec-first development +description: The exact commands of the t27 toolchain (tri, t27c, t27b, tri t27o) for spec-first work -- check, test with per-test counts and vacuity, seal, lower to Verilog, convert foreign code, gate a PR. Every command named here exists; checked against --help on 2026-10-18. --- # TRI Pipeline Skill @@ -15,102 +15,63 @@ description: Execute tri commands (gen, test, verify, seal, verdict) for spec-fi > - What gen cannot express yet is a compiler defect. File it on #5980 with a minimal `.t27` repro instead of writing the code by hand. > - This rule overrides any step below that says to write a script or code in another language. The full text is in `AGENTS.md`, "Only t27". -Execute the canonical t27 toolchain commands. +## Three things called `tri` -## Commands +| Name | What it is | Note | +|---|---|---| +| `scripts/tri` | bash front door; runs `scripts/tri_loop/*.py` helpers first (`pr-state`, `priority`, `triage`, `tick`, `t27b`, `toolbelt`, `damage`, `swarm`; list: `tri loop-help`), else forwards to `t27c` | `scripts/tri test` is the WHOLE-REPO `t27c suite`, not one spec | +| `target/release/tri` | Rust CLI, `cargo build --release -p tri`, ~55 subcommands; `--help` is the authority | `tri test ` is the one-spec runner | +| `t27c` | the compiler, `cargo build --release -p t27c` | lands at `./target/release/t27c` (workspace root) | -### `tri gen` -Generate code from .t27 specifications. +Use `./target/release/tri` and `./target/release/t27c` by path when the difference matters. -```bash -tri gen specs/ring-NNN-name.t27 -``` - -**Output**: Generated files in `gen/` directory -**Laws**: L2 (GENERATION) - gen/ is read-only -**Verification**: Hash verification during seal phase - -### `tri test` -Run conformance tests from specifications. - -```bash -tri test specs/ring-NNN-name.t27 -``` - -**Output**: Test results, pass/fail status -**Laws**: L4 (TESTABILITY) - specs must have tests -**Success Criteria**: All tests pass, invariants satisfied - -### `tri verify` -Verify all 7 invariant laws. - -```bash -tri verify -``` - -**Checks**: -- L1: Commits have issue references -- L2: No manual edits to gen/ -- L3: ASCII-only source files -- L4: All specs have tests -- L5: φ identity constraints -- L6: FORMAT-SPEC-001.json authority -- L7: No new shell scripts on critical path - -**Output**: Pass/fail for each law -**Block**: Non-compliant commits are blocked - -### `tri seal` -Generate and verify seal hash. +## One spec, end to end ```bash -tri seal specs/ring-NNN-name.t27 +export ZIG_GLOBAL_CACHE_DIR=$TMPDIR/zig-cache ZIG_LOCAL_CACHE_DIR=$TMPDIR/zig-local # sandboxed sessions +./target/release/t27c check specs//.t27 # parse + typecheck, fast +./target/release/t27c test-report specs//.t27 # runs every test; per-test assert counts; "vacuous passes N of M" +./target/release/tri test specs//.t27 # exit code gate over test-report (does not yet fail on vacuous: #10497) +./target/release/t27c seal specs//.t27 --save # writes .trinity/seals/_.json +./target/release/t27c seal specs//.t27 --verify # must print "all hashes MATCH" ``` -**Output**: Hash of generated artifacts -**Purpose**: Immutable snapshot for verification +- `t27c test ` only LISTS the test blocks; it runs nothing. Never quote it as a test result. +- A pass with 0 runtime asserts is vacuous. Read the `vacuous passes` line of `test-report` yourself until #10497 lands. +- Negative control: copy the spec to `$TMPDIR`, break one constant, run `test-report`, and see a FAIL before you claim the tests mean anything. +- `t27c test-report` exits 1 on FAIL and 2 on BLOCKED (did not compile). -### `tri verdict` -Generate formal pass/fail verdict. +## Generate and lower -```bash -tri verdict -``` +- `t27c gen-verilog | gen-c | gen-rust | gen ` print to stdout (`gen` is Zig). `tri gen ` runs gen-verilog, gen-c and gen-rust to stdout and writes nothing. +- `t27b verilog ` (native backend, `cargo build --release -p t27b`) is the path for FPGA board tops: it can instantiate primitives and other modules, takes pin attributes `_LOC|IOSTANDARD|SLEW|IN_TERM` (no XDC), and writes a testbench under `-DT27B_TESTBENCH`. It **refuses signed types** (exit 2): fixed-point hardware specs keep a sign flag with unsigned magnitudes. +- `t27b test [--check]` is the AArch64 JIT runner (fast; prints total runtime asserts, not per test). Exit 4 means the JIT and the interpreter disagree. +- AX7203 caveat (#10498): `t27c fpga-build` defaults to the Wukong fgg676 part and `t27c fpga-flash` has no ax7203 board; the AX7203 is `xc7a200tfbg484-2` (`fpga/HARDWARE_SSOT.md`). Follow M0 (`specs/fpga/rc_filter_ax7203.t27`, #10276) for the board flow. -**Output**: -- Overall status: PASS | FAIL -- Law compliance breakdown -- Required fixes for failures +## Foreign code in -### `tri experience save` -Save episode to experience log. +- `tri t27o [--name N] [--oracle] [--check]` turns a Rust file into a `.t27` skeleton; refused bodies keep their signature and a comment naming the refused construct. Rules: `specs/tools/t27o/rust_convert.t27`. Rust is the only front end today; a new language is a new `specs/tools/t27o/_convert.t27` beside it (the SPICE front end for #10486 goes there). -```bash -tri experience save --ring 72 --phase verify --outcome success -``` - -**Output**: Entry in `~/.trinity/experience/episodes.jsonl` +## Is someone already on it? -### `tri experience query` -Search past episodes. +- `tri topic ` -- open issues, PRs and recent commits that match. Run it before opening an issue or a lane. +- `tri loop claim ` -- take a named claim so two loop ticks or sessions cannot pick the same task. -```bash -tri experience query "how to fix L5 violation" -``` +## Pull requests and CI -**Output**: Relevant past episodes with solutions +- `tri pr ready [--wait --required-only]` prints one `VERDICT:` line (safe to merge, DO NOT MERGE, WAIT, CANNOT TELL, NEW REASON) after classifying every failing check. +- `tri pr landed --probe S --file P` -- did the content actually reach the default branch. +- `tri night`, `tri red now|why`, `tri ci baseline`, `tri gates ...`, `tri merging`, `tri lanes --repo t27 --base master`. +- `tri seals fresh|drift|twins|hollow` -- seal health across the tree. +- `tri hooks pre-commit|commit-msg|pre-push|l1-check|status` -- the commit gates, runnable by hand. +- Commit in a worktree with `git -c core.hooksPath=.githooks commit`: the configured hooks path is the main checkout's. -## Error Handling +## Experience -If a command fails: -1. Log error with context -2. Suggest fix based on error type -3. Check experience for similar past issues -4. Retry with modified inputs if applicable +- `tri experience save` (no flags) is the only experience command. There is no `tri experience query` and no `tri verify`. -## Success Indicators +## MCP servers -- Command exits with code 0 -- Output contains expected patterns -- No law violations detected -- Artifacts are generated correctly +- **t27 MCP** (gHashTag/t27-mcp, local stdio): `t27_check` (compiler front end in wasm: parse + typecheck only, no tests), `t27_spec`, `t27_specs`, `t27_grep`, `t27_find`, `t27_examples`, `t27f_outline`, `t27f_graph`, `t27_dashboard` and more. Use `t27_check` for a fast syntax check without a build. +- **TRI CLAW** (`/mcp` of the vibee-render service): about 170 tools; `t27_specs` and `hdl_run` (verilator lint, iverilog sim, yosys synth_xilinx) are the ones spec work uses. The t27 tools are being mounted there (#10483, gHashTag/t27-mcp#26). +- `cli/tri-mcp` is not buildable (not a workspace member, #5395) and its `tri_test` only lists tests (#8140, fix in #8149). Do not rely on it.