okstra 0.98.1 → 0.98.2

package/docs/for-ai/skills/okstra-schedule.md

@@ -0,0 +1,321 @@
+# okstra-schedule AI Manual
+
+## 원천
+
+- 스킬 원문: [`skills/okstra-schedule/SKILL.md`](../../../skills/okstra-schedule/SKILL.md)
+- schedule 템플릿: [`templates/reports/schedule.template.md`](../../../templates/reports/schedule.template.md)
+- schedule validator: [`validators/validate-schedule.py`](../../../validators/validate-schedule.py)
+- workStatus inference 참조: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
+
+## 목적
+
+`okstra-schedule`은 task-group 안의 non-done task들을 모아 클라이언트용 작업 일정 Markdown을 만든다. 실행 task를 시작하는 스킬이 아니며, 단일 task 분석도 아니다.
+
+출력 위치:
+
+```text
+<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
+```
+
+## 사용 조건
+
+사용한다:
+
+- 사용자가 task-group 전체의 "일정", "schedule", "작업 계획표"를 요청한다.
+- `.okstra/discovery/task-catalog.json`에 해당 task-group이 있고, `done`이 아닌 task가 하나 이상 있다.
+
+사용하지 않는다:
+
+- 단일 task 상태/분석: `okstra-inspect status`
+- 실제 phase 실행: `okstra-run`
+- 이미 완료된 task-group: 파일을 만들지 않고 모든 task가 done이라고 말한다.
+
+## Preflight
+
+각각 별도 Bash 호출:
+
+```bash
+okstra ensure-installed --runtime claude-code
+okstra check-project --json
+```
+
+runtime이나 project setup이 없으면 `/okstra-setup` 안내 후 멈춘다.
+
+## model gate
+
+스킬 frontmatter는 `model: opus`다. 활성 모델이 Opus-class 또는 Fable-class가 아니면 사용자에게 전환을 권한다. 사용자가 lower model로 진행하겠다고 명시하면 진행하되, 생성 schedule 상단에 reduced-quality warning을 넣는다.
+
+## task-group 해석
+
+1. `.okstra/discovery/task-catalog.json`을 읽는다.
+2. 사용자 입력 task-group을 lowercase하고 `[a-z0-9]` 외 문자를 제거한다.
+3. catalog entry의 `taskGroupPathSegment`에도 같은 변환을 적용해 비교한다.
+4. raw `taskGroup` fallback은 쓰지 않는다.
+5. 매칭된 각 task의 `task-manifest.json`을 직접 읽는다. catalog는 stale일 수 있고 manifest가 authoritative다.
+
+## workStatus filter
+
+각 manifest에서 workStatus를 확인한다. 없거나 비어 있으면 `okstra-inspect`의 `status.4` inference table을 적용한다.
+
+제외:
+
+- explicit `done`
+- inferred `done`
+
+포함:
+
+- `todo`
+- `in-progress`
+- `blocked`
+- `phase-done`
+- 그 밖의 non-done inferred/display 상태
+
+필터 후 0개면 schedule file을 만들지 않는다.
+
+## per-task data extraction
+
+manifest에서 읽는다:
+
+- `taskId`, `taskGroup`, `taskKey`
+- `workCategory`
+- `workflow.currentPhase`
+- `workflow.currentPhaseState`
+- `taskType`
+- `workStatus`
+- `latestReportPath`
+
+report에서 파싱한다:
+
+- Title / Problem statement
+- Solution / Architecture
+- Work Breakdown
+- Verification Commands
+- Rollback strategy
+- Effort, Risk, Priority, Scope, Repos
+
+report가 없거나 manifest pointer가 stale이면 fallback:
+
+1. `taskRootPath`를 기준으로 `runs/<taskType>/reports/final-report-*.md`에서 mtime이 최신인 파일을 찾는다.
+2. 없으면 `runs/*/reports/final-report-*.md`도 본다.
+3. 찾으면 parse하고 schedule task block에 fallback note를 넣는다.
+4. 끝까지 없으면 `[NEEDS-OKSTRA-RUN]`으로 표시하고 manifest metadata만 사용한다.
+
+특정 section parse 실패는 `[PARSE-ERROR: <section>]`으로 표시하고 계속한다.
+
+## client-facing audience rule
+
+schedule은 클라이언트용 작업 계획이다. 내부 report의 approval, blocking decision, 사용자 확인 필요 항목을 schedule에 노출하지 않는다.
+
+출력에서 제거한다:
+
+- permission/authority 확인 step
+- approval waiting buffer
+- stakeholder coordination
+- 법무/조직 sign-off
+- `Consolidated User Decision Checklist`
+- `#### 사용자 확인 필요 항목`
+- `Done`, `Ready?`, `Blocking Decisions` column
+- checkbox list/cell
+
+effort와 Gantt는 engineering duration만 반영한다.
+
+## phase classification
+
+기본 mapping:
+
+| workCategory | phase |
+|---|---|
+| `bugfix` | High/Med-High risk이면 Phase 1, 아니면 Phase 2 |
+| `feature` | Phase 2 |
+| `improvement` | Phase 2 |
+| `refactor` | Phase 3 |
+| `ops` | Phase 3 |
+| `docs` / `doc` | Phase 2 |
+| `unknown` 또는 미정의 | Phase 2, rationale note 추가 |
+
+priority override:
+
+- `P0`: Phase 1
+- `P1`, `P2`: Phase 2
+- `P3`: Phase 3
+
+ambiguous하면 가장 가까운 phase에 두고 rationale을 phase section 상단에 쓴다. 이 rationale은 현재 validator gap으로 문서에서 책임진다.
+
+## section contract
+
+템플릿의 heading 순서와 spelling을 따른다. `validate-schedule.py`가 section order, title suffix, metadata, field labels, enum, Gantt axis 등을 검사한다.
+
+top-level 계약 sections:
+
+1. `## At a Glance`
+2. `## Executive Summary`
+3. `## Task Dependency Graph`
+4. `## Phase 1: Critical Fixes`
+5. `## Phase 2: Enhancements`
+6. `## Phase 3: Architecture`
+7. `## Execution Priority Matrix`
+8. `## Cross-Task Dependencies & Shared Concerns`
+9. `## Risk Mitigation Strategy`
+10. `## Recommended Immediate Actions`
+
+optional sections:
+
+- `## Gantt Chart`: `Task Dependency Graph`와 `Phase 1` 사이.
+- `## Glossary`: 마지막 section. opaque code가 본문에 남을 때만 사용.
+
+phase에 task가 없어도 heading을 유지하고 `_없음_`을 쓴다.
+
+## top header
+
+형태:
+
+```markdown
+# <Title> — Work Schedule
+
+> Generated: <YYYY-MM-DD HH:MM> | Project: <project-id> | Task Group: <task-group>
+> Source: okstra <mode> (<N> tasks included, <M> done excluded)
+```
+
+title suffix `— Work Schedule`은 validator가 검사한다.
+
+## At a Glance
+
+다음 totals line이 정확히 있어야 한다.
+
+```markdown
+**총 <N>개 task / 예상 소요: <X.X> ~ <Y.Y> days (Effort 합산)**
+```
+
+Effort-to-day mapping은 template의 `### Effort Sizing 기준` table이 SSOT다. lower/upper 합산으로 total day range를 만든다.
+
+enum 값:
+
+| Field | 값 |
+|---|---|
+| Effort | `S`, `M`, `L`, `XL`, `XXL` |
+| Priority | `P0`, `P1`, `P2`, `P3` |
+| Risk | `Very Low`, `Low`, `Medium`, `Med-High`, `High` |
+| Phase | `1`, `2`, `3` |
+
+`Med-High`가 canonical이다.
+
+## per-task block
+
+모든 task block은 `| Item | Detail |` table을 가진다. field row 순서:
+
+1. `**Category**`
+2. `**Priority**`
+3. `**Effort**`
+4. `**Status**`
+5. `**Risk**`
+6. `**Scope**`
+7. `**Repo**`
+
+그 뒤 subsection 순서:
+
+1. `**Problem**:`
+2. `**Solution**:`
+3. `**Work Breakdown**:`
+4. `**Verification Commands**:`
+5. `**Rollback**:`
+
+`[NEEDS-OKSTRA-RUN]` 또는 `[PARSE-ERROR: <section>]` task는 가능한 field만 채우되 marker를 task heading 바로 아래 둔다.
+
+## Task Dependency Graph
+
+dependency가 없으면 literal:
+
+```markdown
+_의존 정보 없음_
+```
+
+dependency가 있으면 plain fenced block을 사용한다. language tag를 붙이지 않는다.
+
+````
+```
+DEV-1 -> DEV-2, DEV-3
+DEV-2 -> DEV-4
+```
+````
+
+arrow는 ASCII `->`만 사용한다.
+
+## Gantt Chart
+
+기본은 렌더한다. day signal이 하나라도 있으면 rough estimate라도 chart를 만든다.
+
+렌더 조건 예:
+
+- 2개 이상 task에 effort sizing이 있다.
+- 1개 task라도 effort range가 있다.
+- source report에 Part/Phase/Step decomposition이 있다.
+- total effort가 3 days 이상이다.
+
+skip은 모든 task가 XXL이고 decomposition이 없거나, 모든 task에 effort와 decomposition이 없을 때만 한다. skip하면 `Gantt Chart` 위치에 다음 blockquote를 둔다.
+
+```markdown
+> _Gantt Chart 생략: <actual data를 근거로 한 이유>._
+```
+
+Gantt는 plain fenced ASCII다. Mermaid, PlantUML, Graphviz, date axis를 쓰지 않는다.
+
+````
+```
+Day:            1    5    10   15   20
+                |    |    |    |    |
+Phase 1
+  DEV-1 (M)          ██████          ! crit
+Phase 2
+  DEV-2 (L)                ██████░░  est
+```
+````
+
+axis는 relative day count만 사용한다. calendar date, weekday, "오늘 + N"을 넣지 않는다.
+
+## opaque code 처리
+
+내부 report code(`FC-5`, `UC-3`, `M2` 등)는 그대로 노출하지 않는다.
+
+선택 A: 짧은 설명으로 inline replacement.
+
+선택 B: 반복되는 code가 많으면 마지막 `## Glossary`에 모든 code를 해석한다.
+
+decision-item letter code(`A1`, `B2`, `C3`, `D4`)는 schedule에 넣지 않는다.
+
+## validation
+
+작성 후 완료 메시지 전에 다시 읽고 validator를 실행한다.
+
+```bash
+python3 ~/.okstra/lib/validators/validate-schedule.py <output-path>
+```
+
+설치본 validator가 없으면 repo validator를 쓴다.
+
+```bash
+python3 validators/validate-schedule.py <output-path>
+```
+
+실패하면 파일을 고치고 재검증한다. validator가 없을 때만 manual checklist로 대체한다.
+
+## 완료 메시지
+
+```text
+Schedule 생성 완료: <relative-path>
+- 포함 task: N개
+- 제외(done) task: M개
+- 예상 소요: X.X ~ Y.Y days (Effort 합산)
+- 모드: lightweight
+```
+
+## 금지 패턴
+
+- heading을 한국어/프랑스어 등으로 번역하기.
+- `## Cumulative Timeline` 추가.
+- `## Effort-to-Day 매핑` 같은 extra top-level section 추가.
+- Gantt를 mermaid로 렌더하기.
+- Gantt axis에 calendar date를 넣기.
+- checkbox, Done, Ready, Blocking Decisions column 만들기.
+- internal approval/blocker/user-decision 항목을 클라이언트 schedule에 노출하기.
+- report가 없다고 task를 제외하기. `[NEEDS-OKSTRA-RUN]`으로 포함한다.
+- timestamp collision 시 기존 파일을 덮어쓰기. `-2`, `-3` suffix를 붙인다.

