@buaa_smat/hometrans 0.1.13 → 0.1.14

package/skills/hmos-spec-generate/SKILL.md

@@ -1,332 +1,332 @@
----
-name: hmos-spec-generate
-description: "Generate atomic-scenario requirement specs (markdown) from raw .txt requirement batches for Android-to-HarmonyOS migration. Reads a single .txt holding multiple REQ blocks (blank-line separated), explores the Android code graph via GitNexus, writes per-REQ trace files first then synthesizes specs from the trace. Triggers: spec generation, generate spec, requirement to spec, atomic scenarios, scenario decomposition, decompose scenarios, req to spec, code-trace-first, batch req txt."
-license: MIT
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Skill
-  - AskUserQuestion
-  - TaskCreate
-  - TaskList
-  - TaskUpdate
-  - mcp__gitnexus__query
-  - mcp__gitnexus__context
-  - mcp__gitnexus__impact
-  - mcp__gitnexus__cypher
-  - mcp__gitnexus__list_repos
----
-
-# Spec Generator Skill
-
-Produce atomic-scenario requirement specs from Android source code for Android-to-HarmonyOS migration. The input is a single `.txt` carrying multiple REQ blocks (blank-line separated); each block is processed end-to-end (3.1 → 3.5) before the next block starts.
-
-This skill uses GitNexus as the code-graph backend: the `gitnexus-cli` skill for index management, and `mcp__gitnexus__*` tools for code queries. Spec synthesis MUST go through a trace file written in 3.3 — never synthesize from conversation context.
-
-## Expected Input
-
-- `requirement-description-file`: absolute path to a single `.txt` file containing one or more REQ blocks separated by blank lines. Within each block, the first line is the REQ title (often a dash-separated settings path like `Settings-UserInterface-ImmersionMode`), and the remaining lines are the body (behavior, default values, toggles). Required.
-- `android-project-path`: absolute path to the Android project root (must be inside a Git repo). Required.
-- `spec-output-dir`: absolute path to the directory where spec files will be written (will be created if missing). Required.
-
-**Caller example**:
-
-```
-requirement-description-file: C:\proj\reqs\req-batch2-zh.txt
-android-project-path:         C:\proj\SaltPlayer\
-spec-output-dir:              C:\proj\specs-out\
-```
-
-## Expected Output
-
-- One markdown spec per REQ block, written to `<spec-output-dir>/<feature>-SPEC.md`. `<feature>` is the ≤ 20-character slug distilled in 3.1 (use the REQ's own language for the slug; ASCII / kebab-case acceptable when shorter).
-- One intermediate code-trace file per REQ block, written to `<spec-output-dir>/.trace/<feature>.md` (same slug). 3.5 synthesis MUST `Read` this file rather than recalling from conversation context.
-- Both files overwrite if they already exist.
-
----
-
-## Principles
-
-Rules the final spec MUST obey:
-
-1. Decompose the requirement into atomic scenarios — their union reconstitutes the full requirement.
-2. Each atomic scenario corresponds to one happy path OR one boundary / exception path.
-3. Atomic scenarios MUST be exhaustive and mutually non-redundant.
-4. The spec MUST contain a requirement-level semantic description, scenario-level semantic descriptions, and scenario flow descriptions.
-5. Scenario flow descriptions MUST contain both a trigger action sequence and the corresponding logical execution steps.
-6. The spec MUST NOT contain any Android-related knowledge, design, or code-level description. See `references/android-platform-tokens.md` for the full strip list and Chinese replacement vocabulary.
-7. When `REQ_DESC` disagrees with the Android code implementation, the spec follows `REQ_DESC`; discrepancies are summarized at the end of the spec in user-facing language.
-8. **Coverage rule** — scenarios MUST cover ALL UI entries discovered in code, not just those explicitly mentioned in `REQ_DESC`. If the trace's Scope / Boundary section enumerates N entries and `REQ_DESC` only mentions M < N, the spec still produces scenarios for all N. Missing entries here = missing scenarios in the spec.
-
----
-
-## Method Discipline
-
-Cross-cutting disciplines for trace exploration (3.1 → 3.3), verified in 3.4 Review.
-
-### Multi-layer claim
-
-**Rule**: A user-observable behavior on Android is typically carried by multiple source layers. Every claim in the trace MUST enumerate each relevant layer's state — either a `file:line` hit, or an explicit `N/A: <reason>` saying why that layer does not carry it. This applies to both positive claims ("this behavior is wired at X") and negative ones ("Y does not exist"). Omitting a layer = layer not checked, never = layer not present.
-
-Android source layers:
-
-| Layer | Examples |
-|---|---|
-| **code** | Java / Kotlin / Compose source (`.java`, `.kt`) — click handlers, ViewModels, Services, Repositories, DAOs, Workers |
-| **resource** | `res/layout/*.xml`, `res/menu/*.xml`, `res/drawable/*.xml`, `res/values/*.xml`, `res/xml/*.xml` (preference screens), `res/navigation/*.xml` |
-| **manifest** | `AndroidManifest.xml` (activity / service / receiver / provider / permission / intent-filter / foreground-service-type declarations); `build.gradle` flavor or `buildConfig` flags when behavior is build-gated |
-
-### Replayable fact
-
-**Rule**: Every fact in the trace MUST be **replayable verbatim** from a tool response. `file:line` anchors come from `mcp__gitnexus__context` / `cypher` results or the line-number prefix of a `Read` output. Phrases with counts or ordering ("called N times", "first X then Y", "synchronously then asynchronously", "again") MUST be derivable from precise tool-driven counting and sequencing (e.g. `mcp__gitnexus__cypher` aggregating callers, or repeated `mcp__gitnexus__impact` calls). Delete any fact that cannot be replayed.
-
-**Common failure mode**: Hallucinate detail by analogy with common patterns ("synchronous write then asynchronous overwrite", "set X again"); estimate a line number from a `mcp__gitnexus__context` snippet and drift to a neighbouring symbol; make negative assertions from intuition instead of reverse-lookup with `mcp__gitnexus__impact` / `cypher` / `Grep`.
-
----
-
-## References
-
-External resources Read on demand (not pre-loaded). Loading these too early wastes context budget; load each only at the step that needs it.
-
-| File | When to read |
-|---|---|
-| `references/spec-sample-1.md` | 3.5 Synthesize — boundary-and-happy-path decomposition style |
-| `references/spec-sample-2.md` | 3.5 Synthesize — nested sub-bullet decomposition style |
-| `references/spec-sample-3.md` | 3.5 Synthesize — shared-mechanic + per-value decomposition for enumerated multi-entry settings |
-| `references/android-platform-tokens.md` | 3.5 Synthesize — platform-token strip list + Chinese replacement vocabulary |
-| `references/step4-report-template.md` | Step 4 — summary report output format |
-
-Mimic the samples' voice, scenario granularity, and structure — NOT their vocabulary or domain. The samples happen to use consumer-app domains (music / video); this skill applies to any Android application domain.
-
----
-
-## Workflow
-
-### Step 0 — Validate inputs and parse REQ blocks
-
-1. Verify `requirement-description-file` exists and is a file. If not, stop and report.
-2. Verify `android-project-path` exists and is a directory. If not, stop and report.
-3. Ensure `spec-output-dir` exists (create if missing). Ensure `<spec-output-dir>/.trace/` exists (create if missing).
-4. **Parse the input `.txt`** (UTF-8):
-   - Split into REQ blocks by blank lines. Each block: first non-blank line = `title`, remaining non-blank lines = `body`.
-   - If a block has empty `body`, mark it for skip with reason `empty body`; do not abort the whole batch.
-   - If the file yields zero blocks, stop and report.
-5. **Distill a feature slug** for each block:
-   - Summarize the REQ into a `<feature>` phrase. **≤ 20 characters, in the REQ's own language.**
-   - Sanitize illegal filesystem characters (`< > : " / \ | ? *` and ASCII control chars) by replacing each with `-`.
-   - Different REQ blocks should produce different features. Titles already encode the top-level category (e.g. `Settings-UI-...` vs `Settings-Lyrics-...`); retain enough category context in the slug to keep distinct.
-   - The slug is the filename stem for both the trace (`.trace/<feature>.md`) and the spec (`<feature>-SPEC.md`).
-
-Step 0 output: an ordered list of `(title, body, feature)` tuples plus a skip list. Proceed directly to Step 1.
-
-### Step 1 — Confirm the Android project is a Git repo
-
-Run `git rev-parse --is-inside-work-tree` inside `android-project-path`.
-
-- Output is `true` → proceed to Step 2.
-- Otherwise → STOP. Tell the user:
-
-  > `android-project-path` is not a Git repository. GitNexus indexes by Git identity. Please run:
-  >
-  > ```
-  > cd <android-project-path>
-  > git init && git add . && git commit -m "init"
-  > ```
-  >
-  > then re-invoke this skill.
-
-Do NOT auto-`init` / `add` / `commit` the user's project. Do NOT modify `git config`.
-
-### Step 2 — Ensure GitNexus has a fresh index for the project
-
-GitNexus exposes two surfaces:
-
-- **Index management** (`status`, `analyze`) → invoke the `gitnexus-cli` skill (CLI wrapper, returns text).
-- **Code queries** (`query`, `context`, `impact`, `cypher`, `list_repos`) → call `mcp__gitnexus__*` tools directly.
-
-Procedure:
-
-1. Invoke `gitnexus-cli` skill with `status` against `android-project-path`.
-2. Decide based on the output:
-   - **Not registered** or **stale** → invoke `gitnexus-cli` with `analyze`, wait for completion.
-   - **Fresh** → proceed.
-3. Obtain `<repo-id>` via `mcp__gitnexus__list_repos()`; find the entry whose `path` matches `android-project-path`; take its `repo` (or equivalent identifier) field.
-
-**Hard fail policy** — any of the following stops the skill and surfaces the error to the user; do NOT degrade to `Read` + `Grep`:
-
-- `gitnexus-cli` skill is unavailable → ask the user to run `/setup` first.
-- `gitnexus-cli status` or `analyze` returns an error → surface the error verbatim.
-- `mcp__gitnexus__list_repos` returns no matching entry → ask the user to verify that `analyze` registered the project.
-- Any `mcp__gitnexus__*` call in Step 3 fails unexpectedly → surface the error; stop the skill.
-
-> All `mcp__gitnexus__*` calls in Step 3 MUST carry `repo=<repo-id>` (or equivalent scope parameter). Cross-repo results poison the trace.
-
-### Step 3 — Process each REQ block end-to-end
-
-Iterate the `(title, body, feature)` tuples from Step 0 in order. For each tuple, run **3.1 → 3.5** in full before starting the next. Do NOT batch code exploration across REQ blocks.
-
-Order matters: build the trace from Android source first, then synthesize the spec from the trace. Spec synthesis (3.5) MUST `Read` the trace written in 3.3 / 3.4 — recalling from conversation context causes scenario drift and `file:line` fabrication.
-
-#### 3.1 Read
-
-- Use the parsed `body` directly (already loaded in Step 0). If the tuple is marked `skip: empty body`, skip to the next tuple and record in Step 4 report.
-- Extract from `body`: UI path / page anchors (if any), primary user intent, key entities (data models, persistence key names, setting names), explicit boundary conditions (default values, toggle states, error messages, length limits).
-- For dependent REQs (body mentions "depends on X" or similar), note the dependency for the 3.3 trace's `Core business entities` section.
-
-#### 3.2 Recall — Locate entry points (dual-path union)
-
-Run both paths in parallel within the same turn (emit all mcp calls together); the deduplicated union is the recall result. All mcp calls MUST carry `repo=<repo-id>`.
-
-| Path | Approach | Value |
-|---|---|---|
-| **Path 1 · By-concept lookup** | For each entity / UI anchor / intent verb from 3.1, call `mcp__gitnexus__query({ query: "<concept>", repo: "<repo-id>" })` and `mcp__gitnexus__context({ name: "<symbol>", repo: "<repo-id>" })` to find candidate symbols (Activities / Fragments / Composables / ViewModels / Services / Repositories / DAOs). Cross-validate symbol name, file path, and context against `REQ_DESC`. | Direct hits: pages obviously implementing the REQ; data models named after REQ entities. |
-| **Path 2 · Reverse-by-usage** | Take the most discriminative keyword (a settings key literal, a persistence column / preference key, a unique business term). `query` → candidate symbol → `mcp__gitnexus__impact({ name: "<symbol>", repo: "<repo-id>" })` returns callers (nested). Walk callers upward until hitting an `Activity` / `Fragment` / `@Composable` host. That host is an entry point. If the walk passes through intermediate dialog / popup / bottom-sheet / inner-composable components that directly reference the target key, record each as a **separate entry point** — these represent distinct user-facing surfaces within the host. | Covers structural blind spots Path 1 misses: deeply nested consumers, pass-through navigation pages, manifest-declared receivers. |
-
-**Behavioral REQ anchor extraction**: when `REQ_DESC` has no explicit literal keyword (e.g. "after track-change X refreshes synchronously"), extract anchors as `(action verb, affected entity)` tuples — e.g. `(track-change, X)` — and feed both into Path 1's `query` and Path 2's seed symbol search.
-
-**Both paths hit zero** → ask the user via `AskUserQuestion` whether to manually specify an entry point. If declined → write `status: no_recall` in the trace, skip 3.3 / 3.4 / 3.5, flag in Step 4 report. Do NOT fabricate entry points.
-
-**Terse REQ handling** — if the REQ body has fewer than ~20 substantive characters, OR contains only topical keywords (e.g. "multi-device", "landscape/portrait") with no concrete action verb / entity:
-
-1. **MUST** run two broad enumeration passes (both mandatory, not optional):
-   - **Pass A · Feature code**: `mcp__gitnexus__cypher` enumeration — find all Activity / Fragment / Composable hosts whose `configChanges` manifest attribute is non-default (for orientation / resize cases) or whose layout has a resource qualifier matching the REQ topic (e.g. `-land`, `-sw600dp`, `-night`).
-   - **Pass B · Settings breadth**: For EACH distinct keyword in the REQ body, run `mcp__gitnexus__query` + `Grep` to enumerate ALL settings / configuration screens that reference that keyword or a semantically related term. Terse REQs frequently span multiple unrelated settings pages; anchoring on the single most obvious page is the primary failure mode. The union of Pass A and Pass B is the recall result.
-2. If ≥3 plausible candidates → list them in the trace's `Status` section as `candidate_hosts: [...]` and proceed normally.
-3. If <3 candidates → invoke `AskUserQuestion`: show the candidate list, ask which are in-scope for this REQ. Do NOT silently guess.
-4. Mark in trace `Status` block: `terse_req: true` (this signal feeds 3.4 review).
-5. **3.4 Review MUST verify**: every settings screen discovered in Pass B has at least one Entry or Touched-entry in the trace. A discovered-but-untraced screen → fail review, return to 3.3.
-
-**Clarification triggers** (interrupt 3.2 / 3.3 with `AskUserQuestion`):
-
-- `REQ_DESC` contains ambiguous phrases ("any entry point", "related pages", "all related locations") AND the trace cannot map them to a unique set of components.
-- Path 1 + Path 2 both return zero, before writing `no_recall`.
-- Deviations from `REQ_DESC` exceed five AND touch core behavior (REQ may be stale; confirm before proceeding).
-
-#### 3.3 Trace — Explore code and write `<spec-output-dir>/.trace/<feature>.md`
-
-The trace file is the sole machine-readable contract delivered to 3.5. Exploration and writing form a single unit.
-
-**Exploration checklist — execution order** (all mcp calls carry `repo: "<repo-id>"`):
-
-| Step | Action | Tool |
-|---|---|---|
-| 1 | Survey candidate symbols for each anchor from 3.1 | `mcp__gitnexus__query` / `context` |
-| 2 | Full call chain (callers / callees, up and down) | `mcp__gitnexus__impact` |
-| 3 | Cross-class graph traversal / reverse-lookup state writers / aggregation | `mcp__gitnexus__cypher` |
-| 4 | Exact literal positioning (settings keys, DAO columns, intent actions, preference `android:key`) | `Grep` |
-| 5 | Final `file:line` verification / zero-hit counter-evidence | `Read` (small window) / `Grep` |
-
-**Exploration dimensions — information coverage** (orthogonal to the checklist; checklist = order, dimensions = what to capture). Apply each to every recall entry:
-
-- **Trigger code** — UI control + event callback (click / long-press / swipe / lifecycle / broadcast receiver) invoking the REQ behavior. Fill Entry's `code` and `resource` layer fields.
-- **End-to-end call chain** — trigger → ViewModel / UseCase → Service / Repository → data source. Fill Entry's `data_flow`; each hop carries `file:line`.
-- **State writes & persistence** — every state mutation (state holders, DAO inserts, preference / DataStore / MMKV puts, file writes). Record key / column names verbatim.
-- **Side effects / cross-boundary** — broadcasts, bound services, notifications, App Widget IPC, content providers, accessibility events.
-- **Manifest declarations / build flags** — activity / service / receiver registration, intent filters, permissions, foreground service types, build flavor / `buildConfig` gates. Fill Entry's `manifest` field — `N/A: <reason>` if none.
-- **Deviations from `REQ_DESC`** — every gap (default values, copy strings, behavior, hidden entries, validation rules). Feeds Principle 7.
-- **Application scope / boundary · Exhaustive entry enumeration** — ALL UI paths touching this feature / state, beyond REQ text. For state keys: reverse-lookup writers + lift to UI hosts. For readers: enumerate consumers + non-consumers. One field block per entry; omitted here = scenario omitted in spec.
-- **Consumer list & non-consumers** — who reads this state, plus which UI surfaces explicitly do NOT. Non-consumer claims use the structured field block (`claim` / `closure_layers` / `tools` / `zero_hits`).
-
-**Trace file template** (write to `<spec-output-dir>/.trace/<feature>.md`):
-
-```markdown
-# Code trace · <feature>
-
-## Status
-status: ok | no_recall | error
-repo-id: <repo-id>
-backend: gitnexus
-
-## Recalled entry points (Path 1 + Path 2 union, deduplicated)
-- Entry 1: <UI path / page name> — file:line — recalled by: path 1 | path 2 | both
-- ...
-
-## Entry · <name>
-- claim: <user-observable behavior in one sentence>
-- layers:
-  - code:     <file:line>                  # required; hit or `N/A: <reason>`
-  - resource: <file:line> | N/A: <reason>  # layout / menu / drawable / values / xml-preferences / navigation
-  - manifest: <file:line> | N/A: <reason>  # AndroidManifest entry / build.gradle flag
-- interaction: <state writes, persistence keys (verbatim), in-memory mutations>
-- data_flow:   <trigger → ViewModel / Service / Repo → data source, each hop with file:line>
-
-## Entry · <name 2> ... Entry · <name N>
-(each entry repeats the claim / layers / interaction / data_flow field block)
-
-## Implicit triggers (non-UI state changes that activate this feature)
-- Trigger: <track-change / Pro status change / permission change / foreground-background switch / network change / lyrics document change / current track is null> — <file:line> — behavior: <one sentence>
-- (write "None" if no implicit trigger applies)
-
-## Core business entities (data model / persistence key / state machine)
-- Entity X: <file:line + field list + semantics>
-- For dependent REQs: <dependency-key-name> sourced from feature `<depended-feature>` at file:line
-- ...
-
-## Cross-entry shared declarations
-- <AndroidManifest.xml / build.gradle entries with file:line, shared across multiple entries>
-- ... (write "None" explicitly if no cross-entry declaration applies; per-entry manifest facts live in each Entry's `manifest` layer field)
-
-## Deviations from REQ_DESC
-1. <REQ says A; but code at file:line behaves as B>
-2. ...
-(empty → write "None" explicitly to confirm the check was performed)
-
-## Scope / Boundary — Exhaustive entry enumeration
-### Touched entries (all UI paths, not limited to REQ_DESC mentions)
-(each touched entry uses the same `claim` / `layers` / `interaction` / `data_flow` field block as the Entry template above)
-
-### Consumers (who reads this state / data)
-- Consumer: <component name> — file:line
-
-### Non-consumers (boundary counter-examples with evidence)
-- claim:          <e.g. "App widget does not read this key">
-  closure_layers: [code, resource, manifest]
-  tools:          [Grep "<pattern>", mcp__gitnexus__cypher "<...>", Read "<path>"]
-  zero_hits:      <verbatim zero-hit evidence — file globs searched, regex used, hit count>
-
-## Same-source cross-reference (if applicable)
-- This REQ shares behavior with feature `<other-feature>` (e.g. the same setting exposed under multiple settings paths).
-  Both specs are generated independently and reference each other in their deviation sections.
-- (write "None" if not applicable)
-```
-
-#### 3.4 Review — No fabrication, no omission, method-discipline compliant
-
-Run the checks below against the trace from 3.3; every check must pass before proceeding to 3.5.
-
-- **No fabrication** — every declared `file:line` actually exists (sample-verify via `mcp__gitnexus__context` or `Read`); every behavioral claim is source-supported; every boundary claim has tool evidence.
-- **No omission** — every detail in `REQ_DESC` has a counterpart in the trace (Entry / behavior / deviation). If REQ mentions a feature code does not implement, record as deviation, not omission.
-- **Method-discipline compliance** (Multi-layer claim + Replayable fact) — sample-verify random `file:line` anchors via `mcp__gitnexus__context` / `Read` (≥1 line drift → fail); sample-verify every count / ordering phrase against source (unreplayable → fail); every Entry / Touched-entry has all three layer fields filled (hit or `N/A: <reason>`); every Non-consumer claim has all four structured fields (`claim` / `closure_layers` / `tools` / `zero_hits`).
-- **Implicit triggers coverage** — the trace's `Implicit triggers` section is present and explicitly filled (≥1 trigger OR `None`). Absence of the section = fail review.
-- **Trace section presence audit** — every trace MUST contain these H2 sections (with `None` if truly empty; absence = fail): `Status` / `Recalled entry points` / per `Entry` (all 4 fields: `claim` / `layers` / `interaction` / `data_flow`) / `Implicit triggers` / `Core business entities` / `Cross-entry shared declarations` / `Deviations from REQ_DESC` / `Scope / Boundary` / `Same-source cross-reference`.
-
-Any check failing → return to 3.3 (rewrite / supplement / fix). Judge convergence yourself; no external iteration cap. All checks pass → proceed to 3.5.
-
-#### 3.5 Synthesize — Write the final spec
-
-`Read` the trace from 3.3 / 3.4, then synthesize the spec following `## Principles` and the style references under `references/`. Write to `<spec-output-dir>/<feature>-SPEC.md` (overwrite if exists).
-
-**Synthesis discipline**:
-
-- **Implicit triggers coverage** — every entry in the trace's `Implicit triggers` section MUST appear in the spec as an independent scenario OR as a main step within an existing scenario. Listed in trace but absent from spec = scenario omission. (Extends Principle 8 to non-UI triggers.)
-- **Shared-mechanic factoring** — for enumerated-value settings (three-way / four-way / radio-group) accessible from multiple entry points, factor the shared menu interaction across all entries into ONE scenario; give each enum value its OWN runtime-semantics scenario. Do NOT split the mechanical scenario per entry point, and do NOT bundle "user picks X" with "what X does" in the same scenario per value.
-- **Binary-toggle anti-pattern** — a binary on/off switch is ONE trigger; write ONE scenario for the toggle (both directions), with linked-control side-effects as sub-bullets. Write SEPARATE scenarios for each state's runtime rendering (e.g. "when ON, cover rotates" / "when OFF, cover is static"). Do NOT split "turn on" / "turn off" into independent scenes.
-- **Same-source cross-reference** — if the trace's `Same-source cross-reference` section is non-empty, append a short note at the end of the spec referencing the other `<feature>-SPEC.md` (e.g. "This setting also exists under `<other-feature>-SPEC.md` with identical behavior").
-- **REQ-vs-code-string arbitration** — code's user-facing strings (toast / notification / dialog / snackbar / error) that conflict with `REQ_DESC` are **deviation evidence**, NOT authoritative facts. Author spec body per `REQ_DESC` phrasing; record the conflicting string + `file:line` in trace's `Deviations`. Do NOT copy code strings verbatim into the spec.
-
-After writing, proceed to the next REQ block.
-
-### Step 4 — Summary report
-
-Once all REQ blocks are processed (or skipped with warnings), produce a brief report following `references/step4-report-template.md`. The template defines the per-block table format, skipped-block list, and aggregates. Keep the in-session reply within ~40 lines; per-block detail belongs in spec / trace files.
-
----
-
-## Forbidden
-
-- **No nested LLM-agent skill calls** — no `gitnexus-exploring`, no `gitnexus-debugging`, no `gitnexus-refactoring`, no `gitnexus-impact-analysis`. They override this SKILL's instructions and cause role drift. **Exception**: `gitnexus-cli` is a CLI wrapper (not an LLM agent); using it for index management is allowed.
+---
+name: hmos-spec-generate
+description: "Generate atomic-scenario requirement specs (markdown) from raw .txt requirement batches for Android-to-HarmonyOS migration. Reads a single .txt holding multiple REQ blocks (blank-line separated), explores the Android code graph via GitNexus, writes per-REQ trace files first then synthesizes specs from the trace. Triggers: spec generation, generate spec, requirement to spec, atomic scenarios, scenario decomposition, decompose scenarios, req to spec, code-trace-first, batch req txt."
+license: MIT
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Skill
+  - AskUserQuestion
+  - TaskCreate
+  - TaskList
+  - TaskUpdate
+  - mcp__gitnexus__query
+  - mcp__gitnexus__context
+  - mcp__gitnexus__impact
+  - mcp__gitnexus__cypher
+  - mcp__gitnexus__list_repos
+---
+
+# Spec Generator Skill
+
+Produce atomic-scenario requirement specs from Android source code for Android-to-HarmonyOS migration. The input is a single `.txt` carrying multiple REQ blocks (blank-line separated); each block is processed end-to-end (3.1 → 3.5) before the next block starts.
+
+This skill uses GitNexus as the code-graph backend: the `gitnexus-cli` skill for index management, and `mcp__gitnexus__*` tools for code queries. Spec synthesis MUST go through a trace file written in 3.3 — never synthesize from conversation context.
+
+## Expected Input
+
+- `requirement_description_file`: absolute path to a single `.txt` file containing one or more REQ blocks separated by blank lines. Within each block, the first line is the REQ title (often a dash-separated settings path like `Settings-UserInterface-ImmersionMode`), and the remaining lines are the body (behavior, default values, toggles). Required.
+- `android_project_dir`: absolute path to the Android project root (must be inside a Git repo). Required.
+- `spec_output_dir`: absolute path to the directory where spec files will be written (will be created if missing). Required.
+
+**Caller example**:
+
+```
+requirement_description_file: C:\proj\reqs\req-batch2-zh.txt
+android_project_dir:         C:\proj\SaltPlayer\
+spec_output_dir:              C:\proj\specs-out\
+```
+
+## Expected Output
+
+- One markdown spec per REQ block, written to `<spec_output_dir>/<feature>-SPEC.md`. `<feature>` is the ≤ 20-character slug distilled in 3.1 (use the REQ's own language for the slug; ASCII / kebab-case acceptable when shorter).
+- One intermediate code-trace file per REQ block, written to `<spec_output_dir>/.trace/<feature>.md` (same slug). 3.5 synthesis MUST `Read` this file rather than recalling from conversation context.
+- Both files overwrite if they already exist.
+
+---
+
+## Principles
+
+Rules the final spec MUST obey:
+
+1. Decompose the requirement into atomic scenarios — their union reconstitutes the full requirement.
+2. Each atomic scenario corresponds to one happy path OR one boundary / exception path.
+3. Atomic scenarios MUST be exhaustive and mutually non-redundant.
+4. The spec MUST contain a requirement-level semantic description, scenario-level semantic descriptions, and scenario flow descriptions.
+5. Scenario flow descriptions MUST contain both a trigger action sequence and the corresponding logical execution steps.
+6. The spec MUST NOT contain any Android-related knowledge, design, or code-level description. See `references/android-platform-tokens.md` for the full strip list and Chinese replacement vocabulary.
+7. When `REQ_DESC` disagrees with the Android code implementation, the spec follows `REQ_DESC`; discrepancies are summarized at the end of the spec in user-facing language.
+8. **Coverage rule** — scenarios MUST cover ALL UI entries discovered in code, not just those explicitly mentioned in `REQ_DESC`. If the trace's Scope / Boundary section enumerates N entries and `REQ_DESC` only mentions M < N, the spec still produces scenarios for all N. Missing entries here = missing scenarios in the spec.
+
+---
+
+## Method Discipline
+
+Cross-cutting disciplines for trace exploration (3.1 → 3.3), verified in 3.4 Review.
+
+### Multi-layer claim
+
+**Rule**: A user-observable behavior on Android is typically carried by multiple source layers. Every claim in the trace MUST enumerate each relevant layer's state — either a `file:line` hit, or an explicit `N/A: <reason>` saying why that layer does not carry it. This applies to both positive claims ("this behavior is wired at X") and negative ones ("Y does not exist"). Omitting a layer = layer not checked, never = layer not present.
+
+Android source layers:
+
+| Layer | Examples |
+|---|---|
+| **code** | Java / Kotlin / Compose source (`.java`, `.kt`) — click handlers, ViewModels, Services, Repositories, DAOs, Workers |
+| **resource** | `res/layout/*.xml`, `res/menu/*.xml`, `res/drawable/*.xml`, `res/values/*.xml`, `res/xml/*.xml` (preference screens), `res/navigation/*.xml` |
+| **manifest** | `AndroidManifest.xml` (activity / service / receiver / provider / permission / intent-filter / foreground-service-type declarations); `build.gradle` flavor or `buildConfig` flags when behavior is build-gated |
+
+### Replayable fact
+
+**Rule**: Every fact in the trace MUST be **replayable verbatim** from a tool response. `file:line` anchors come from `mcp__gitnexus__context` / `cypher` results or the line-number prefix of a `Read` output. Phrases with counts or ordering ("called N times", "first X then Y", "synchronously then asynchronously", "again") MUST be derivable from precise tool-driven counting and sequencing (e.g. `mcp__gitnexus__cypher` aggregating callers, or repeated `mcp__gitnexus__impact` calls). Delete any fact that cannot be replayed.
+
+**Common failure mode**: Hallucinate detail by analogy with common patterns ("synchronous write then asynchronous overwrite", "set X again"); estimate a line number from a `mcp__gitnexus__context` snippet and drift to a neighbouring symbol; make negative assertions from intuition instead of reverse-lookup with `mcp__gitnexus__impact` / `cypher` / `Grep`.
+
+---
+
+## References
+
+External resources Read on demand (not pre-loaded). Loading these too early wastes context budget; load each only at the step that needs it.
+
+| File | When to read |
+|---|---|
+| `references/spec-sample-1.md` | 3.5 Synthesize — boundary-and-happy-path decomposition style |
+| `references/spec-sample-2.md` | 3.5 Synthesize — nested sub-bullet decomposition style |
+| `references/spec-sample-3.md` | 3.5 Synthesize — shared-mechanic + per-value decomposition for enumerated multi-entry settings |
+| `references/android-platform-tokens.md` | 3.5 Synthesize — platform-token strip list + Chinese replacement vocabulary |
+| `references/step4-report-template.md` | Step 4 — summary report output format |
+
+Mimic the samples' voice, scenario granularity, and structure — NOT their vocabulary or domain. The samples happen to use consumer-app domains (music / video); this skill applies to any Android application domain.
+
+---
+
+## Workflow
+
+### Step 0 — Validate inputs and parse REQ blocks
+
+1. Verify `requirement_description_file` exists and is a file. If not, stop and report.
+2. Verify `android_project_dir` exists and is a directory. If not, stop and report.
+3. Ensure `spec_output_dir` exists (create if missing). Ensure `<spec_output_dir>/.trace/` exists (create if missing).
+4. **Parse the input `.txt`** (UTF-8):
+   - Split into REQ blocks by blank lines. Each block: first non-blank line = `title`, remaining non-blank lines = `body`.
+   - If a block has empty `body`, mark it for skip with reason `empty body`; do not abort the whole batch.
+   - If the file yields zero blocks, stop and report.
+5. **Distill a feature slug** for each block:
+   - Summarize the REQ into a `<feature>` phrase. **≤ 20 characters, in the REQ's own language.**
+   - Sanitize illegal filesystem characters (`< > : " / \ | ? *` and ASCII control chars) by replacing each with `-`.
+   - Different REQ blocks should produce different features. Titles already encode the top-level category (e.g. `Settings-UI-...` vs `Settings-Lyrics-...`); retain enough category context in the slug to keep distinct.
+   - The slug is the filename stem for both the trace (`.trace/<feature>.md`) and the spec (`<feature>-SPEC.md`).
+
+Step 0 output: an ordered list of `(title, body, feature)` tuples plus a skip list. Proceed directly to Step 1.
+
+### Step 1 — Confirm the Android project is a Git repo
+
+Run `git rev-parse --is-inside-work-tree` inside `android_project_dir`.
+
+- Output is `true` → proceed to Step 2.
+- Otherwise → STOP. Tell the user:
+
+  > `android_project_dir` is not a Git repository. GitNexus indexes by Git identity. Please run:
+  >
+  > ```
+  > cd <android_project_dir>
+  > git init && git add . && git commit -m "init"
+  > ```
+  >
+  > then re-invoke this skill.
+
+Do NOT auto-`init` / `add` / `commit` the user's project. Do NOT modify `git config`.
+
+### Step 2 — Ensure GitNexus has a fresh index for the project
+
+GitNexus exposes two surfaces:
+
+- **Index management** (`status`, `analyze`) → invoke the `gitnexus-cli` skill (CLI wrapper, returns text).
+- **Code queries** (`query`, `context`, `impact`, `cypher`, `list_repos`) → call `mcp__gitnexus__*` tools directly.
+
+Procedure:
+
+1. Invoke `gitnexus-cli` skill with `status` against `android_project_dir`.
+2. Decide based on the output:
+   - **Not registered** or **stale** → invoke `gitnexus-cli` with `analyze`, wait for completion.
+   - **Fresh** → proceed.
+3. Obtain `<repo-id>` via `mcp__gitnexus__list_repos()`; find the entry whose `path` matches `android_project_dir`; take its `repo` (or equivalent identifier) field.
+
+**Hard fail policy** — any of the following stops the skill and surfaces the error to the user; do NOT degrade to `Read` + `Grep`:
+
+- `gitnexus-cli` skill is unavailable → ask the user to run `/setup` first.
+- `gitnexus-cli status` or `analyze` returns an error → surface the error verbatim.
+- `mcp__gitnexus__list_repos` returns no matching entry → ask the user to verify that `analyze` registered the project.
+- Any `mcp__gitnexus__*` call in Step 3 fails unexpectedly → surface the error; stop the skill.
+
+> All `mcp__gitnexus__*` calls in Step 3 MUST carry `repo=<repo-id>` (or equivalent scope parameter). Cross-repo results poison the trace.
+
+### Step 3 — Process each REQ block end-to-end
+
+Iterate the `(title, body, feature)` tuples from Step 0 in order. For each tuple, run **3.1 → 3.5** in full before starting the next. Do NOT batch code exploration across REQ blocks.
+
+Order matters: build the trace from Android source first, then synthesize the spec from the trace. Spec synthesis (3.5) MUST `Read` the trace written in 3.3 / 3.4 — recalling from conversation context causes scenario drift and `file:line` fabrication.
+
+#### 3.1 Read
+
+- Use the parsed `body` directly (already loaded in Step 0). If the tuple is marked `skip: empty body`, skip to the next tuple and record in Step 4 report.
+- Extract from `body`: UI path / page anchors (if any), primary user intent, key entities (data models, persistence key names, setting names), explicit boundary conditions (default values, toggle states, error messages, length limits).
+- For dependent REQs (body mentions "depends on X" or similar), note the dependency for the 3.3 trace's `Core business entities` section.
+
+#### 3.2 Recall — Locate entry points (dual-path union)
+
+Run both paths in parallel within the same turn (emit all mcp calls together); the deduplicated union is the recall result. All mcp calls MUST carry `repo=<repo-id>`.
+
+| Path | Approach | Value |
+|---|---|---|
+| **Path 1 · By-concept lookup** | For each entity / UI anchor / intent verb from 3.1, call `mcp__gitnexus__query({ query: "<concept>", repo: "<repo-id>" })` and `mcp__gitnexus__context({ name: "<symbol>", repo: "<repo-id>" })` to find candidate symbols (Activities / Fragments / Composables / ViewModels / Services / Repositories / DAOs). Cross-validate symbol name, file path, and context against `REQ_DESC`. | Direct hits: pages obviously implementing the REQ; data models named after REQ entities. |
+| **Path 2 · Reverse-by-usage** | Take the most discriminative keyword (a settings key literal, a persistence column / preference key, a unique business term). `query` → candidate symbol → `mcp__gitnexus__impact({ name: "<symbol>", repo: "<repo-id>" })` returns callers (nested). Walk callers upward until hitting an `Activity` / `Fragment` / `@Composable` host. That host is an entry point. If the walk passes through intermediate dialog / popup / bottom-sheet / inner-composable components that directly reference the target key, record each as a **separate entry point** — these represent distinct user-facing surfaces within the host. | Covers structural blind spots Path 1 misses: deeply nested consumers, pass-through navigation pages, manifest-declared receivers. |
+
+**Behavioral REQ anchor extraction**: when `REQ_DESC` has no explicit literal keyword (e.g. "after track-change X refreshes synchronously"), extract anchors as `(action verb, affected entity)` tuples — e.g. `(track-change, X)` — and feed both into Path 1's `query` and Path 2's seed symbol search.
+
+**Both paths hit zero** → ask the user via `AskUserQuestion` whether to manually specify an entry point. If declined → write `status: no_recall` in the trace, skip 3.3 / 3.4 / 3.5, flag in Step 4 report. Do NOT fabricate entry points.
+
+**Terse REQ handling** — if the REQ body has fewer than ~20 substantive characters, OR contains only topical keywords (e.g. "multi-device", "landscape/portrait") with no concrete action verb / entity:
+
+1. **MUST** run two broad enumeration passes (both mandatory, not optional):
+   - **Pass A · Feature code**: `mcp__gitnexus__cypher` enumeration — find all Activity / Fragment / Composable hosts whose `configChanges` manifest attribute is non-default (for orientation / resize cases) or whose layout has a resource qualifier matching the REQ topic (e.g. `-land`, `-sw600dp`, `-night`).
+   - **Pass B · Settings breadth**: For EACH distinct keyword in the REQ body, run `mcp__gitnexus__query` + `Grep` to enumerate ALL settings / configuration screens that reference that keyword or a semantically related term. Terse REQs frequently span multiple unrelated settings pages; anchoring on the single most obvious page is the primary failure mode. The union of Pass A and Pass B is the recall result.
+2. If ≥3 plausible candidates → list them in the trace's `Status` section as `candidate_hosts: [...]` and proceed normally.
+3. If <3 candidates → invoke `AskUserQuestion`: show the candidate list, ask which are in-scope for this REQ. Do NOT silently guess.
+4. Mark in trace `Status` block: `terse_req: true` (this signal feeds 3.4 review).
+5. **3.4 Review MUST verify**: every settings screen discovered in Pass B has at least one Entry or Touched-entry in the trace. A discovered-but-untraced screen → fail review, return to 3.3.
+
+**Clarification triggers** (interrupt 3.2 / 3.3 with `AskUserQuestion`):
+
+- `REQ_DESC` contains ambiguous phrases ("any entry point", "related pages", "all related locations") AND the trace cannot map them to a unique set of components.
+- Path 1 + Path 2 both return zero, before writing `no_recall`.
+- Deviations from `REQ_DESC` exceed five AND touch core behavior (REQ may be stale; confirm before proceeding).
+
+#### 3.3 Trace — Explore code and write `<spec_output_dir>/.trace/<feature>.md`
+
+The trace file is the sole machine-readable contract delivered to 3.5. Exploration and writing form a single unit.
+
+**Exploration checklist — execution order** (all mcp calls carry `repo: "<repo-id>"`):
+
+| Step | Action | Tool |
+|---|---|---|
+| 1 | Survey candidate symbols for each anchor from 3.1 | `mcp__gitnexus__query` / `context` |
+| 2 | Full call chain (callers / callees, up and down) | `mcp__gitnexus__impact` |
+| 3 | Cross-class graph traversal / reverse-lookup state writers / aggregation | `mcp__gitnexus__cypher` |
+| 4 | Exact literal positioning (settings keys, DAO columns, intent actions, preference `android:key`) | `Grep` |
+| 5 | Final `file:line` verification / zero-hit counter-evidence | `Read` (small window) / `Grep` |
+
+**Exploration dimensions — information coverage** (orthogonal to the checklist; checklist = order, dimensions = what to capture). Apply each to every recall entry:
+
+- **Trigger code** — UI control + event callback (click / long-press / swipe / lifecycle / broadcast receiver) invoking the REQ behavior. Fill Entry's `code` and `resource` layer fields.
+- **End-to-end call chain** — trigger → ViewModel / UseCase → Service / Repository → data source. Fill Entry's `data_flow`; each hop carries `file:line`.
+- **State writes & persistence** — every state mutation (state holders, DAO inserts, preference / DataStore / MMKV puts, file writes). Record key / column names verbatim.
+- **Side effects / cross-boundary** — broadcasts, bound services, notifications, App Widget IPC, content providers, accessibility events.
+- **Manifest declarations / build flags** — activity / service / receiver registration, intent filters, permissions, foreground service types, build flavor / `buildConfig` gates. Fill Entry's `manifest` field — `N/A: <reason>` if none.
+- **Deviations from `REQ_DESC`** — every gap (default values, copy strings, behavior, hidden entries, validation rules). Feeds Principle 7.
+- **Application scope / boundary · Exhaustive entry enumeration** — ALL UI paths touching this feature / state, beyond REQ text. For state keys: reverse-lookup writers + lift to UI hosts. For readers: enumerate consumers + non-consumers. One field block per entry; omitted here = scenario omitted in spec.
+- **Consumer list & non-consumers** — who reads this state, plus which UI surfaces explicitly do NOT. Non-consumer claims use the structured field block (`claim` / `closure_layers` / `tools` / `zero_hits`).
+
+**Trace file template** (write to `<spec_output_dir>/.trace/<feature>.md`):
+
+```markdown
+# Code trace · <feature>
+
+## Status
+status: ok | no_recall | error
+repo-id: <repo-id>
+backend: gitnexus
+
+## Recalled entry points (Path 1 + Path 2 union, deduplicated)
+- Entry 1: <UI path / page name> — file:line — recalled by: path 1 | path 2 | both
+- ...
+
+## Entry · <name>
+- claim: <user-observable behavior in one sentence>
+- layers:
+  - code:     <file:line>                  # required; hit or `N/A: <reason>`
+  - resource: <file:line> | N/A: <reason>  # layout / menu / drawable / values / xml-preferences / navigation
+  - manifest: <file:line> | N/A: <reason>  # AndroidManifest entry / build.gradle flag
+- interaction: <state writes, persistence keys (verbatim), in-memory mutations>
+- data_flow:   <trigger → ViewModel / Service / Repo → data source, each hop with file:line>
+
+## Entry · <name 2> ... Entry · <name N>
+(each entry repeats the claim / layers / interaction / data_flow field block)
+
+## Implicit triggers (non-UI state changes that activate this feature)
+- Trigger: <track-change / Pro status change / permission change / foreground-background switch / network change / lyrics document change / current track is null> — <file:line> — behavior: <one sentence>
+- (write "None" if no implicit trigger applies)
+
+## Core business entities (data model / persistence key / state machine)
+- Entity X: <file:line + field list + semantics>
+- For dependent REQs: <dependency-key-name> sourced from feature `<depended-feature>` at file:line
+- ...
+
+## Cross-entry shared declarations
+- <AndroidManifest.xml / build.gradle entries with file:line, shared across multiple entries>
+- ... (write "None" explicitly if no cross-entry declaration applies; per-entry manifest facts live in each Entry's `manifest` layer field)
+
+## Deviations from REQ_DESC
+1. <REQ says A; but code at file:line behaves as B>
+2. ...
+(empty → write "None" explicitly to confirm the check was performed)
+
+## Scope / Boundary — Exhaustive entry enumeration
+### Touched entries (all UI paths, not limited to REQ_DESC mentions)
+(each touched entry uses the same `claim` / `layers` / `interaction` / `data_flow` field block as the Entry template above)
+
+### Consumers (who reads this state / data)
+- Consumer: <component name> — file:line
+
+### Non-consumers (boundary counter-examples with evidence)
+- claim:          <e.g. "App widget does not read this key">
+  closure_layers: [code, resource, manifest]
+  tools:          [Grep "<pattern>", mcp__gitnexus__cypher "<...>", Read "<path>"]
+  zero_hits:      <verbatim zero-hit evidence — file globs searched, regex used, hit count>
+
+## Same-source cross-reference (if applicable)
+- This REQ shares behavior with feature `<other-feature>` (e.g. the same setting exposed under multiple settings paths).
+  Both specs are generated independently and reference each other in their deviation sections.
+- (write "None" if not applicable)
+```
+
+#### 3.4 Review — No fabrication, no omission, method-discipline compliant
+
+Run the checks below against the trace from 3.3; every check must pass before proceeding to 3.5.
+
+- **No fabrication** — every declared `file:line` actually exists (sample-verify via `mcp__gitnexus__context` or `Read`); every behavioral claim is source-supported; every boundary claim has tool evidence.
+- **No omission** — every detail in `REQ_DESC` has a counterpart in the trace (Entry / behavior / deviation). If REQ mentions a feature code does not implement, record as deviation, not omission.
+- **Method-discipline compliance** (Multi-layer claim + Replayable fact) — sample-verify random `file:line` anchors via `mcp__gitnexus__context` / `Read` (≥1 line drift → fail); sample-verify every count / ordering phrase against source (unreplayable → fail); every Entry / Touched-entry has all three layer fields filled (hit or `N/A: <reason>`); every Non-consumer claim has all four structured fields (`claim` / `closure_layers` / `tools` / `zero_hits`).
+- **Implicit triggers coverage** — the trace's `Implicit triggers` section is present and explicitly filled (≥1 trigger OR `None`). Absence of the section = fail review.
+- **Trace section presence audit** — every trace MUST contain these H2 sections (with `None` if truly empty; absence = fail): `Status` / `Recalled entry points` / per `Entry` (all 4 fields: `claim` / `layers` / `interaction` / `data_flow`) / `Implicit triggers` / `Core business entities` / `Cross-entry shared declarations` / `Deviations from REQ_DESC` / `Scope / Boundary` / `Same-source cross-reference`.
+
+Any check failing → return to 3.3 (rewrite / supplement / fix). Judge convergence yourself; no external iteration cap. All checks pass → proceed to 3.5.
+
+#### 3.5 Synthesize — Write the final spec
+
+`Read` the trace from 3.3 / 3.4, then synthesize the spec following `## Principles` and the style references under `references/`. Write to `<spec_output_dir>/<feature>-SPEC.md` (overwrite if exists).
+
+**Synthesis discipline**:
+
+- **Implicit triggers coverage** — every entry in the trace's `Implicit triggers` section MUST appear in the spec as an independent scenario OR as a main step within an existing scenario. Listed in trace but absent from spec = scenario omission. (Extends Principle 8 to non-UI triggers.)
+- **Shared-mechanic factoring** — for enumerated-value settings (three-way / four-way / radio-group) accessible from multiple entry points, factor the shared menu interaction across all entries into ONE scenario; give each enum value its OWN runtime-semantics scenario. Do NOT split the mechanical scenario per entry point, and do NOT bundle "user picks X" with "what X does" in the same scenario per value.
+- **Binary-toggle anti-pattern** — a binary on/off switch is ONE trigger; write ONE scenario for the toggle (both directions), with linked-control side-effects as sub-bullets. Write SEPARATE scenarios for each state's runtime rendering (e.g. "when ON, cover rotates" / "when OFF, cover is static"). Do NOT split "turn on" / "turn off" into independent scenes.
+- **Same-source cross-reference** — if the trace's `Same-source cross-reference` section is non-empty, append a short note at the end of the spec referencing the other `<feature>-SPEC.md` (e.g. "This setting also exists under `<other-feature>-SPEC.md` with identical behavior").
+- **REQ-vs-code-string arbitration** — code's user-facing strings (toast / notification / dialog / snackbar / error) that conflict with `REQ_DESC` are **deviation evidence**, NOT authoritative facts. Author spec body per `REQ_DESC` phrasing; record the conflicting string + `file:line` in trace's `Deviations`. Do NOT copy code strings verbatim into the spec.
+
+After writing, proceed to the next REQ block.
+
+### Step 4 — Summary report
+
+Once all REQ blocks are processed (or skipped with warnings), produce a brief report following `references/step4-report-template.md`. The template defines the per-block table format, skipped-block list, and aggregates. Keep the in-session reply within ~40 lines; per-block detail belongs in spec / trace files.
+
+---
+
+## Forbidden
+
+- **No nested LLM-agent skill calls** — no `gitnexus-exploring`, no `gitnexus-debugging`, no `gitnexus-refactoring`, no `gitnexus-impact-analysis`. They override this SKILL's instructions and cause role drift. **Exception**: `gitnexus-cli` is a CLI wrapper (not an LLM agent); using it for index management is allowed.
 - **No modification of the Android project** — `.gradle`, `AndroidManifest.xml`, source files. This skill is read-only.