Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions .trinity/seals/promotion_promotion_t27l.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{
"built_by": "t27c-bootstrap@0.5.2+116178f1d",
"closure": [],
"config": "gen=c,rust,verilog,zig;tests=zig",
"gen_hash_c": "sha256:ac1bc71e3fb8077927876b02b4784ed7cd829bab6ef634c59baa886e4002377a",
"gen_hash_rust": "sha256:4c98699ffa7aaa447963d8436399140627e2b23bffed9354fd4910af7147e667",
"gen_hash_verilog": "sha256:8986ee282cd9a04b35123b534764c9a6721e09e7cf1fd295eb939b2b612eecc9",
"gen_hash_zig": "sha256:b4ba4e472b74fddad87c8b0a49f6bf4ae755f6175bbe030bdb014406b72fc561",
"module": "promotion_t27l",
"ring": 12,
"seal_schema": 2,
"sealed_at": "2026-11-09T18:16:47Z",
"sealed_by": "t27c-bootstrap@0.5.2",
"spec_hash": "sha256:a086430758531b6918cb62209c7de538250d4771e7e9b7430b35319501911e2a",
"spec_path": "specs/promotion/t27l_promotion.t27",
"tests": {
"failed": 0,
"failing": [],
"forced": false,
"passed": 6,
"total": 6,
"vacuous": 0
},
"toolchain": {
"test_runner": "sha256:1a50286d6170ef41c779d26385a1be59823925d7131497c93d84194144ba93b3",
"zig": "0.16.0"
}
}
33 changes: 33 additions & 0 deletions docs/promotion/contributor-path.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Contributor path

Part of #13473. Issue #13481. Status: DRAFT_UNSENT. This run filed no issue and sent no mail.

## Existing entry

`CONTRIBUTING.md` is the entry point already in the repo. It tells a contributor to read `SOUL.md`, `OWNERS.md`, and to reference a GitHub issue. The issue-shape sections a new issue needs are Boundary, User Scenarios, Requirements, and Success Criteria (`specs/policy/issue_shape.t27`, named from `AGENTS.md`).

## Good-first-issue label

Open issues with that label: 0.

Command: `gh api -X GET search/issues -f q='repo:Trinity-S-AI-DNA/t27 is:issue is:open label:good-first-issue' -f per_page=1 --jq .total_count`

No template file for that label existed under `docs/promotion/` before this pack. The proposed shape, not a filed issue, is `docs/promotion/good-first-issue-template.md`.

## Path

1. Read `CONTRIBUTING.md`.
2. Pick a lesson row in `docs/promotion/course-map.md` whose `frame_next` cell is not blank (eight rows; `specs/course/lesson_frames.t27` test `the_edit_changes_eight_frames_and_no_exempt_one`).
3. File an issue with the proposed template only after the issue-shape check the skill describes. This pack does not file it.
4. Open a pull request that references that issue.

## Asset fields

| Field | Value |
| --- | --- |
| claim | N/A |
| artifact | `CONTRIBUTING.md` and `docs/promotion/good-first-issue-template.md` |
| reproducible path | the label search above |
| visual | N/A |
| CTA | N/A -- not sent |
| metric | 0 open good-first-issue issues |
62 changes: 62 additions & 0 deletions docs/promotion/course-map.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Course map: 27 lessons

Part of #13473. Issue #13475. Status: DRAFT_UNSENT. Nothing here was posted.

## Source

Live lesson rows are `LESSON_IDS`, `LESSON_TITLES`, `LESSON_MODULES`, `LESSON_WIDGETS`, `LESSON_SPECS`, and `LESSON_GOALS` in `Trinity-S-AI-DNA/trinity` `apps/website/specs/course/course.t27`.

Fetched this run with `gh api repos/Trinity-S-AI-DNA/trinity/contents/apps/website/specs/course/course.t27`. Blob sha `3b3aa5d21a1dc86876c5b873bf6d6b8cf8d20b21`, size 28305. `LESSON_COUNT` is 27.

`specs/course/lesson_frames.t27` in this repo says `FRAME_NOW` is that `LESSON_SPECS` table as read on 2026-11-07, and `FRAME_NEXT` is the table a later course edit writes. `changed() == 8`. The column `frame_next` below is blank when the two paths are the same string.

Lesson body text was not copied. `specs/course/fpga_course_v2.t27` weak point W1 records that lesson 1 and lesson 3 still frame boards that are not the bench board `specs/boards/ax7203.t27`.