package/docs/for-ai/skills/okstra-setup.md

@@ -0,0 +1,140 @@
+# okstra-setup AI Manual
+
+## 원천
+
+- 스킬 원문: [`skills/okstra-setup/SKILL.md`](../../../skills/okstra-setup/SKILL.md)
+- CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
+- project 등록 구현: `src/commands/lifecycle/setup.mjs`
+- install/ensure-installed 구현: `src/commands/lifecycle/install.mjs`
+
+## 목적
+
+`okstra-setup`은 두 가지를 처리한다.
+
+1. 머신 단위 runtime 설치: `~/.okstra/`, `~/.claude/skills/`, `~/.claude/agents/`
+2. 프로젝트 단위 등록: `<PROJECT_ROOT>/.okstra/project.json`
+
+일상적인 task 실행 스킬이 아니다. task가 이미 준비된 상태면 `okstra-run` 또는 `okstra-inspect`로 라우팅한다.
+
+## 사용 조건
+
+사용한다:
+
+- 사용자가 "okstra setup", "setup okstra", "initialize okstra", "okstra init", "처음 설정"을 요청한다.
+- `~/.okstra/version`이 없거나 오래된 것으로 보인다.
+- 현재 프로젝트에 `.okstra/project.json`이 없다.
+
+사용하지 않는다:
+
+- task run을 시작하려는 경우. 이때는 `okstra-run`.
+- status/history/report를 보려는 경우. 이때는 `okstra-inspect`.
+- 이미 `.okstra/project.json`이 있고 day-to-day 사용만 필요한 경우.
+
+## 실행 전 확인
+
+사용자에게 Node 18+, Python 3.10+가 필요하다고 알린다. 현재 working directory가 okstra 메타데이터를 둘 프로젝트 안인지 불명확하면, 프로젝트 루트를 먼저 확인한다.
+
+설치 명령:
+
+```bash
+npx -y okstra@latest install --runtime claude-code
+```
+
+이 명령은 idempotent로 취급한다. 이미 설치되어 있어도 다시 실행해 runtime, skill, agent payload를 현재 package 버전과 맞춘다. 실패하면 stderr를 그대로 사용자에게 보여준다. legacy `okstra-install.sh`로 우회하지 않는다.
+
+## 명령 호출 규칙
+
+`okstra install` 이후에는 후속 명령이 모두 `okstra` literal token으로 시작해야 한다.
+
+허용되는 형태:
+
+```bash
+okstra check-project --json
+okstra setup --yes --project-root /abs/project --project-id my-project
+okstra doctor --runtime claude-code
+```
+
+피해야 하는 형태:
+
+- `export PYTHONPATH=...`
+- `eval "$(okstra paths --shell)"`
+- `$PROJECT_ROOT` 같은 shell 변수
+- `$(...)` command substitution
+- `if`, `&&`, `||`로 감싼 okstra 호출
+
+`okstra <subcmd>`가 자체적으로 Python path를 부트스트랩하므로 `okstra paths --shell`은 이 스킬에서 쓰지 않는다. 경로가 필요하면 `okstra paths --json`을 별도 호출로 실행하고 JSON 값을 읽는다.
+
+## 프로젝트 루트 해석
+
+먼저 실행:
+
+```bash
+okstra check-project --json
+```
+
+결과 처리:
+
+- `ok: true`: 이미 등록된 프로젝트다. `projectRoot`, `projectJsonPath`, `projectId`를 사용자에게 보여주고 유지 여부를 확인한다.
+- `ok: false`, `stage: "resolve"`: 사용자에게 절대 project root를 받아 `okstra check-project --cwd /abs/path --json`을 다시 실행한다.
+- `ok: false`, `stage: "project_json_missing"`: 정상 생성 경로로 진행한다.
+- 그 외 실패 stage: JSON의 `reason`을 그대로 보여주고, 원문이 지시하는 recovery를 따른다.
+
+## project.json 생성 또는 유지
+
+`<PROJECT_ROOT>/.okstra/project.json`이 있으면 `projectId`와 `projectRoot`를 보여주고 유지/덮어쓰기 여부를 확인한다. 기본은 유지다. 기존 `projectId`를 바꾸려면 파일 삭제가 필요하므로 자동으로 덮어쓰지 않는다.
+
+파일이 없으면 project id를 물어본다. 답변은 비어 있지 않고 alphanumeric 문자를 하나 이상 포함해야 한다. 빈 값으로 `okstra setup --yes`를 호출하면 실패하므로 다시 묻는다.
+
+생성 명령:
+
+```bash
+okstra setup --yes --project-root /abs/project --project-id my-project
+```
+
+## 선택 설정
+
+원문상 Step 4.5-4.9는 사용자가 명시적으로 원할 때만 수행하는 선택 설정이다. 기본값으로 충분하면 건너뛰고 doctor로 간다.
+
+선택 설정:
+
+- `worktreeSyncDirs`: task worktree에 symlink할 프로젝트 상대 디렉터리 목록. 기본은 `.project-docs`, `.scratch`, `graphify-out`, `.claude`.
+- `qaCommands`: implementation verifier가 실행할 check-only lint/format/typecheck/test 명령.
+- `qaEnv`: Tier 3 conformance script가 사용할 replica/test DB, local app URL, env file, surface patterns.
+- PR body template: `okstra config set pr-template-path "<path>" --scope project|global`
+- final report language: `okstra config set report-language <en|ko|auto> --scope project`
+
+`qaCommands.cmd`는 mutation을 암시하는 token을 담으면 verifier가 거부한다. deny-list의 실제 권위는 `scripts/okstra_ctl/qa_commands.py`다.
+
+## 자동 Claude 설정 symlink
+
+`okstra setup`은 `<PROJECT_ROOT>/.claude/settings.local.json`을 `~/.okstra/templates/settings.local.json` symlink로 provision한다. 기존 regular file이 있으면 `.bak.<timestamp>`로 백업한 뒤 symlink를 둔다. 실패 메시지가 나오면 사용자가 기존 project-specific rule을 수동 병합해야 한다.
+
+## 검증
+
+마지막에 실행:
+
+```bash
+okstra doctor --runtime claude-code
+```
+
+모든 check가 OK면 setup 완료로 보고한다. 실패가 있으면 출력 내용을 그대로 보여주고, 재설치/스킵 여부는 사용자가 결정하게 한다.
+
+## 완료 메시지
+
+짧게 다음 정보를 포함한다.
+
+- runtime 위치: `~/.okstra`
+- project metadata: `<PROJECT_ROOT>/.okstra/project.json`
+- `projectId`
+- 다음 단계: `/okstra-run`
+
+## 흔한 실패 처리
+
+| 증상 | 처리 |
+|---|---|
+| `command not found: npx` | Node 18+ 설치 안내 |
+| `--project-id is required` | project id를 다시 물어보고 non-empty 값으로 재실행 |
+| `projectId mismatch` | 어떤 id가 canonical인지 사용자에게 확인. 자동 삭제하지 않음 |
+| `.okstra/` 쓰기 EACCES | ownership/writability 문제를 설명 |
+| `.claude/settings.local.json` symlink warning | 백업 파일과 symlink 상태를 사용자에게 보여주고 수동 병합 안내 |
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.98.1",
+  "version": "0.98.2",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.98.1",
-  "builtAt": "2026-06-22T07:33:44.995Z",
+  "package": "0.98.2",
+  "builtAt": "2026-06-22T12:25:00.654Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/skills/okstra-brief/SKILL.md

