spec(t27f): topic-to-value engine and /t27f skill, phase 1 slice (Closes #9951)

.claude/skills/t27f/SKILL.md

@@ -0,0 +1,111 @@
+---
+id: t27f
+name: T27F Topic Engine
+description: Turn any topic or client brief into three lenses, a 27-lesson map, one relevant Bee task and a verified artifact, with gaps shown, evidence gates and human approval for anything that leaves the machine. Use when the user says "t27f", "explain this topic in 27 steps", "turn this brief into a plan", or gives a client brief (villa, car, campaign, product) or a research/engineering topic.
+---
+
+# T27F Topic Engine
+
+<!-- only-t27-rule -->
+> **Only t27: everything is written in `.t27`.** (Owner hard rule 2026-10-05; budget #7371; restated in every skill per #7588.)
+> - New logic starts as a `.t27` spec with `test` / `invariant` blocks. It reaches Rust, C, Zig, JS or Python only through `t27c gen-*`, and generated files are never hand-edited (L2).
+> - Hand-written code in any other language is denied by the hooks and by CI: `.rs .py .ts .js .sh .zig .c .go .v .yml .toml`, Dockerfile, Makefile; the full list is in `specs/policy/own_language.t27`.
+> - Existing foreign code is debt that only shrinks. Delete it, or replace it with a spec and its generated output.
+> - Thin hand-written glue is capped at 40 added lines per file and 80 per PR. No label lifts the cap. Never split a PR to slip under it.
+> - 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".
+
+Phase 1 vertical slice of gHashTag/trinity#1677 (parent gHashTag/trinity#1648).
+
+**The rules live in one place: `specs/t27f/topic_engine.t27`.** This skill is the order of
+operations around it. It never restates a constant, a vocabulary or a gate; it reads them. If
+this text and the spec disagree, the spec wins and this text is the bug.
+
+## 0. Load the engine
+
+Read the spec through the t27 MCP server, which is already installed in Claude Code:
+
+- `mcp__t27__t27_spec` with `path: "specs/t27f/topic_engine.t27"` and `source: true`.
+- Until the spec is published to t27.ai, the MCP answers "not found": read the file from a
+  gHashTag/t27 checkout instead. Say which one you used.
+
+From the source, take: `LENS_NAMES`, `LENS_QUESTIONS`, `STAGE_NAMES`, the four `*_WORDS`
+vocabularies, the five `*_BEES` lists, `MAX_ACTIVE_BEES`, and the functions `intake_verdict`,
+`map_verdict`, `initial_status`, `route`, `dispatch_allowed`, `required_evidence`,
+`evidence_accepted`, `verify`, `counts_as_progress`, `needs_human_approval`, `action_allowed`,
+`after_action`. Evaluate them as written; they are small and total.
+
+Everything in `DETERMINISTIC_STEPS` is decided by those functions, never by your judgement.
+You write only what `LLM_WRITES` names.
+
+## 1. Intake
+
+Ask for, or take from the message: the topic or brief, and its sources (links, files, notes).
+Apply `intake_verdict(has_topic, source_count)`:
+
+- `INTAKE_EMPTY`: ask for the topic and stop.
+- `INTAKE_NO_SOURCES`: continue, but every lesson starts as a GAP. Say so up front.
+- `INTAKE_OK`: continue.
+
+## 2. Route
+
+Count whole-word, case-insensitive hits of the brief against each `*_WORDS` list. Show the four
+counts, then apply `route(content, engineering, research, sales)`. Name the domain and the Bee list
+it allows. Do not override the result; if it looks wrong, the vocabulary in the spec is what needs a
+PR.
+
+## 3. Three lenses
+
+Write one short paragraph per lens, answering that lens's question from `LENS_QUESTIONS`, using only
+the sources. A claim with no source is not written; it becomes a gap.
+
+## 4. The 27-lesson map
+
+Print a table of 27 rows, lens-major (`step_lens`, `step_stage`): step, lens, stage, lesson title,
+source, status.
+
+- For each lesson, `grounded` means at least one source supports it.
+- Status from `initial_status(grounded, first_grounded)`. A GAP row says **GAP: needs a source on
+  <what>** and nothing else. Never invent filler to make the map look complete.
+- Count grounded lessons per lens and report `map_verdict(...)`.
+
+## 5. One Bee task
+
+Pick the first OPEN lesson. Check `dispatch_allowed(active_bees)`. Choose one capability from the
+domain's Bee list and write one task for it:
+
+- goal (one sentence), input (the lesson and its sources), output (the artifact),
+- the evidence that will verify it: `required_evidence(stage, domain)`.
+
+In this phase the Bee is you, in this session, or a delegated Agent if the user asks for it. Never
+start more than `MAX_ACTIVE_BEES`, and never one per lesson.
+
+## 6. Draft, then verify
+
+Produce the artifact as a DRAFT and label it as one. Collect the evidence (a source link, a passing
+test, a review, the client's approval). Apply `verify(DRAFT, stage, domain, evidence)`.
+
+- Only VERIFIED or PUBLISHED counts: `counts_as_progress`. Report the progression event as
+  `+POINTS_PER_VERIFIED_LESSON` point, and nothing else. `REWARD_IS_MONEY` is false: never describe
+  points as money, tokens, payouts or value.
+- `opens_next(DRAFT)` is true, so the learner may move on while the draft waits for evidence.
+
+## 7. Approval gate
+
+Before any action, check `needs_human_approval(action)` and `action_allowed(status, action,
+approved)`.
+
+- Publish, send to a client, any payment, anything destructive: ask the user in chat and wait for a
+  clear yes. A yes covers that one action only.
+- Publishing or sending needs a VERIFIED item. A draft is never published.
+
+## 8. Keep the three layers apart
+
+Keep drafts, verified results and published items under separate headings (`layer_of`). If the
+journey is saved, save it as a `.t27` data module, not JSON. Saving follows the user's instruction.
+
+## What this skill does not claim
+
+No runtime dispatches Bees from the spec yet, and nothing publishes on its own. Those are later
+phases of gHashTag/trinity#1677. If a step needs one of them, say that it is missing; do not
+simulate it.

specs/OWNERS.md

@@ -28,6 +28,7 @@
 | `docs/` | **Z-Zeta** (with **T-Queen** for `chapters/queen.t27`) | The system documentation of `t27.ai/#/docs` as `.t27` specs (`docs/system.t27`, `KIND = "docs"`; `docs/chapters/<id>.t27`, `KIND = "docs-chapter"`): chapter ids, sections, sources, the figure and table the site generates; English prose in `docs/system/<id>.md`, Russian via `i18n/docs-ru.t27` |
 | `ui/` | **T-Queen** | The site's viewport contract as a `.t27` spec (`ui/viewport.t27`, `KIND = "viewport"`): tiers by CSS viewport width, panes per tier, the 44 px touch minimum, the six-size QA matrix and the Queen rail capacity read from `Queen.css`; the site (gHashTag/trinity) generates `viewport.generated.ts` / `.css` from a vendored copy and evaluates the spec's own test blocks; `ui/queen_evidence.t27` (`module ui_queen_evidence`): the evidence constants of the Queen's FFN and Ternary Check panel, from which the site generates `queenEvidence.generated.ts`; canonical here since S10, byte-identical to the copy the site carried alone |
 | `catalog/` | **T-Queen** | How the site's spec catalog and the Queen map find the repositories that write `.t27` (`catalog/discovery.t27`, `KIND = "discovery"`): the GitHub owners scanned, the exclusions, what makes a candidate qualify (a declaration in the compiler's AST, not a file extension) and the limits; the site (gHashTag/trinity) vendors a byte-identical copy and `scripts/discover-t27-worlds.mjs` reads it through the compiler wasm before touching GitHub |
+| `t27f/` | **T-Queen** | The T27F topic-to-value engine of gHashTag/trinity#1677 (`t27f/topic_engine.t27`, module `T27fTopicEngine`): the 3 x 9 = 27 lesson shape, intake and gap rules, keyword routing to one domain, the Bee dispatch cap, the evidence and approval gates, and progression that is never money; driven by the Claude Code skill `.claude/skills/t27f/SKILL.md` through the t27 MCP server |
 | `trinity/` | **T-Queen** + **A-Architect** | The project manifest of gHashTag/trinity as `.t27` specs (`trinity/project.t27`, `KIND = "project"`; `trinity/capabilities/<id>.t27`, `KIND = "capability"`): the pinned consumer revision, profiles, dispositions and evidence tags, dialect and build counts, dependency pins and the work packages of gHashTag/trinity#988; each card names its owner, canonical spec, implementation and generated paths, build targets, acceptance command and evidence; `tools/trinity_manifest.py` derives the inventory from a clean pinned checkout and holds the cards to it; `trinity/compiler_matrix.t27` (`KIND = "compiler-matrix"`) names the pinned compiler, the backends, the stages and the features of the executable subset with their fixtures under `bootstrap/tests/fixtures/trinity_matrix/`, and `tools/trinity_compiler_matrix.py` measures them; `trinity/build_graph.t27` (`KIND = "build-graph"`) declares the consumer's toolchain, pins, profiles, generated-file boundaries and receipt policy, and `tools/trinity_build_receipt.py` derives the graph, writes the receipts and judges drift; the consumer vendors a byte-identical copy and generates its manifest from it (S12). Shared contracts stay in their own subtrees (`numeric/`, `vsa/`, `queen/`, `tools/`, `docs/`, `ui/`) and are cited, never copied |
 
 Each subtree with substantial churn should keep a local **`OWNERS.md`** (see below).

specs/skills/t27-t27f.t27

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+; specs/skills/t27-t27f.t27 -- skill t27/t27f
+; Source of truth for the skill card on t27.ai (#/skills?skill=t27/t27f).
+; The skill body lives in gHashTag/t27 at .claude/skills/t27f/SKILL.md; its rules live in
+; specs/t27f/topic_engine.t27 (gHashTag/trinity#1677).
+; The JSON the site serves is generated from this file by the real compiler;
+; nothing below is parsed with a regex.
+; phi^2 + 1/phi^2 = 3 | TRINITY
+
+module skill_t27_t27f;
+
+pub const KIND : str = "skill";
+pub const ID : str = "t27/t27f";
+pub const NAME : str = "T27F Topic Engine";
+pub const REPO : str = "t27";
+pub const SOURCE : str = "SKILL.md";
+pub const SUMMARY_EN : str = "Turn a topic or client brief into three lenses, a 27-lesson map, one Bee task and a verified artifact";
+; The frontmatter id is the slash command.
+pub const COMMAND : str = "/t27f";
+; Specs this skill stands on.
+pub const SPECS : [1]str = ["specs/t27f/topic_engine.t27"];
+pub const TAGS : [3]str = ["t27f", "learning", "bees"];
+pub const ENABLED : bool = true;
+; Default budget; SKILL.md declares no timeout of its own.
+pub const TIMEOUT_MIN : u16 = 30;
+
+test basic_constants {
+    assert KIND == "skill";
+    assert ID == "t27/t27f";
+    assert NAME == "T27F Topic Engine";
+    assert REPO == "t27";
+    assert COMMAND == "/t27f";
+    assert ENABLED == true;
+    assert TIMEOUT_MIN == 30;
+    assert TAGS[0] == "t27f";
+    assert TAGS[1] == "learning";
+    assert TAGS[2] == "bees";
+    assert SPECS.len == 1;
+    assert SPECS[0] == "specs/t27f/topic_engine.t27";
+}