This repo's lesson 1 title in `specs/course/lesson_01_fpga_intro.t27` is `Lesson 1: What is an FPGA?`. That string is not the trinity lesson 1 title below.

## Asset fields, same for every lesson

| Field | Value |
| --- | --- |
| claim | N/A -- a lesson title is not one of the nine approved sentences in #13473 |
| visual proof | the widget id; screenshot N/A, none captured in this run |
| CTA | N/A -- not sent |
| metric | not measured |

`gallery.t27` is not in this checkout (`test -f specs/widgets/gallery.t27` exit 1). The course spec says every widget id is a gallery id. This map cannot check that membership from this tree.

## Lessons

| n | id | title | module | widget | spec now | frame_next | result named by LESSON_GOALS |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | fpga-is-a-grid | An FPGA is a grid you configure | chip | fasm-skyline | specs/boards/wukong_v1.t27 | specs/boards/ax7203.t27 | What an FPGA is made of, and why a design uses only part of the chip. |
| 2 | which-chip | Which chip is this? | chip | idcode | specs/tools/tri/fpga.t27 | | How a chip names itself in 32 bits, and how to read those bits. |
| 3 | pins-and-package | Pins, balls and the package | chip | pin-map | specs/boards/xc7a100t_minimal.t27 | specs/boards/ax7203.t27 | How the signals of your design reach the outside world. |
| 4 | bits-and-trits | Bits, trits and GF16 | numbers | gf16-calc | specs/tutorial/01_values_and_types.t27 | specs/ternary/packed_trit.t27 | How a number is stored in bits, and how balanced ternary stores it in trits. |
| 5 | what-arithmetic-costs | What arithmetic costs | numbers | cost-curves | specs/tutorial/05_widths_and_casts.t27 | specs/ternary/hybrid_arithmetic.t27 | Why a multiplier is expensive and an adder is cheap, measured on a real chip. |
| 6 | how-much-fits | How much fits on the chip | numbers | fits-on | specs/fpga/stdlib.t27 | | How to read a resource count and find which resource runs out first. |
| 7 | hello-t27 | Hello, t27 | program | play-hello-world | specs/tutorial/02_functions.t27 | | What a t27 spec looks like, and what the compiler does with it in your browser. |
| 8 | tests-are-the-spec | Tests are part of the spec | program | test-waves | specs/tutorial/07_tests_invariants_benches.t27 | | Why every t27 spec carries its own tests, and what a waveform shows. |
| 9 | compiles-is-not-correct | Compiles is not the same as correct | program | t27-tri-misread | specs/tutorial/03_operators.t27 | | Why green checks are not proof, and how to catch code that compiles and is wrong. |
| 10 | compiler-stages | The stages of t27c | compiler | t27c-stages | specs/tutorial/06_structs_enums_switch.t27 | | The path a spec takes inside t27c: tokens, syntax tree, types, HIR, code. |
| 11 | t27c-on-a-real-machine | t27c on a real machine | compiler | t27c-hello-world | specs/demos/hello_world.t27 | | The same compiler on a real machine, printing what it really prints. |
| 12 | seven-backends-and-t27b | Seven backends, and t27b | compiler | play-rust | specs/tutorial/08_modules_and_arrays.t27 | | One spec, many target languages, and a native compiler with no LLVM. |
| 13 | spec-to-verilog | From a spec to Verilog | hardware | play-verilog | specs/ternary/clocked_counter.t27 | | How a t27 function becomes logic, and how a clocked function becomes registers. |
| 14 | count-the-cells | Count the cells | hardware | stat-card | specs/tutorial/04_control_flow.t27 | specs/ternary/ternary_full_adder.t27 | How to count what a synthesizer built: LUTs, flip-flops, DSPs, block RAM. |
| 15 | one-lut-up-close | One LUT, up close | hardware | lut-explain | specs/ternary/ternary_full_adder.t27 | | What a 6-input lookup table is, and how 64 bits describe any gate. |
| 16 | synthesis-warnings | Synthesis warnings that matter | synthesis | synth-smells | specs/fpga/crossopt.t27 | | How to read a yosys log, and the warnings that become bugs on silicon. |
| 17 | state-machines | State machines | synthesis | fsm-sketch | specs/fpga/dft.t27 | specs/fpga/uart.t27 | How a synthesizer finds a state machine in your design, or refuses to. |
| 18 | where-the-luts-go | Where the LUTs go | synthesis | lut-treemap | specs/fpga/partition.t27 | | Which part of a design spends the LUTs, and why hierarchy matters. |
| 19 | placement | Placement: where the cells land | timing | placement-map | specs/fpga/placement.t27 | | What place and route does, and where it put a real design. |
| 20 | logic-depth | Logic depth | timing | lut-depth | specs/fpga/timing.t27 | | Why the longest chain of logic sets how fast a design can run. |
| 21 | timing-slack | Timing and slack | timing | slack-waterfall | specs/fpga/cts.t27 | specs/fpga/timing.t27 | What slack is, and how to read a timing report path by path. |
| 22 | fasm-to-frames | From FASM to frames | bitstream | tri-x7-fasm | specs/tools/trios/tri/x7-fasm.t27 | | What FASM is, and how features become configuration frames. |
| 23 | a-build-receipt | A build, itemised | bitstream | build-receipt | specs/fpga/adapter.t27 | specs/fpga/board_receipt.t27 | Every stage from a spec to a bitstream, with its time, tool and hash. |
| 24 | read-a-bitstream | Read a bitstream | bitstream | bit-autopsy | specs/tools/trios/tri/x7-writer.t27 | | What is inside a .bit file, and which chip it was built for. |
| 25 | jtag-asks-the-chip | JTAG asks the chip | board | tri-fpga-jtag | specs/tools/trios/tri/fpga-jtag.t27 | | How a cable finds the chip on a board and reads its IDCODE. |
| 26 | same-bits-on-the-board | The same bits, on the board | board | x7-board | specs/tools/trios/tri/x7-board.t27 | | How to show that a bitstream is byte-identical and that it runs. |
| 27 | capstone | Capstone: out-guess yosys | board | gatle | specs/fpga/e2e_demo.t27 | | Put it together: guess what a real t27 module costs in LUTs. |