@@ -393,9 +393,12 @@ Step 0):
 okstra task-list
 ```
 
-Parse the JSON `tasks[]` array; collect the **distinct** `taskGroup` values
-ordered by `updatedAt` descending. Take the **2 most-recent** distinct
-groups as recommendations.
+Parse the JSON `tasks[]` array. The `taskGroup` field is a **raw display
+name, not a slug** — `slugify` each value (lowercase + non-alphanumeric →
+`-`) and **dedupe by slug** so case/format variants collapse (e.g.
+`uploadFont` and `uploadfont` are one group, not two). Order the distinct
+slugs by their most-recent `updatedAt`. Take the **2 most-recent** distinct
+slugs as recommendations and show them in slug form.
 
 `AskUserQuestion` (single-select):
 
@@ -413,8 +416,14 @@ picker and ask one free-text question:
 `"Task group (e.g. backend-api, INV-1234, refactor)"` → `task_group`.
 
 Slug rule: same as `okstra-run` Step 3 — slugify, must have at least one
-alphanumeric character. Note that an existing group's value is already a
-slug; a `직접 입력` value is slugified before use.
+alphanumeric character. **Always slugify the chosen value**, whether it came
+from an existing-group selection or `직접 입력` — the `taskGroup` returned by
+`okstra task-list` is a raw display name, not a slug, so picking one verbatim
+would create a non-standard directory (e.g. `briefs/uploadFont/`). The brief's
+on-disk directory segment (`briefs/<task-group>/`) and the frontmatter
+`task-group` value are both the slugified form, and `validate-brief.py`
+(Step 6.6) rejects any brief whose directory segment differs from
+`slugify(frontmatter task-group)`.
 
 If `task_group` was already collected by Step 1b sub-step 0 (tracker
 preflight), reuse that value silently — do NOT ask again.
@@ -752,7 +761,7 @@ Use the same template per brief file. In tracker mode producing a parent
 plus N children, you write **N+1 files** (each carries only its own Source
 Material).
 
-The installed template `~/.okstra/templates/reports/brief.template.md` is the byte-for-byte SSOT for the brief shape — frontmatter keys, top-header blockquote, section ordering, and inline `<!-- author guidance -->` HTML comments. Render that file with the per-brief values substituted; leave any section's body as `_(none)_` rather than fabricating content. Preserve the template's HTML comments verbatim (they are part of the contract) but do NOT promote them to body prose.
+The installed template `~/.okstra/templates/reports/brief.template.md` is the byte-for-byte SSOT for the brief shape — frontmatter keys, top-header blockquote, and section ordering. The template's inline `<!-- author guidance -->` HTML comments are fill-in scaffolding for the author, NOT part of the artifact: render the file with per-brief values substituted and **strip every `<!-- ... -->` comment** so the final brief carries none. Leave any section's body as `_(none)_` rather than fabricating content.
 
 **Variant note:** The template file is the canonical reporter-input shape. For the codebase-scan variant (`scope: codebase` in frontmatter), OMIT the `## Source Material` and `## Problem / Symptom` headings entirely — do NOT include them with `_(none)_` bodies. Instead, KEEP the `## Scan Scope` and `## Priority Lenses` sections (already present in the template file, marked with HTML comments). For the error-feedback variant (`scope` omitted ⇒ `reporter-input`), use the reporter-input shape: KEEP `## Source Material` (the chosen cluster's anonymized error records) and `## Problem / Symptom`, and OMIT the codebase-only `## Scan Scope` / `## Priority Lenses` sections. The remaining sections (Context / Desired Outcome / Constraints / Related Artifacts / Open Questions / Reporter Confirmations / Augmentation) apply to all variants.
 
