shapeup-sdlc 1.6.2

package/skills/translator/README.md

@@ -0,0 +1,66 @@
+# translator
+
+The language gate upstream of the harness. It turns the PO's non-English intake (pitch /
+PRD / requirement / transcript) into faithful **English** copies the harness can consume,
+then proves the result is English and structurally identical to the source. It is **narrow
+by design** — it normalizes language, nothing else.
+
+```
+PO intake (any language)  →  TRANSLATOR  →  <name>.en.md (+ glossary.md + report)  →  ba-pitch-analyzer → …
+```
+
+**Why it exists:** the harness (ba-pitch-analyzer → task-executor → spec-evaluator) is
+English-only end to end and HARD-FAILs on anything else. Previously `tech-lead` was expected
+to cover this; that conflated orchestration with language normalization. This skill owns the
+language concern so the orchestrator stays thin.
+
+**What it does NOT do:** plan, build, judge, or translate harness output back to the PO's
+language. Input-normalization only.
+
+## Resource map
+```
+translator/
+├── SKILL.md                       # entry — GATE T0–T2, the detect→glossary→translate→verify flow, flags, hard rules
+├── README.md                      # this file
+└── references/
+    └── preservation-rules.md      # ★ translate-vs-preserve table, 1:1 structure rule, glossary protocol, verification scan
+```
+
+| Resource | Loaded at | Purpose |
+|----------|-----------|---------|
+| `SKILL.md` | always | T-gates, phase sequence, invocation, hard rules |
+| `references/preservation-rules.md` | before translating | what stays verbatim, glossary format, the 3 verification checks |
+
+## Install
+```bash
+cp -r translator <repo>/.claude/skills/      # or ~/.claude/skills/
+```
+Pairs with the harness skills (`ba-pitch-analyzer`, `task-executor`, `spec-evaluator`,
+`tech-lead`). `tech-lead` auto-invokes it at GATE L0 when intake is non-English.
+
+## Invoke
+```bash
+/translator docs/pitch.md                       # → docs/pitch.en.md (+ glossary.md, report)
+/translator docs/intake/                         # folder; already-English files skipped
+/translator --glossary docs/glossary.md docs/pitch.md   # reuse vocabulary across docs/runs
+/translator --check docs/pitch.md                # detect-only (what tech-lead L0 calls)
+/translator --auto docs/pitch.md                 # headless; still stops on a dirty residual scan
+```
+
+## Gate map
+| Gate | When | Decision |
+|------|------|----------|
+| T0 | intake | detect source language per file; scope what to translate; `--check` stops here |
+| T1 | after glossary | PO confirms term mappings; ambiguous terms resolved (never guessed) |
+| T2 | after verify | sign off only on a clean residual scan + matching structure |
+
+## Output
+- `<name>.en.md` — the English copy (original never overwritten)
+- `glossary.md` — source→English term map (persisted, reusable)
+- `translation-report.md` — detect table, glossary diff, verification result
+
+## Version
+0.1 — initial language gate. Detect → glossary → translate → verify → sign-off. Strict
+English-only for the whole harness; faithful 1:1 with structure/frontmatter/wikilink/code/
+number preservation; reusable glossary; idempotent already-English no-op; `--check` mode;
+residual-non-English scan blocks sign-off even under `--auto`.