Lesson 5's goal says "measured on a real chip" and does not give the number in `LESSON_GOALS`. The number is not measured in this run.

Nine module titles, from `MODULE_TITLES` in the same blob: The chip; Numbers in hardware; Your t27 program; Inside t27c; From spec to hardware; Reading synthesis; Place, route, timing; The bitstream; On the board.
24 changes: 24 additions & 0 deletions docs/promotion/good-first-issue-template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Proposed good-first-issue body

Part of #13473. Issue #13481. This is a template. It was not filed. Replace every `FILL` from a source you can name. Do not invent a lesson number or a test count.

```text
## Boundary

- FILL: one path from docs/promotion/course-map.md

## User Scenarios

**Given** the lesson row named above **when** a new contributor opens the spec **then** FILL: the check they can run.

## Requirements

- FR-001: FILL
- FR-002: The change must not post to X, LinkedIn, Telegram, Habr, or Instagram.

## Success Criteria

- FILL: one command and the output it must print.
```

The four section names are the ones `AGENTS.md` says `specs/policy/issue_shape.t27` requires.
24 changes: 24 additions & 0 deletions docs/promotion/monetization-ladder.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Monetization ladder

Part of #13473. Issue #13482. Status: DRAFT_UNSENT. No price is written. No offer was sent. The epic says not to sell "AGI access".

#13473 names five tiers and does not name a price, a SKU, or a paid package. Empty tiers stay empty.

| tier | offer named by #13473 | price | sent |
| --- | --- | --- | --- |
| Free | open artifacts in Trinity-S-AI-DNA/t27 and the 27-lesson course | none named | no |
| Low | not specified | not written | no |
| Mid | not specified | not written | no |
| High | not specified | not written | no |
| B2B | the funnel names the step and names no offer | not written | no |

## Asset fields

| Field | Value |
| --- | --- |
| claim | N/A -- no paid claim is approved in the nine sentences |
| artifact | this file |
| reproducible path | issue #13473 "Funnel" and "Approved claim patterns" |
| visual | N/A |
| CTA | N/A -- not sent |
| metric | not measured |
26 changes: 26 additions & 0 deletions docs/promotion/self-improving-loop.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Self-improving loop

Part of #13473. Issue #13484. Status: specified, not started as a job. This file does not add a workflow, does not run cron, and does not call a paid model.

## Bound

One pass, then stop.