@@ -1010,15 +1019,17 @@ started.
   Augmentation / interpretation goes only into the `Augmentation` section
   or a `> augmented:` blockquote inside the required section.
 - **No template author-guidance in the artifact body.** The Step 5
-  template above carries author guidance in HTML comments
-  (`<!-- ... -->`); preserve those comments when writing the brief but do
-  NOT promote them to body prose. Section headings stay clean — never copy
-  parenthetical reviewer notes onto the heading itself (e.g. emit
+  template carries author guidance in HTML comments (`<!-- ... -->`);
+  **strip every such comment when writing the brief** — the final artifact
+  contains zero `<!-- ... -->` blocks. (The validator now ignores comment
+  regions, but a clean artifact is the contract, and it is what the
+  passing reference briefs look like.) Section headings stay clean — never
+  copy parenthetical reviewer notes onto the heading itself (e.g. emit
   `## Source Material`, not `## Source Material (verbatim — do not modify)`).
   Placeholder prose inside angle brackets (`<Background / scope / why
-  now…>`) is intentional and is meant to be replaced with the reporter's
-  actual content; do not strip the angle-bracket placeholders, replace
-  them.
+  now…>`) is NOT a comment — it is intentional scaffolding meant to be
+  replaced with the reporter's actual content; replace those placeholders,
+  do not leave them in.
 - If the tracker MCP is not connected, do not guess — ask the user to paste
   the body or skip the source.
 - If a URL fetch fails or hits an auth wall, do not guess — ask for a

package/runtime/validators/validate-brief.py

@@ -6,7 +6,8 @@ Checks performed per brief file:
 1. YAML frontmatter exists on line 1 with required keys.
 2. brief-id matches the filename stem.
 3. depth equals the number of `sub/` segments in the path (relative to the
-   `briefs/` root).
+   `briefs/` root), and the task-group directory segment equals the
+   slugified frontmatter `task-group` (lowercase, non-alphanumeric → `-`).
 4. Every Open Questions row starts with one of the five signal prefixes
    (general | terminology | intent-check | conversion-block | adr-candidate).
    `adr-candidate:` targets okstra-internal
@@ -56,6 +57,7 @@ from okstra_ctl.improvement_lenses import (
     MAX_PRIORITY_LENSES,
     MIN_PRIORITY_LENSES,
 )
+from okstra_ctl.ids import slugify_task_segment
 
 REQUIRED_FRONTMATTER_KEYS = {
     "type",
@@ -89,6 +91,23 @@ REPORTER_CONFIRMATION_VALUES = {"complete", "partial", "pending", "skipped"}
 
 SCOPE_VALUES = {"reporter-input", "codebase"}
 
+_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+
+
+def strip_html_comments(text: str) -> str:
+    """Remove `<!-- ... -->` blocks before parsing.
+
+    The brief template carries author-guidance comments whose example rows
+    (`intent-check: <…>`, `conversion-block: <…>`, `terminology-mapping: <…>`)
+    are NOT real entries. Without this, every `- ` collector below
+    (`open_questions_rows`, `augmentation_entries`, `meaningful_bullets`) would
+    count them as data and raise false `reporter-confirmations` / `terminology`
+    failures. Comments are never brief content, so stripping them once here is
+    the single root fix. Frontmatter uses `#` comments only, so this is a no-op
+    for the YAML block.
+    """
+    return _HTML_COMMENT_RE.sub("", text)
+
 
 def strip_yaml_comment(line: str) -> str:
     """Drop a YAML inline comment, keeping `#` that is part of a value.
@@ -268,7 +287,7 @@ def check_reporter_confirmations(
 
 
 def validate_brief(path: Path, briefs_root: Path) -> list[str]:
-    text = path.read_text(encoding="utf-8")
+    text = strip_html_comments(path.read_text(encoding="utf-8"))
     errors: list[str] = []
 
     # 1. frontmatter
@@ -315,8 +334,10 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
     # 3. depth equals path's `sub/` nesting depth
     try:
         rel = path.relative_to(briefs_root)
+        under_root = True
     except ValueError:
         rel = path
+        under_root = False
     # path components after the task-group dir: any number of `sub` segments + filename
     parts = list(rel.parts)
     if len(parts) >= 2:
@@ -332,6 +353,19 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
                 f"frontmatter says depth={fm.get('depth')!r}"
             )
 
+    # 3b. task-group directory segment must equal the slugified frontmatter value.
+    # Catches case/format drift (e.g. dir `uploadFont` vs slug `uploadfont`) that
+    # case-insensitive filesystems hide but case-sensitive CI breaks on.
+    if under_root and len(parts) >= 2:
+        expected_segment = slugify_task_segment(fm.get("task-group", ""))
+        if expected_segment and parts[0] != expected_segment:
+            errors.append(
+                f"task-group directory segment {parts[0]!r} does not match the "
+                f"slugified frontmatter task-group {expected_segment!r} "
+                f"(frontmatter task-group={fm.get('task-group')!r}); rename the "
+                f"directory or fix the frontmatter so both use the slug"
+            )
+
     # 4. Open Questions prefixes
     oq_rows = open_questions_rows(text)
     intent_check_rows: list[str] = []