package/skills/translator/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: translator
+description: "Use this skill whenever intake for the harness (pitch, PRD, requirement, transcript, or any spec input) is in a non-English language and must be normalized to English BEFORE planning/building. The single language gate for the planner→generator→judge harness. Triggers on: \"translate this pitch\", \"normalize to English\", \"this requirement is in Vietnamese\", \"prepare intake for the harness\", \"make the spec English\", \"check if this is English\", and Vietnamese \"dịch sang tiếng Anh\", \"chuẩn hoá tiếng Anh\", \"dịch pitch\", \"chuyển yêu cầu sang tiếng Anh\". Produces faithful English copies (original never overwritten) plus a glossary and verification report. tech-lead auto-invokes it at GATE L0 when intake is non-English; also runs standalone."
+---
+
+# Translator (harness language gate)
+
+The one job upstream of the whole harness: **make the input English, faithfully, once.**
+The harness is English-only end to end — the planner, generator, and judge all assume
+English and HARD-FAIL on anything else. This skill is the single component that guarantees
+that assumption holds. It is **not** a translator that rewrites; it normalizes language
+while preserving every requirement, number, boundary, and structural element 1:1.
+
+```
+PO writes intake (any language)  →  TRANSLATOR  →  <name>.en.md (English)  →  ba-pitch-analyzer → …
+                                    (this skill)     + glossary.md + report
+```
+
+**Scope is deliberately narrow (simplicity first):**
+- ✅ Translate **input** docs (pitch / PRD / requirement / transcript) into English copies.
+- ✅ Emit a persisted **glossary** so domain terms map consistently across docs and runs.
+- ✅ **Verify** the output is English and structurally identical to the source.
+- 🚫 Does NOT plan, build, or judge — that is the harness's job.
+- 🚫 Does NOT translate harness **output** back to the PO's language (input-normalization only).
+- 🚫 Does NOT summarize, add, drop, or "improve" content — faithful 1:1 only.
+
+> **What is preserved verbatim vs translated, glossary protocol, verification scan**
+> → `references/preservation-rules.md` — read it before translating any file.
+
+---
+
+## Workflow Overview
+
+```
+INPUT: doc(s) in any language
+          │
+⏸ GATE T0 │  Detect & Scope ──────► per-file source-language detection; list files to
+          │                        translate; already-English files → skipped (idempotent)
+          │
+▶ Phase 1 │  Glossary ────────────► extract domain terms + proper nouns + do-not-translate
+          │                        tokens; map source→English; reuse existing glossary.md
+⏸ GATE T1 │  Glossary Review ──────► PO confirms term mappings; ambiguous terms resolved here
+          │                        (never guessed). lite/auto: auto-proceed on unambiguous.
+          │
+▶ Phase 2 │  Translate ───────────► WRITE <name>.en.md (original untouched): prose → English,
+          │                        glossary applied; frontmatter keys, wikilinks, code, URLs,
+          │                        numbers preserved
+          │
+▶ Phase 3 │  Verify ──────────────► residual-non-English scan + structural diff (heading /
+          │                        link / code-block / list-item counts must match source)
+⏸ GATE T2 │  Output Sign-off ──────► confirm clean scan + matching structure, then emit
+          │                        glossary.md + translation-report.md (the .en.md is already
+          │                        written in Phase 2)
+✅ Done   └─► English intake ready for the harness
+```
+
+---
+
+## GATE T0 — Detect & Scope
+
+**Purpose:** Decide what needs translating before spending tokens, and stay idempotent.
+
+```
+T0.1  For each input file/path, detect source language (sample headings + body prose,
+      ignore code blocks / identifiers / URLs).
+T0.2  Classify:
+        already-English  → SKIP (no .en.md written; report it as pass-through)
+        non-English      → queue for translation
+        mixed            → queue; flag the English spans to keep verbatim
+T0.3  In --check mode: print the classification table and STOP. Write nothing.
+      (This is the mode tech-lead calls at GATE L0 to decide whether to run a full pass.)
+```
+
+**GATE T0 Output:**
+```
+⏸ GATE T0 — Detect & Scope
+Files        : [N]   (translate: [k]  ·  already-English: [N-k])
+Source lang  : [vi | mixed | …]
+Glossary     : [reuse docs/glossary.md | build new]
+Mode         : [full | --check (detect only)]
+```
+Under `--check`: stop here. Otherwise proceed to Phase 1 (auto) or wait for confirm (interactive).
+
+---
+
+## Phase 1 — Glossary
+
+**Goal:** One consistent English term per source term, across every doc and every run.
+Inconsistent vocabulary is the failure that poisons downstream DDD extraction (the planner
+treats two spellings as two concepts). Read `references/preservation-rules.md#Glossary` first.
+
+```
+1. Reuse: if a glossary.md exists (or --glossary <path> given), load it as the base map.
+2. Extract from the source: domain nouns, actor names, status/enum values, screen names,
+   feature jargon. Propose source→English for each new term.
+3. Mark do-not-translate tokens: proper nouns, brand/product names, code identifiers, API
+   names, env vars, file paths — these pass through verbatim (see preservation-rules).
+4. Flag ambiguous terms (one source word → multiple valid English terms) for GATE T1.
+```
+
+**Output:** draft `glossary.md` (source term · English · note/do-not-translate flag).
+
+---
+
+## GATE T1 — Glossary Review
+
+**Purpose:** Lock vocabulary with the PO before it propagates into every translated doc.
+
+```
+Print the new/changed term rows + any ambiguous terms.
+Ask (max 2): confirm the English term for each ambiguous entry; any term to force
+verbatim (do-not-translate)?
+```
+Never guess an ambiguous domain term — a wrong canonical term cascades into the spec.
+`--auto` / `--lite`: auto-proceed when no term is ambiguous; if any is, still pause (a
+wrong term is more expensive than a pause).
+
+---
+
+## Phase 2 — Translate
+
+**Goal:** Faithful English copy. Read `references/preservation-rules.md` first.
+
+```
+For each queued file, write <name>.en.md (sibling of the source; original untouched):
+  - Translate prose values only. Apply the glossary to every domain term.
+  - PRESERVE verbatim: YAML frontmatter KEYS, [[wikilink]] targets, `code`/```fenced```,
+    URLs, file paths, numbers, units, appetite/boundary values, do-not-translate tokens.
+  - Keep document structure 1:1: same headings, same table rows, same list items, same
+    order. No merging, no reordering, no summarizing.
+  - Mixed-language source: leave already-English spans as they are.
+```
+Faithfulness rule: the `.en.md` must carry exactly the requirements of the source — nothing
+added, nothing dropped, no editorializing. Translation ≠ rewriting.
+
+---
+
+## Phase 3 — Verify
+
+**Goal:** Prove the output is English and structurally identical before sign-off.
+
+```
+3.1  Residual-non-English scan: scan every .en.md for source-language characters/words
+     outside code blocks / do-not-translate tokens. Any hit → list file:line, do NOT pass.
+3.2  Structural diff vs source: heading count, table-row count, list-item count, wikilink
+     count, code-block count must match. Mismatch → a requirement was dropped/added → fail.
+3.3  Glossary coverage: every extracted term resolved (no "⏳ TBD" left in glossary.md).
+```
+A failing scan blocks GATE T2 — emit the residual list and fix before signing off.
+
+---
+
+## GATE T2 — Output Sign-off
+
+```
+⏸ GATE T2 — Output Sign-off
+Translated   : [k] files → <name>.en.md
+Glossary     : glossary.md ([t] terms, [a] resolved-ambiguous)
+Residual scan: ✅ clean | 🔴 [n] non-English spans → [file:line …]
+Structure    : ✅ matches source | 🔴 [diff]
+```
+On clean → `✅ Intake English-ready: [files]. Point the harness at the .en.md copies.`
+Under `--auto`/`--unattended`: auto-sign-off only if the residual scan is clean; a dirty
+scan always stops (never ship half-translated intake to the harness).
+
+---
+
+## Output files
+
+| File | Purpose | Notes |
+|------|---------|-------|
+| `<name>.en.md` | The English copy the harness consumes | One per translated source; **original is never overwritten** |
+| `glossary.md` | source→English term map | Persisted + reused; the shared vocabulary for this feature |
+| `translation-report.md` | detect table, glossary diff, verification result | Audit trail; what was skipped/flagged |
+
+**Destinations (two-root workspace).** `<name>.en.md` is always written as a sibling
+of its source — when the source already lives under the SHARED root
+`shapeup/<slug>/shaping/`, the copy lands there too. `glossary.md` is durable
+shared vocabulary → write it to `shapeup/<slug>/shaping/glossary.md`.
+`translation-report.md` is run-trace (audit) → write it to the LOCAL root
+`.shapeup/<slug>/translation-report.md`. When run standalone on loose intake files
+(no slug yet), all three default to siblings of the source.
+
+---
+
+## Envelope contract — the domain layer
+
+Orchestrated, this skill is dispatched like every worker: a **WorkOrder** in (`--order <path>`,
+operation `translate`), a **WorkResult** out. The standalone arguments below map 1:1 onto the
+payload fields registered for this worker in the central domain registry
+(`skills/tech-lead/schemas/domain.schema.json`, `x-payload-by-worker`):
+
+| Payload field | Standalone form | Meaning |
+|---|---|---|
+| `payload.intake[]` | positional path(s) | Source docs to normalize to English — originals never overwritten |
+| `payload.glossary` | `--glossary` | An existing `glossary.md` to reuse as the base term map |
+
+The WorkResult may carry only `files_touched`, `artifacts`, `assumptions`, `deviations`
+(`x-result-by-worker`): the `.en.md` copies, glossary, and verification report return as
+`artifacts`; ambiguous-term resolutions made without a PO land in `assumptions`.
+
+---
+
+## Invocation
+
+```bash
+# Translate one intake file → docs/pitch.en.md (+ glossary.md, translation-report.md)
+/translator docs/pitch.md
+
+# Translate a folder of intake docs (already-English files are skipped)
+/translator docs/intake/
+
+# Reuse / extend an existing glossary for consistent vocabulary across runs
+/translator --glossary docs/glossary.md docs/pitch.md
+
+# Detect-only: is this English? print the table and stop (what tech-lead L0 calls)
+/translator --check docs/pitch.md
+
+# Headless: skip gates; still HARD-STOPS on a dirty residual scan
+/translator --auto docs/pitch.md
+```
+
+### Flags
+| Flag | Effect |
+|------|--------|
+| `--check` | Detect source language and report; write nothing, stop at GATE T0 |
+| `--glossary <path>` | Load an existing glossary as the base map (consistency across docs/runs) |
+| `--auto` | Skip T0/T1 confirmation gates; still pauses on ambiguous terms + dirty scan |
+| `--unattended` | Auto-sign-off all gates; stop only on a dirty residual scan or hard error |
+| `--out <dir>` | Write `.en.md` copies into a target dir instead of beside the source |
+
+---
+
+## Hard Rules (never override without explicit user instruction)
+
+| Rule | Rationale |
+|------|-----------|
+| Never overwrite the source; always write a `.en.md` copy | The PO still needs to read their original |
+| Never summarize, add, or drop content — faithful 1:1 | The harness builds exactly what the spec says; drift here is silent scope change |
+| Preserve frontmatter keys, wikilink targets, code, URLs, numbers verbatim | Structure is load-bearing for downstream parsing; translating it breaks the spec tree |
+| One source term → one English term, via the glossary | Two spellings read as two concepts to the planner's DDD pass |
+| Ambiguous term → ask at GATE T1, never guess | A wrong canonical term cascades into every doc and every build round |
+| Already-English input → no-op (idempotent) | Re-runs and `--check` must be safe and cheap |
+| Dirty residual scan blocks sign-off, even under `--auto` | Half-translated intake makes the harness HARD-FAIL mid-run — worse than stopping here |
+| Input-normalization only — never translate harness output back | This is the upstream gate; output language is a separate, out-of-scope concern |
+
+---
+
+## Relationship to the harness
+
+```
+TRANSLATOR (this skill)  →  ba-pitch-analyzer (PLAN)  →  task-executor (BUILD)  →  spec-evaluator (JUDGE)
+   language gate                 English-only specs        English-only code         English-only verdict
+```
+- The harness is **English-only end to end**; the downstream skills HARD-FAIL on non-English.
+- `tech-lead` does **not** translate — at GATE L0 it runs `/translator --check`, and if intake
+  is non-English it runs a full `/translator` pass first, then orchestrates against the `.en.md`
+  copies. Orchestration and language normalization are separate single-purpose concerns.