1. Read `docs/promotion/baseline.md` and `docs/promotion/weekly-report-template.md`.
2. If a metric has no command, write `not measured`. Do not write 0 in its place.
3. If the model or the API returns a rate limit, record `WAITING_RATE_LIMIT` (`on_rate_limit(false)` in `specs/promotion/t27l_promotion.t27`) and stop.
4. `on_rate_limit(true)` is `refused`. There is no paid fallback (#13473, `FREE_MODELS_FIRST`).
5. The only edit a pass may make before a named owner approval is under `docs/promotion/` and `specs/promotion/`. It does not post.

No cron card was added. Issue #12869 asks for a blog-steward workflow. That workflow is not this loop, and it was not added.

## Asset fields

| Field | Value |
| --- | --- |
| claim | N/A |
| artifact | this file and `specs/promotion/t27l_promotion.t27` |
| reproducible path | `t27c test-report` recorded in `t27l-promotion-schema.md` |
| visual | N/A |
| CTA | N/A -- not sent |
| metric | not measured -- the loop has not run |
48 changes: 48 additions & 0 deletions docs/promotion/t27l-promotion-schema.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# T27L promotion schema

Part of #13473. Issue #13483. Status: DRAFT_UNSENT. The spec does not emit a live event and does not post.

## Surface

Name: `promotion_kernel`.

Constant: `SURFACE` in `specs/promotion/t27l_promotion.t27`.

`REGISTERED_IN_T27L` is false. `specs/t27os/t27l.t27` on master `116178f1d` sets `TL_SURFACE_LAST` to 19. `tl_surface_name` returns `course_hud`, `dev_view`, `pane`, `viewer`, `neko`, `menu_l`, `browser`, `other`, `cost`, `system`, `agent`, `security`, `research`, `memory`, `time`, `ci`, `migration`, `visual`, `roadmap`. None of those strings is `promotion_kernel`. This pack does not edit `t27l.t27`.

## Actions

| constant | text |
| --- | --- |
| ACTION_DRAFT | draft |
| ACTION_GATE_CHECK | gate_check |
| ACTION_PUBLISH_APPROVED | publish_approved |
| ACTION_WAITING_RATE_LIMIT | WAITING_RATE_LIMIT |
| ACTION_REFUSED | refused |

`on_rate_limit(false)` returns `WAITING_RATE_LIMIT`. `on_rate_limit(true)` returns `refused`. A paid model is not a fallback.

## Gates

`asset_ready` is true only when claim, artifact, path, visual, CTA, and metric are all present.

`proof_ready` is true only when widget, screenshot, test pass, and human yes are all present (#13485).

`may_publish` is true only when both gates are true.

## Check

`./target/debug/t27c test-report specs/promotion/t27l_promotion.t27` on this run: tests 6, pass 6, FAIL 0, vacuous passes 0 of 6.

Seal: `.trinity/seals/promotion_promotion_t27l.json`, saved with `./target/debug/t27c seal specs/promotion/t27l_promotion.t27 --save`, then `--verify` printed `all hashes MATCH`.

## Asset fields

| Field | Value |
| --- | --- |
| claim | N/A |
| artifact | `specs/promotion/t27l_promotion.t27` |
| reproducible path | the test-report command above |
| visual | N/A |
| CTA | N/A -- not sent |
| metric | 6 tests, 0 failures, 0 vacuous |
27 changes: 27 additions & 0 deletions docs/promotion/widget-inventory.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
{
"part_of": 13473,
"issue": 13476,
"status": "DRAFT_UNSENT",
"published": false,
"gallery_spec_in_this_repo": false,
"gallery_check": "test -f specs/widgets/gallery.t27",
"course_blob_sha": "3b3aa5d21a1dc86876c5b873bf6d6b8cf8d20b21",
"types": [
{"type": "interactive number", "status": "nearest", "nearest": "lesson 4 widget gf16-calc", "screenshot": null},
{"type": "bit layout explorer", "status": "nearest", "nearest": "lesson 2 widget idcode", "screenshot": null},
{"type": "encode/decode", "status": "nearest", "nearest": "lesson 2 widget idcode", "screenshot": null},
{"type": "rounding", "status": "nearest", "nearest": "lesson 4 widget gf16-calc", "screenshot": null},
{"type": "overflow", "status": "absent", "nearest": null, "screenshot": null},
{"type": "NaN", "status": "absent", "nearest": null, "screenshot": null},
{"type": "block scale", "status": "absent", "nearest": "conformance/vectors/block_fp_conformance_v0.json is not a widget", "screenshot": null},
{"type": "ternary adder", "status": "nearest", "nearest": "specs/ternary/ternary_full_adder.t27", "screenshot": null},
{"type": "ternary multiplier", "status": "nearest", "nearest": "lesson 8 widget test-waves", "screenshot": null},
{"type": "FPGA blink", "status": "nearest", "nearest": "lesson 24 widget bit-autopsy", "screenshot": null},
{"type": "neural training loop", "status": "absent", "nearest": null, "screenshot": null},
{"type": "loss curve", "status": "absent", "nearest": "specs/widgets/cost_curves.t27 is LUT cost, not training loss", "screenshot": null},
{"type": "before/after", "status": "partial", "nearest": "specs/course/lesson_01_diff_main.t27", "screenshot": null},
{"type": "live build", "status": "nearest", "nearest": "lesson 23 widget build-receipt", "screenshot": null},
{"type": "agent swarm view", "status": "absent", "nearest": "lesson 27 LESSON_ALSO includes race-the-bee", "screenshot": null},
{"type": "course progress", "status": "partial", "nearest": "specs/course/course_hud_state.t27", "screenshot": null}
]
}
41 changes: 41 additions & 0 deletions docs/promotion/widget-inventory.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Widget inventory

Part of #13473. Issue #13476. Status: DRAFT_UNSENT. Nothing here was posted.

The 16 type names are the list in #13476 FR-003. They are not ids in the live course. The course widget ids are `LESSON_WIDGETS` in the trinity course blob `3b3aa5d21a1dc86876c5b873bf6d6b8cf8d20b21` (see `docs/promotion/course-map.md`).

`test -f specs/widgets/gallery.t27` exited 1. This checkout cannot show that a type is a compiled gallery widget.

`nearest` means a lesson widget or a file in this repo that covers part of the same words. It is not a claim that the V5 type exists under that name.

| type | status | nearest source | visual output checked |
| --- | --- | --- | --- |
| interactive number | nearest | lesson 4 widget `gf16-calc` | screenshot N/A |
| bit layout explorer | nearest | lesson 2 widget `idcode` | screenshot N/A |
| encode/decode | nearest | lesson 2 widget `idcode` | screenshot N/A |
| rounding | nearest | lesson 4 widget `gf16-calc` | screenshot N/A |
| overflow | absent | not in `LESSON_WIDGETS` | N/A |
| NaN | absent | not in `LESSON_WIDGETS` | N/A |
| block scale | absent | not in `LESSON_WIDGETS`; `conformance/vectors/block_fp_conformance_v0.json` is a vector file, not a widget | N/A |
| ternary adder | nearest | lesson 15 spec `specs/ternary/ternary_full_adder.t27` (`test -f` present); widget on that lesson is `lut-explain` | screenshot N/A |
| ternary multiplier | nearest | lesson 8 widget `test-waves` | screenshot N/A |
| FPGA blink | nearest | lesson 24 widget `bit-autopsy`; the lesson task text in the blob names a `blink_j26` sample | screenshot N/A |
| neural training loop | absent | not in `LESSON_WIDGETS` | N/A |
| loss curve | absent | lesson 5 widget `cost-curves` is a LUT-cost chart (`specs/widgets/cost_curves.t27` present), not a training-loss curve | screenshot N/A |
| before/after | partial | `specs/course/lesson_01_diff_main.t27` present; not a `LESSON_WIDGETS` id | screenshot N/A |
| live build | nearest | lesson 23 widget `build-receipt` | screenshot N/A |
| agent swarm view | absent | not a `LESSON_WIDGETS` id; lesson 27 `LESSON_ALSO` includes `race-the-bee` | screenshot N/A |
| course progress | partial | `specs/course/course_hud_state.t27` present; not a `LESSON_WIDGETS` id | screenshot N/A |

## Asset fields

| Field | Value |
| --- | --- |
| claim | N/A for the 16 type names; the approved sentence "Every course widget is a compiled t27 spec." is a content-bank draft, not a result of this inventory |
| artifact | `docs/promotion/widget-inventory.json` |
| reproducible path | `test -f` lines above, plus the course blob fetch in `course-map.md` |
| visual | N/A -- no screenshot |
| CTA | N/A -- not sent |
| metric | 16 types listed; gallery membership not measured |

Machine-readable copy: `docs/promotion/widget-inventory.json`.
Loading
Loading