package/skills/translator/references/preservation-rules.md

@@ -0,0 +1,102 @@
+# Preservation Rules
+
+What the translator touches, what it must never touch, and how it proves the result.
+Read this before translating any file. The governing principle: **translate meaning,
+preserve everything that machines parse.** A `.en.md` that reads well but breaks the spec
+tree's wikilinks or drops a table row is a failed translation.
+
+---
+
+## 1. Translate vs preserve verbatim
+
+| Element | Action | Why |
+|---------|--------|-----|
+| Prose, headings (text), table cell text, list items | **Translate** | The human-readable content the harness reasons over |
+| YAML frontmatter **keys** (`appetite:`, `lens:`, `feature:`) | **Preserve** | Parsed by downstream skills; translating a key breaks the schema |
+| YAML frontmatter **values** that are prose | Translate | e.g. a description value |
+| YAML frontmatter **values** that are enums/slugs/IDs (`lens: standard`, `feature: checkout-vnpay`) | **Preserve** | Machine-matched; must stay byte-identical |
+| `[[wikilink]]` targets | **Preserve** | They resolve to filenames; translating breaks the graph. (A wikilink *alias* shown to humans may be translated: `[[UC-Login\|đăng nhập]]` → `[[UC-Login\|log in]]`) |
+| `` `inline code` `` and ```` ```fenced``` ```` blocks | **Preserve** | Code, identifiers, commands — not natural language |
+| Code identifiers, type names, API names, env vars, file paths | **Preserve** | `UserRepository`, `VNPAY_SECRET`, `src/modules/canvas/` stay as-is |
+| URLs | **Preserve** | Links, not prose |
+| Numbers, units, currency, dates, appetite/boundary values | **Preserve** | `~3 tuần` → translate the unit word only if prose (`~3 weeks`); never alter the number |
+| Proper nouns / brand / product names | **Preserve** (unless an established English name exists) | VNPAY, Supabase, ReactFlow |
+
+**Mixed-language source:** leave already-English spans exactly as written. Do not
+"re-translate" English into different English.
+
+---
+
+## 2. Structure is 1:1
+
+The `.en.md` must mirror the source's structure exactly:
+
+- Same number of headings, at the same levels, in the same order.
+- Same number of table rows and columns.
+- Same number of list items and nesting.
+- Same number of code blocks and wikilinks.
+- No merging paragraphs, no reordering sections, no "tightening" prose.
+
+Rationale: the planner extracts boundaries, rabbit holes, and breadboard elements
+positionally and by count. Dropping or fusing items is silent scope change — the single
+most dangerous failure mode of a translation step.
+
+---
+
+## 3. Glossary protocol
+
+A `glossary.md` is the contract that keeps one source term mapped to one English term across
+every doc and every run. Without it, "phiếu giảm giá" becomes "voucher" in one file and
+"discount coupon" in another, and the planner's DDD pass sees two aggregates.
+
+**Format** (`glossary.md`):
+
+```markdown
+# Glossary — <feature-slug>
+
+| Source term | English | Note |
+|-------------|---------|------|
+| phiếu giảm giá | voucher | domain noun — aggregate candidate |
+| người dùng | user | actor |
+| VNPAY | VNPAY | do-not-translate (brand) |
+| đơn hàng | order | domain noun |
+```
+
+**Rules:**
+- Reuse an existing glossary (`--glossary <path>`) as the base — extend, don't replace.
+- One source term → exactly one English term. If the source uses a term two ways, that is
+  an **ambiguity** → resolve at GATE T1, then record both senses as distinct rows with notes.
+- `do-not-translate` rows pin proper nouns / identifiers that must pass through verbatim.
+- No `⏳ TBD` may remain at sign-off — every extracted term is resolved (Phase 3.3).
+
+---
+
+## 4. Verification scan (Phase 3)
+
+Three checks, all must pass before GATE T2 sign-off:
+
+1. **Residual-non-English scan.** Scan each `.en.md` for source-language characters or words
+   *outside* code blocks and do-not-translate tokens. For Vietnamese: diacritic ranges
+   (à á ả ã ạ â ầ … đ …) and common function words (và, của, người, là, được, …). Any hit →
+   report `file:line` + the span. Does NOT pass with residuals.
+2. **Structural diff vs source.** Compare counts: headings, table rows, list items,
+   wikilinks, code blocks. Any mismatch → a requirement was added or dropped → fail.
+3. **Glossary coverage.** Every term extracted in Phase 1 appears resolved in `glossary.md`.
+
+A failing scan blocks sign-off even under `--auto`/`--unattended` — half-translated intake
+makes the harness HARD-FAIL mid-run, which is worse and more expensive than stopping here.
+
+---
+
+## 5. Faithfulness (the non-negotiable)
+
+Translation is **not** an editing pass. The `.en.md` carries exactly the requirements of the
+source:
+
+- ❌ Do not add clarifications, assumptions, or "missing" requirements (that is the planner's
+  GATE 0 job, downstream).
+- ❌ Do not drop content that seems redundant or unclear — translate it faithfully and let
+  the planner flag it.
+- ❌ Do not summarize or shorten.
+- ✅ If a source sentence is genuinely ambiguous to translate, keep the most literal English
+  rendering and note it in `translation-report.md` for the PO — never silently pick a meaning.