# SC-Compose Requirements

> Status: Active Release Baseline
> Product: `sc-composer` (library) and `sc-compose` (CLI)
> Document role: Normative release requirements for both crates

This document supersedes the prior high-level placeholder. It is the normative
release requirements baseline for `sc-compose` v1.4.1.

## 1. Intent

This document defines the required behavior of `sc-composer` and `sc-compose`.
It is the design authority for release work. If the implementation diverges
from this document, the implementation is wrong unless the document is
explicitly amended.

## 2. Problem Statement

Teams need one deterministic composition engine for prompt profiles,
instruction templates, and composed prompt output across multiple AI runtimes.
Without a shared implementation, include handling, variable validation,
discovery conventions, and diagnostics drift across callers.

`sc-composer` exists to provide one reusable implementation for:

- prompt and profile file resolution,
- Jinja2-style template rendering,
- include expansion,
- variable declaration and validation,
- deterministic composition output,
- machine-readable diagnostics.

## 3. Product Scope

The product has two deliverables:

- Library crate: `sc-composer`
- CLI binary crate: `sc-compose`

The library is the semantic source of truth. The CLI is a thin interface over
the library.

### 3.1a Phase P Go module distribution

The Phase P generated-Go strategy is governed by
[ADR-0020: Generated Go Binding Strategy](adrs/0020-generated-go-binding-strategy.md),
which is **Accepted**. The native libraries are distributed as the
target-specific release bundles documented by the Go integration guide; a Go
module download alone does not include those native libraries.

The repository MUST publish a generated Go module for the canonical `sc-sha`
hash operations so external consumers can use the shared hash contract without
copying its implementation. The module MUST use the documented submodule path
`github.com/randlee/sc-compose/bindings/sc-sha-go`, generated UniFFI source, and
the matching packaged native artifact for each supported target (Linux/amd64,
macOS/arm64, and Windows/amd64). Release validation MUST cover generated
source drift, native artifact selection, conformance vectors, and an
independent Go consumer. The adapter MUST depend only on `sc-sha` and MUST NOT
add ATM, resolver, filesystem, or duplicate hash logic.

### 3.1 ATM Independence

This repository is intentionally independent from ATM and any other orchestration
runtime.

- No `ATM_HOME` environment variable may be referenced anywhere in this repo.
- No `agent-team-mail-*` crate may appear in any `Cargo.toml` in this repo.
- No ATM spool, socket, mailbox, or runtime path convention may be assumed.
- No `use atm_*::...` or `use agent_team_mail::...` imports may appear in the
  library or CLI crates.
- Any ATM integration belongs in adapters outside this repository rather than
  in `sc-composer` or `sc-compose`.

### 3.2 Boundary Rules

- `sc-composer` must remain runtime-agnostic.
- `sc-composer` must not depend on mailbox formats, daemon lifecycle behavior,
  team coordination state, or runtime-specific home-directory conventions.
- `sc-compose` must be usable as a standalone tool without any external
  orchestration runtime.
- If an external system needs integration-specific behavior, that adaptation
  must live outside this repository rather than inside the core composition
  semantics.

### 3.3 Non-Goals

The initial product explicitly does not provide:

- daemon control or process management,
- mailbox handling or message routing,
- team configuration or ATM runtime management,
- network I/O or remote template fetching,
- ATM-specific file path conventions or runtime lookup behavior.

## 4. Functional Requirements

### FR-1: Template Inputs

- The engine must support plain text and markup source files, including
  `.txt`, `.md`, and `.xml`.
- The engine must support template files ending in `.j2`, including typed
  variants such as `.md.j2`, `.txt.j2`, and `.xml.j2`.
- Any filename ending in `.j2` must be treated as a template.
- Files may begin with YAML frontmatter.
- Frontmatter is optional.

### FR-1a: Frontmatter Schema

Frontmatter must support this schema:

```yaml
pass: 1
required_variables:
  - variable_name
variables:
  variable_name:
    required: true
defaults:
  variable_name: value
input_defaults:
  variable_name: fallback
metadata:
  key: value
json_escape_mode: auto
```

Schema rules:

- `required_variables` is optional.
- `pass` is optional and identifies an explicit pass number for stacked
  frontmatter blocks.
- `defaults` is optional.
- `input_defaults` is accepted as an alias for `defaults` in frontmatter.
- For compatibility with existing template metadata, a frontmatter
  `variables` map with `{ required: true }` declarations is accepted as an
  equivalent spelling of `required_variables`.
- `metadata` is optional.
- `json_escape_mode` is optional for JSON templates and accepts only `auto` or
  `legacy`. `auto` is the default; `legacy` is an explicit compatibility mode
  for manually quoted string placeholders and emits a migration warning.
- The recognized top-level frontmatter keys are `pass`,
  `required_variables`, `variables`, `defaults`, `input_defaults`,
  `metadata`, and `json_escape_mode`. When scanning stacked frontmatter, a later block containing an
  unrecognized top-level key is treated as template body content.
- If a frontmatter block exists and a field is omitted, it defaults to:
  - `required_variables: []`
  - `defaults: {}`
  - `metadata: {}`
- If no frontmatter block exists at all, the file is treated as having no
  declarations and no defaults.
- `required_variables` values must be unique variable names.
- `defaults` supplies optional values that become part of the render context
  unless overridden by environment-derived or explicit input values.
- If both `defaults` and `input_defaults` appear in the same frontmatter
  block, `input_defaults` wins for overlapping keys and validation emits a
  `WARN_VAL_CONFLICTING_DEFAULT_SECTIONS` warning diagnostic.
- `metadata` is descriptive only. It must not directly change render semantics
  unless a future requirement explicitly assigns meaning to a metadata key.

### FR-1b: Value Types

### FR-1b-json: JSON interpolation contract

- JSON templates use complete-value `auto` interpolation by default. Bare
  placeholders own their JSON quoting and preserve scalar, object, array, and
  null types.
- An explicit `legacy` mode safely escapes string contents without adding
  surrounding quotes already present in manually quoted source.
- CLI mode selection takes precedence over root frontmatter, followed by the
  default `auto` mode.
- `validate` and `validate --lint` emit the migration-directed warning for
  legacy mode or quoted placeholders detected in JSON context:
  `Template uses legacy JSON escape mode. Migrate to bare placeholders (auto
  mode) to avoid double-quoting issues. See docs/migration/json-escape-mode.md`
- A JSON render must not emit output until the complete body parses
  successfully.
- The parser gate applies to ordinary `render` as well as `render --check-render`
  and runs before stdout, file, dry-run preview, or JSON-envelope emission.
- `validate` remains static-only and must report that state explicitly. The
  `validate --check-render` variant renders in memory with the supplied exact
  context, reports the checked-render state, and emits no body or file.
- A malformed rendered JSON body must fail closed with the stable
  `ERR_RENDER_JSON_MALFORMED` diagnostic. The diagnostic includes template,
  line, column, and byte offset, but never echoes rendered values.
- Source lint uses the canonical `ERR_JSON_MODE_CONTRACT` diagnostic for an
  auto-mode quoted scalar placeholder. Ambiguous quoted expressions use
  `WARN_JSON_QUOTED_PLACEHOLDER` as a conservative finding instead of being
  silently treated as safe. The existing
  `WARN_JSON_LEGACY_ESCAPE_MODE` migration warning remains emitted by static
  validation for legacy mode or detected quoted placeholders.

The render-context value model accepts any finite JSON/YAML-compatible tree
that the existing `serde_json::Value` and Minijinja context can represent.

The six Phase O.4 repository assignment templates are explicit `auto`-mode
consumers of this contract. Their scalar interpolation slots and scalar loop
elements are bare; `carry_forward_findings_json` is the only reviewed raw-JSON
fragment and must contain a validated JSON array. The O.4 semantic fixture
corpus is the acceptance evidence for quotes, backslashes, Unicode, newlines,
empty and optional values, arrays, objects, null branches, and injection-safe
control characters. The migration matrix and legacy exception are maintained
in `docs/migration/json-escape-mode.md`.

The Phase O.5 release gate extends this contract across consumer repositories:

- every release-candidate campaign reads a source-of-truth inventory of
  repository roots and pinned commits, verifies each commit before scanning,
  and reports the actual JSON-template count and every path;
- an unavailable or unpinned root blocks an unconditional release claim;
- a successful JSON render is a valid campaign PASS only after the complete
  emitted body is parsed as one JSON document; parser failure, partial output,
  timeout, or success-status/body mismatch is fail-closed evidence;
- the original 1.4.0 quoted-placeholder shape remains a permanent negative
  fixture: auto mode rejects it before emission, while explicit legacy mode
  produces one safely escaped string and one deprecation diagnostic;
- external findings are owned by the external repository and require a
  separately merged migration/fix before the release gate can become green.

- Variables used by template rendering must be one of:
  - string
  - number
  - boolean
  - null
  - an object/map with string keys, recursively containing supported values
  - a sequence recursively containing supported values, including arrays,
    objects, scalars, `null`, and jagged shapes
- The top-level `--var-file` document remains a JSON/YAML object and YAML map
  keys remain strings; these ingress boundaries are independent of nesting
  depth.
- `metadata` may contain arbitrary YAML values because it is descriptive only
  and does not participate in rendering semantics.

HTML-Report follow-on design track:

- FR-12 through FR-15 are implemented by Phase HTML-Report.
- The remaining design exploration in
  [docs/html-sprint-report-plan.md](html-sprint-report-plan.md) is limited to
  H5-and-later work such as multi-panel HTML/XHTML composition, wrapper-level
  output viewing behavior, and possible post-render-hook design that stays
  outside the core `sc-compose` contract unless explicitly accepted later.

### FR-1c: File Extension and Discovery Conventions

- Profile and prompt assets must support both plain files and template files.
- Within a candidate directory, resolver probe order for agent and command files
  must be:
  1. `<name>.md.j2`
  2. `<name>.md`
  3. `<name>.j2`
- Skill probe order must be:
  1. `<name>/SKILL.md.j2`
  2. `<name>/SKILL.md`
  3. `<name>/SKILL.j2`
- CLI `render` and `validate` must accept explicit template paths anywhere
  under the configured root, including nested skill templates.

### FR-1d: Template Pack Layout

- Bundled examples and user templates use different on-disk layouts.
- Bundled examples are stored on disk as flat `*.j2` files directly under the
  examples root.
- Example names are derived from the template filename by removing the trailing
  `.j2` suffix and then one remaining source extension when present.
  Examples:
  - `hello.md.j2` -> `hello`
  - `service-config.yaml.j2` -> `service-config`
- Derived bundled example names must be unique. If two flat example files
  normalize to the same name, the examples root is invalid until the collision
  is removed.
- User templates are stored as one subdirectory per template under the user
  templates root.
- A user template directory name is the template name.
- A user template directory may contain one or more files, including one or
  more `.j2` templates and supporting assets.
- `template.json` is optional for user template directories. If present, it is
  user-facing metadata and may contain only:
  - `description`
  - `version`
  - `input_defaults`
- `input_defaults` may provide default render inputs using supported
  render-context value types.
- `template.json` must not introduce alternate render semantics, hook
  execution, or manifest-owned entrypoint selection in the initial release.
- The CLI treats each normalized bundled example entry as a single-template
  example pack even though the on-disk layout is a flat file.
- Named render from `sc-compose examples <name>` resolves the matching flat
  example-pack file under the examples root.
- Named render from `sc-compose templates <name>` is defined only when the
  template directory contains exactly one root-level `*.j2` file.
- Template directories with zero or multiple root-level `*.j2` files remain
  listable and addable, but they are not implicitly renderable by name in the
  initial release.

### FR-2: Variable Resolution and Precedence

- Final render context precedence must be:
  1. explicit input variables,
  2. environment-derived variables,
  3. built-in render-context variables,
  4. user-template `input_defaults`,
  5. frontmatter defaults.
- Frontmatter-declared `required_variables` must be evaluated after the merge.
- Variables present only in `defaults` are optional by default.
- A variable may appear in both `required_variables` and `defaults`; in that
  case the default value satisfies the requirement unless overridden.
- An empty sequence value such as `[]` is valid input and satisfies a required
  variable when provided explicitly or by defaults.
- `validate` and `render --dry-run` must emit an informational diagnostic when
  a referenced or required variable is satisfied by a default value rather than
  explicit caller input.
- Explicit CLI `--var key=value` inputs are always strings.
- This string-only behavior is intentional: CLI text inputs are not coerced
  based on their spelling. Callers that need numeric, boolean, null, object,
  or sequence values must use `--var-file` or template-owned defaults.
- Variables loaded through `--var-file` may be any supported render-context
  value type.
- Variables loaded through `--env-prefix` are always strings.
- After the final context merge, every referenced variable path must either
  have a value binding or be handled by the unbound-variable policy described
  in FR-2a. A missing binding is distinct from an undeclared token and from an
  extra caller-provided variable.
- `ComposePolicy.unbound_variable_policy` controls referenced-but-unbound
  paths with `error`, `warn`, or `ignore` severity. When unset, it inherits
  `unknown_variable_policy` for compatibility; an explicit value keeps the
  two policy axes independent.
- If frontmatter is absent:
  - the engine must discover referenced variables from the template and include
    graph,
  - `validate` must emit a generated-frontmatter recommendation,
  - diagnostics must include a direct fix command:
    `sc-compose frontmatter-init <file>.j2`.

### FR-2c: Built-In Render-Context Variables

- Every render context must inject these built-in variables when the caller
  does not supply them:
  - `TEMPLATE_NAME`
  - `HOSTNAME`
  - `USERNAME`
  - `RENDER_DATE`
  - `RENDER_TIMESTAMP`
- Built-ins sit below explicit caller inputs and environment-derived values,
  and above template-owned defaults.
- `TEMPLATE_NAME` must reflect the resolved template filename actually rendered,
  not a caller alias.
- Caller-provided values always win:
  - explicit input values override built-ins,
  - environment-derived values override built-ins,
  - template-owned defaults do not override built-ins.

### FR-2a: Tokens Not Declared in Frontmatter

Referenced tokens that are not declared in frontmatter must follow these rules:

- Default behavior:
  - they remain preserved in rendered output,
  - they do not become implicitly required variables,
  - they produce diagnostics in both `render` and `validate`.
- Strict behavior:
  - validation fails,
  - rendering fails,
  - diagnostics identify the undeclared referenced tokens.

This behavior is distinct from missing required variables. A token that is
undeclared is not automatically treated as required unless it is explicitly
listed in `required_variables`.

Referenced-but-unbound tokens are a separate axis from undeclared tokens:

- A referenced token with no binding after the final context/default merge
  emits `ERR_VAL_UNBOUND_VARIABLE` according to
  `unbound_variable_policy`.
- A referenced token may be declared in frontmatter and still be unbound; the
  unbound-variable policy applies independently of `strict_undeclared_variables`.
- A referenced token may be undeclared but bound by caller input; the strict
  undeclared-token policy applies independently and the value is not reported
  as unbound.
- Loop locals, `{% set %}` locals, built-in render-context variables, and
  nested paths satisfied by a merged object value count as bindings.

### FR-2b: Missing and Extra Variables

- Missing frontmatter-declared required variables must fail rendering.
- Undefined-variable render failures and undeclared-token diagnostics must use
  distinct stable diagnostic codes.
- Missing-variable diagnostics must include:
  - the full set of missing variable names,
  - the file in which each variable became required,
  - line and column when available,
  - the include chain when applicable.
- Extra input variables not declared by the template or frontmatter must be
  policy-controlled with `error`, `warn`, or `ignore`.

### FR-3: Include Expansion

- The engine must support inline include directives in the form `@<path>`.
- Include resolution order must be:
  1. path relative to the containing file,
  2. path relative to the configured root.
- Nested includes must support:
  - cycle detection,
  - bounded maximum depth,
  - deterministic expansion order.
- Included templates must be evaluated under the same context and validation
  policy as their parent template.
- Include expansion must be applied consistently whether rendering to stdout or
  to a file.
- Include failures must produce actionable diagnostics with include-chain
  context.

### FR-3a: Frontmatter Across Includes

- A file's own frontmatter applies to that file.
- Required-variable declarations discovered from included files participate in
  validation of the overall composition result.
- Defaults declared in included files participate in context construction unless
  overridden by parent-file defaults, environment-derived variables, or
  explicit input variables.
- If multiple files declare a default for the same variable, precedence must be:
  1. explicit input variables,
  2. environment-derived variables,
  3. including file defaults,
  4. included file defaults discovered deeper in the include graph.
- `metadata` from included files must be preserved in trace data only if the
  library exposes include metadata in a future API. Metadata must not affect
  current render semantics.

### FR-4: Safety Constraints

- File reads must be confined to a configured root by default.
- Path traversal outside the allowed root set must fail.
- Callers may optionally provide additional allowed roots.
- Template rendering must not execute arbitrary host code.

### FR-5: Prompt Resolution Conventions

The resolver must support `file` mode and `profile` mode.

In `file` mode:

- the caller provides an explicit path,
- no precedence search is performed.

In `profile` mode:

- the caller provides a profile kind and name,
- the caller may provide a runtime or omit it,
- the resolver searches runtime-specific and shared locations according to a
  configured path policy.

Runtime-specific directories:

- `.claude/agents/`
- `.claude/commands/`
- `.claude/skills/`
- `.hermes/agents/`
- `.hermes/commands/`
- `.hermes/skills/`
- `.codex/agents/`
- `.codex/commands/`
- `.codex/skills/`
- `.gemini/agents/`
- `.gemini/commands/`
- `.gemini/skills/`
- `.opencode/agents/`
- `.opencode/commands/`
- `.opencode/skills/`

Shared directories:

- `.agents/agents/`
- `.agents/commands/`
- `.agents/skills/`

Default runtime search order for agents:

- `claude`: `.claude/agents/<name>` -> `.agents/agents/<name>`
- `hermes`: `.hermes/agents/<name>` -> `.agents/agents/<name>` -> `.claude/agents/<name>`
- `codex`: `.codex/agents/<name>` -> `.agents/agents/<name>` -> `.claude/agents/<name>`
- `gemini`: `.gemini/agents/<name>` -> `.agents/agents/<name>` -> `.claude/agents/<name>`
- `opencode`: `.opencode/agents/<name>` -> `.agents/agents/<name>` -> `.claude/agents/<name>`

Default runtime search order for commands:

- `claude`: `.claude/commands/<name>` -> `.agents/commands/<name>`
- `hermes`: `.hermes/commands/<name>` -> `.agents/commands/<name>` -> `.claude/commands/<name>`
- `codex`: `.codex/commands/<name>` -> `.agents/commands/<name>` -> `.claude/commands/<name>`
- `gemini`: `.gemini/commands/<name>` -> `.agents/commands/<name>` -> `.claude/commands/<name>`
- `opencode`: `.opencode/commands/<name>` -> `.agents/commands/<name>` -> `.claude/commands/<name>`

Default runtime search order for skills:

- `claude`: `.claude/skills/<name>/` -> `.agents/skills/<name>/`
- `hermes`: `.hermes/skills/<name>/` -> `.agents/skills/<name>/` -> `.claude/skills/<name>/`
- `codex`: `.codex/skills/<name>/` -> `.agents/skills/<name>/` -> `.claude/skills/<name>/`
- `gemini`: `.gemini/skills/<name>/` -> `.agents/skills/<name>/` -> `.claude/skills/<name>/`
- `opencode`: `.opencode/skills/<name>/` -> `.agents/skills/<name>/` -> `.claude/skills/<name>/`

Ambiguity contract:

- If a runtime is explicitly provided, only that runtime path chain is used.
- If a runtime is omitted, the resolver must evaluate all configured runtime and
  shared roots.
- If multiple candidates match, resolution must fail with an actionable
  ambiguity error requiring an explicit runtime selector.
- If exactly one candidate matches, the resolver may select it without an
  explicit runtime.

There is no flat shared fallback such as `.agents/<name>`. Shared prompts live
only under `.agents/agents/`, `.agents/commands/`, and `.agents/skills/`.

The resolver path policy must be configurable by callers and must not be
hardcoded into downstream integrations.

### FR-6: Composition Pipeline

Final composed output must concatenate blocks in this fixed order:

1. resolved profile body,
2. guidance block,
3. user prompt block.

Each block may be empty. Ordering is never caller-defined.

### FR-7: CLI Surface

`sc-compose` must provide these commands:

- `render`
- `resolve`
- `validate`
- `frontmatter-init`
- `template-init`
- `init`
- `verify`
- `extract`
- `observability-health`
- `examples`
- `templates`
- `reports`
- `help` (see FR-22)

The CLI must support:

- `--mode <profile|file>`
- `--kind <agent|command|skill>`
- `--agent <name>`
- `--agent-type <name>` as an alias for `--agent`
- `--runtime <claude|hermes|codex|gemini|opencode>` as an optional runtime selector
- `--ai <claude|hermes|codex|gemini|opencode>` as an alias for `--runtime`
- `--var key=value` repeatably
- `--var-file <path|->`
- `--env-prefix <PREFIX_>`
- `--strict`
- `--unknown-var-mode <error|warn|ignore>`
  - controls both extra caller-provided variables and referenced-but-unbound
    variables; the CLI maps the selected mode to both policy axes.
- `--root <path>`
- `--file <path>`
- `--output <path>` where applicable
- `--guidance <text>`
- `--guidance-file <path|->`
- `--prompt <text>`
- `--prompt-file <path|->`
- `--json`
- `--dry-run`
- `--force` where applicable
- `--pass N` repeatably where applicable
- `--against <path>` where applicable
- `--quiet` where applicable
- `--builtin-var KEY=VALUE` repeatably where applicable

Command behavior:

- `render`
  - renders one resolved template or profile,
  - writes to stdout by default,
  - may write to a file when requested,
  - must honor validation and strictness policy,
  - accepts optional guidance and user prompt blocks.
- `resolve`
  - is defined for `profile` mode,
  - prints the selected profile path,
  - reports attempted search paths,
  - fails in `file` mode.
- `validate`
  - performs full include expansion and variable analysis,
  - does not write output files,
  - exits non-zero on validation failure.
- `frontmatter-init`
  - discovers referenced variables,
  - prepends minimal frontmatter,
  - fails if frontmatter already exists unless `--force` is provided.
- `template-init`
  - converts a concrete file into a templated file using one or more pass
    groups declared with `--pass N`,
  - accepts `--var key=value` replacements within each pass group,
  - accepts `--force` to overwrite an existing frontmatter/template header,
  - supports `--dry-run` without writing the rewritten file,
  - exits with code `3` when declared literal values are not found in the
    source file because that outcome is a usage/configuration failure rather
    than a successful drift result.
- `init`
  - creates `.prompts/`,
  - ensures `.prompts/` is ignored by Git,
  - scans repository templates,
  - validates discovered templates,
  - fails if invalid templates are found,
  - prints recommendations for missing or weak frontmatter.
- `observability-health`
  - reads the current CLI logger health state without mutating composition or
    log configuration,
  - prints a human-readable health summary by default,
  - emits the documented JSON schema when `--json` is provided.
- `examples`
  - supports:
    - `examples list`
    - `examples <name>` for implicit named render
  - resolves example packs from the bundled examples root,
  - uses the same render flags and output semantics as `render` for implicit
    named render.
- `templates`
  - supports:
    - `templates list`
    - `templates add <src> [name]`
    - `templates <name>` for implicit named render
  - resolves template packs from the user templates root,
  - uses the same render flags and output semantics as `render` for implicit
    named render,
  - allows `add` from either a single file or a directory source,
  - stores a file source as `<user-template-root>/<pack-name>/<original-file>`,
  - stores a directory source as `<user-template-root>/<pack-name>/...`.
- `reports`
  - supports:
    - `reports init`
    - `reports smoke`
    - `reports finalize`
    - `reports render-spec`
    - `reports index`
    - `reports verify`
    - `reports publish-manifest`
  - owns the shared reporting runtime surface rather than repo-specific
    producer command bodies,
  - keeps publish upload and browser-open behavior outside the command family.
- `verify`
  - compares a deployed file against the rendered output of `--against
    <template>`,
  - supports pass-scoped `--pass N` groups with per-pass `--var` and
    `--var-file` inputs when `--all` is used,
  - accepts `--builtin-var KEY=VALUE` for deterministic builtin overrides,
  - accepts `--quiet` to suppress diff body output while preserving exit
    status,
  - exits `0` when clean, `1` when drift is detected, and `2` or `3` for
    genuine validation/render or usage/configuration failures.

`--dry-run` behavior:

- For file-writing render operations, `--dry-run` must report:
  - resolved template path,
  - resolved output path,
  - whether content would change,
  - validation and render diagnostics.
- For `frontmatter-init`, `--dry-run` must print the exact frontmatter that
  would be written.
- For `init`, `--dry-run` must print planned filesystem changes, validation
  results, and recommendations without modifying the workspace.

Guidance and prompt input rules:

- `--guidance` and `--guidance-file` are mutually exclusive.
- `--prompt` and `--prompt-file` are mutually exclusive.
- `--guidance-file -` reads guidance content from stdin.
- `--prompt-file -` reads prompt content from stdin.
- If both guidance and prompt are omitted, only the resolved profile body is
  composed.
- The CLI must reject attempts to read both guidance and prompt from the same
  stdin stream in a single invocation.
- CLI-only aliases such as `--agent-type` and `--ai` must be resolved before
  library request construction. The library API does not expose alias concepts.

Default output path policy:

- File mode removes the trailing `.j2` suffix from the template filename.
- Profile mode writes to `.prompts/<name>-<ulid>.md` unless `--output` is
  supplied.

Pack root policy:

- `examples` resolves example packs from:
  1. `SC_COMPOSE_DATA_DIR/examples`
  2. install-relative `../share/sc-compose/examples/`
- `templates` resolves template packs from:
  1. `SC_COMPOSE_TEMPLATE_DIR`
  2. the platform user-data directory joined with `sc-compose/templates/`
- `templates add` must fail if the destination pack name already exists.
- `examples` is read-only. It must not mutate the bundled examples root.

### FR-7a: Variable File Rules

- `--var-file` accepts a JSON or YAML object.
- Variable-file keys must be strings.
- Variable-file values must be supported render-context value types.
- Object/map values with string keys are valid per FR-12.
- Sequence values in variable files may contain scalars, objects, arrays, and
  any finite combination of those values at any nesting depth.
- Historical H2 note (2026-07-29): [ADR-E1](architecture.md#61-adr-e1-recursive-structured-input-contract-2026-07-29)
  supersedes this restriction; the current phase index names the
  recursive-input implementation Sprint E.1 to avoid colliding with completed
  Phase D identifiers.
- Arrays of objects are valid per FR-13 when the array is the variable value
  itself.

### FR-7b: Exit Codes

CLI exit codes must be:

- `0` for success
- `1` reserved exclusively for `verify` when drift is detected after a
  successful comparison run
- `2` for validation or render failure
- `3` for usage, configuration, or contract error

All other commands, including `template-init`, continue to use only `0`, `2`,
and `3`.

### FR-7c: Template Whitespace Control

The template engine must enable `trim_blocks` and `lstrip_blocks` by default.
Authors may opt out for a specific block with the standard Jinja `+` modifier.

### FR-8: Determinism and Diagnostics

- The same logical inputs must produce byte-identical output.
- Diagnostics must include:
  - stable diagnostic code,
  - human-readable message,
  - source file path,
  - line and column when available,
  - include stack when applicable,
  - severity.
- JSON diagnostics must use a stable, versioned schema suitable for machine
  consumers.
- Checked rendering must expose a state-shaped result with the states
  `static_only`, `contract_invalid`, `context_required`, `render_invalid`, and
  `render_checked`. Only `render_checked` authorizes a caller to send or cache
  the exact checked output.
- `render --json` must place checked-render parser failures in the standard
  `DiagnosticEnvelope`; it must not print a malformed body as a successful
  payload.

### FR-8a: Command JSON and Dry-Run Schemas

CLI `--json` output must use the versioned `DiagnosticEnvelope` as the
canonical transport format:

```json
{
  "schema_version": "1",
  "payload": {},
  "diagnostics": []
}
```

Per-command schemas below describe the shape of the `payload` field within that
envelope.

`render --json`

```json
{
  "schema_version": "1",
  "payload": {
    "output_path": "stdout",
    "bytes_written": 123,
    "template": "path/to/template.md.j2",
    "body": "rendered document text"
  },
  "diagnostics": []
}
```

Schema rules:

- `output_path` is a string and uses `"stdout"` when no file is written.
- `bytes_written` is the actual byte count written to the selected output
  target; when writing to stdout it is the UTF-8 byte length emitted to stdout.
- `template` is the resolved template path as a string.
- `body` is present only for non-dry-run stdout renders and contains the full
  rendered document. It is omitted when `--output <file>` is supplied because
  the file is the source of truth.
- For JSON templates, ordinary render performs the complete-body parser gate
  before producing this payload. On parser failure the payload is `{}` and
  `diagnostics` contains `ERR_RENDER_JSON_MALFORMED`; no body or file is
  emitted. A successful checked JSON render includes:

  ```json
  "render_check": {
    "state": "render_checked",
    "template": "path/to/assignment.json.j2",
    "output_format": "json",
    "json_escape_mode": "auto",
    "checked_context": "caller-defined exact context summary",
    "diagnostics": []
  }
  ```

- `render --check-render` adds the same `render_check` object for text output
  while preserving the existing body/output behavior after a successful gate.

`render --dry-run --json`

```json
{
  "schema_version": "1",
  "payload": {
    "would_write": ".prompts/example-01HXYZ.md",
    "would_change": true,
    "template": "path/to/template.md.j2",
    "rendered_preview": "preview text"
  },
  "diagnostics": []
}
```

Schema rules:

- `would_write` is the derived output target as a string.
- `would_change` records whether the dry-run output differs from the current
  file content at the derived output path; missing output files count as
  `true`.
- `rendered_preview` is a preview string.

`template-init --json`

```json
{
  "schema_version": "1",
  "payload": {
    "template_path": "path/to/template.md",
    "template_added": true,
    "would_change": true,
    "vars": ["task"]
  },
  "diagnostics": []
}
```

Schema rules:

- `template_path` is the rewritten template path as a string.
- `template_added` is `true` when the command wrote a changed template to disk.
- `would_change` records whether the generated template differed from the
  original file content.
- `vars` is the ordered list of discovered variable names used in the rewrite.

`resolve --json`

```json
{
  "schema_version": "1",
  "payload": {
    "resolved_path": ".claude/agents/example.md.j2",
    "search_trace": [
      ".claude/agents/example.md.j2",
      ".agents/agents/example.md.j2"
    ],
    "found": true
  },
  "diagnostics": []
}
```

`validate --json`

```json
{
  "schema_version": "1",
  "payload": {
    "valid": true
  },
  "diagnostics": [
    {
      "severity": "info",
      "code": "INFO_VAL_DEFAULT_USED",
      "message": "variable name not provided, using default: \"world\"",
      "location": "templates/example.md.j2"
    }
  ]
}
```

Schema rules:

- Plain `validate` is static-only and includes
  `"state": "static_only"` alongside `valid`; it does not render.
- `validate --check-render` renders in memory and returns one of the
  checked-render states. It never includes a rendered body or output-file
  field. Only `render_checked` has permission to send or cache the exact
  context-specific result.
- `validate --lint --check-render` combines lint and render diagnostics in the
  same envelope.
- `validate --lint` reports source locations and stable mode-lint codes. An
  auto-mode contract error returns exit code `2`; warning-only legacy or
  ambiguous-expression findings preserve exit code `0`.

### FR-8b: Repository template-contract lint

- `sc-compose lint --target template-contracts --json` uses the same
  library-owned source scanner as `validate --lint` and reports the effective
  mode, template path, source location, diagnostic code, migration
  recommendation, and `context_backed_render` state for every finding.
- The target is allowlisted through `.sc/sc-lint/targets/template-contracts.toml`
  and remains a local sc-compose capability; it must not duplicate scanner
  logic in Python or shell. Missing roots, unreadable templates, and include
  failures are explicit configuration failures, never green passes.

`init --json`

```json
{
  "schema_version": "1",
  "payload": {
    "workspace_root": "/repo",
    "created_files": [
      ".prompts/",
      ".gitignore"
    ]
  },
  "diagnostics": []
}
```

`observability-health --json`

```json
{
  "schema_version": "1",
  "payload": {
    "logging": {
      "state": "Healthy",
      "dropped_events_total": 0,
      "flush_errors_total": 0,
      "active_log_path": "<log_root>/logs/sc-compose.log.jsonl",
      "sink_statuses": [],
      "last_error": null,
      "query": null
    }
  },
  "diagnostics": []
}
```

Schema rules:

- `payload.logging` is the JSON serialization of
  `sc_observability::LoggingHealthReport`.
- `LoggingHealthReport` is accessed through the `sc-observability` re-export
  surface for logging-only consumers, per DOC-007 and LOG-038.
- `payload.logging.query` is `null` when query/follow health is unavailable and
  otherwise contains a `QueryHealthReport`.
- `active_log_path` is derived from the configured log root and service name
  using the `LOG-008` layout `<log_root>/logs/<service>.log.jsonl`.
- The concrete path is platform-dependent; on Windows it may be drive-qualified.
- `observability-health --json` must not emit console log lines that corrupt
  the JSON envelope written to stdout.

`frontmatter-init --json`

```json
{
  "schema_version": "1",
  "payload": {
    "template_path": "templates/example.md.j2",
    "frontmatter_added": true,
    "would_change": true,
    "vars": [
      "name",
      "role"
    ]
  },
  "diagnostics": []
}
```

`frontmatter-init --dry-run --json`

```json
{
  "schema_version": "1",
  "payload": {
    "action": "frontmatter-init",
    "would_affect": [
      "templates/example.md.j2"
    ],
    "changed": false,
    "would_change": true,
    "skipped": false,
    "vars": [
      "name",
      "role"
    ]
  },
  "diagnostics": []
}
```

`init --dry-run --json`

```json
{
  "schema_version": "1",
  "payload": {
    "action": "init",
    "would_affect": [
      ".prompts/",
      ".gitignore"
    ],
    "changed": false,
    "would_change": true,
    "skipped": false
  },
  "diagnostics": []
}
```

Schema rules:

- `action` names the command.
- `would_affect` lists the filesystem paths or logical targets that would
  change.
- `changed` remains `false` for dry-run operations because no write occurs.
- `would_change` records whether the command would modify its target if writes
  were enabled.
- `skipped` is `true` when the command decides no change is needed.

`examples list --json`

```json
{
  "schema_version": "1",
  "payload": {
    "packs": [
      {
        "name": "hello",
        "path": "/path/to/share/sc-compose/examples/hello.md.j2"
      }
    ]
  },
  "diagnostics": []
}
```

`templates list --json`

```json
{
  "schema_version": "1",
  "payload": {
    "packs": [
      {
        "name": "pytest-fixture",
        "path": "/path/to/user-data/sc-compose/templates/pytest-fixture"
      }
    ]
  },
  "diagnostics": []
}
```

`templates add --json`

```json
{
  "schema_version": "1",
  "payload": {
    "name": "pytest-fixture",
    "source": "/path/to/source/pytest-fixture.py.j2",
    "destination": "/path/to/user-data/sc-compose/templates/pytest-fixture",
    "changed": true
  },
  "diagnostics": []
}
```

Named render through `examples <name>` and `templates <name>` must emit the
same command payloads as `render` and `render --dry-run`.

### FR-9: Observability

- `sc-composer` must not depend directly on `sc-observability`.
- `sc-composer` must not depend on `sc-observability-types`.
- `sc-composer` must define host-injectable observability hooks locally without
  coupling the library to a concrete logging runtime.
- The initial release observability scope is limited to structured logging,
  health reporting, and downstream extension through the local observer hook
  model.
- `sc-compose` shall use `sc-observability` as the canonical concrete
  observability binding for CLI execution.
- The current follow-on observability uplift targets `sc-observability`
  `1.2.0`.
- The CLI lifecycle adapter shall prefer `Logger::log(...)` for blocking queue
  admission and may use `Logger::try_log(...)` only where non-blocking
  admission is explicitly required.
- `Logger::emit(...)` remains a deprecated compatibility path only; any
  retained use must carry an explicit compatibility rationale in
  `docs/migration-notes.md`.
- The CLI shutdown path shall adapt to `Logger::shutdown(self) ->
  Logger<Stopped>` while preserving post-shutdown health inspection through the
  stopped logger typestate.
- `sc-composer` must emit composition pipeline events through its local
  observer/sink hook model.
- `sc-compose` must emit command lifecycle events through the same local hook
  model.
- Standalone defaults must keep `sc-compose` sink paths tool-scoped.
- Embedded use must permit host-supplied sink and path configuration.
- If no sink is injected, both crates must remain fully functional with
  observability reduced to a no-op.
- `sc-compose` shall keep direct `sc-observability` logger construction and
  sink registration rather than adding the `sc-observe` facade at the CLI seam.
- `sc-observe` and `sc-observability-otlp` remain out of scope for the initial
  release.

### FR-10: Library Log-Sink Injection

- `sc-composer` shall define its minimal observability hook layer locally in
  `sc_composer::observer`.
- The library hook surface shall remain a local sink/observer abstraction over
  `ObservationEvent` rather than importing observability contracts from
  `sc-observability-types`.
- `Renderer::new()` shall remain a pure renderer constructor with no observer
  dependency.
- `compose()` shall preserve no-op behavior when the caller does not provide an
  observer implementation.
- `compose_with_observer(request, &mut dyn CompositionObserver)` shall remain
  the required end-to-end injection surface for host-provided observability.
- The local observer hook surface shall remain object-safe and `dyn`-compatible
  so consuming applications can provide their own logging extensions without
  depending on CLI-specific code.
- Injected hooks shall receive structured events for the resolve,
  include-expand, validate, and render pipeline stages.
- The local observer/sink contracts shall remain usable by embedded hosts that
  do not use the CLI.

### FR-11: CLI Observability Wiring

- `sc-compose` shall construct the concrete `sc-observability` `Logger` during
  CLI startup and wire it into the `sc-composer` injection point.
- The CLI logger wiring shall register both file and console sinks during
  normal terminal execution.
- The console sink shall be suppressed whenever the active command uses the
  `--json` output mode so machine-readable command output remains clean.
- The CLI shall emit structured command lifecycle events for command start,
  command completion, and command failure.
- The CLI shall expose logger health through a dedicated
  `observability-health` command so operators can inspect sink state,
  dropped-event counts, retained-log maintenance state, and the active log
  path.
- The `observability-health` command shall initialize logger configuration the
  same way as a normal CLI process, query health from that process-local
  logger instance, and must not depend on any daemon or background runtime.
- The CLI logger configuration shall keep logger-managed retained-log
  maintenance enabled through `RetainedLogPolicy::default()` so rotation,
  pruning, and maintenance cadence stay owned by `sc-observability` rather
  than duplicated in `sc-compose`.
- The CLI shall perform graceful logger shutdown on process exit so pending
  events flush before termination.

### FR-16: Known-Template Reverse Extraction (v1.1, Phase G.1)

This versioned requirement establishes the Phase G reverse-extraction
contract. The contract is defined by
[ADR-0011](adrs/0011-reverse-extract-known-template-contract.md).

- Reverse extraction accepts a known template and its rendered output as
  in-memory text; the core library performs no file I/O, CLI parsing, or
  network access for this operation.
- The first supported format is XML, and only a documented reversible XML
  subset is in scope. Extracted values are rendered strings, not reconstructed
  typed values.
- Reports retain structural occurrence paths, source evidence, confidence in
  the closed range `0.0..=1.0`, and structured diagnostics. Repeated variable
  occurrences that cannot be identified unambiguously must produce an
  ambiguity diagnostic rather than silently overwrite a value.
- The initial feature explicitly does not identify unknown templates or
  reconstruct loops, branches, JSON, Markdown, or source value types.
- Invalid requests, malformed XML, unsupported syntax, and ambiguous
  structure remain distinct error categories with stable diagnostic codes.
- A dotted expression (for example `{{ user.name }}`) is object-field access,
  not a literal variable identifier. Extraction only supports the scalar
  (flat) variable subset and has no object/nested-value extraction capability,
  so any dotted expression is unsupported syntax and must be rejected with
  `ERR_EXTRACT_UNSUPPORTED` rather than accepted as a literal variable name
  (Phase G.7).

The CLI adapter exposes the same known-template contract through the
read-only command `sc-compose extract TEMPLATE RENDERED [--format xml|json]`.
It supports repeatable `--include NAME` and `--exclude NAME` filters, uses XML
as the backward-compatible default, and accepts `--json` for the standard
diagnostics envelope. The command must not identify unknown templates, invoke
the renderer, scan directories, or write output files.

This is a from-scratch product capability informed by prior reverse-extraction
research. The committed Rust, Python, and CLI corpus is the regression
evidence for the supported known-template/XML-first contract; the earlier
research harness is not a product interface or runtime dependency.

### Phase-H Extension Planning Boundary

Issue #193 records real customer use cases for JSON, YAML, and TOML rendered
output, XML mixed-content blocks, and narrowly defined non-XML prefixes before
rendered XML. Phase H is deliberately limited to the three file-format
extensions: JSON, YAML, and TOML. The XML mixed-content and dirty-prefix
findings remain outside Phase H and are owned by
[Phase I](phase-I/phase-I-plan.md).
[ADR-0012](adrs/0012-phase-h-reverse-extraction-extension-gates.md) and [the
Phase-H plan](phase-H/phase-H-plan.md) require each in-scope format to receive
explicit semantics, diagnostics, and cross-surface tests before
implementation. H.1 is now accepted: its JSON/YAML/TOML contract, diagnostic
inventory, and shared `match_raw_text` core are the binding Phase-H design.
The Phase-G XML scalar-only contract and its fail-closed malformed-input
behavior remain authoritative for existing XML behavior, while H.2 through
H.8 remain gated on their own implementation, hardening, and closure criteria
before runtime behavior changes are claimed.

The accepted H.1 design also plans the migration of the format-neutral
value-matching logic from the current XML extraction path into one shared
internal raw-text matching core. XML structural traversal and format-specific
provenance remain
owned by XML; delimiter scanning, template-segment parsing, static
prefix/suffix matching, capture boundaries, and adjacent-variable ambiguity
handling are shared operations. JSON, YAML, and TOML must delegate to that
core rather than implement independent text matchers. This is an internal
architecture seam in Phase H; Phase I.2 promotes it to a customer-facing
raw-text feature without changing the shared matcher.

#### Phase-H Boundary and Phase-I Follow-on

Phase H did not expose either mode. Phase I.1 now accepts the customer-facing
cross-format raw-text mode for known templates, including Markdown, and Phase
I.2 owns its implementation. A best-effort/degraded-parse mode that recovers
values from structurally modified or partially corrupt documents remains
future work beyond Phase I and must not be inferred from the raw-text contract.

#### Phase-H Closure Evidence

The in-scope issue #193 extensions are closed by the committed H.2-H.8
implementation, hardening, cross-surface tests, and bounded campaign evidence in
[`docs/phase-H/evidence/h-6-cross-format-campaign.json`](phase-H/evidence/h-6-cross-format-campaign.json).
The H.6 campaign covers JSON, YAML, and TOML with 36/36 expected outcomes,
including malformed and unsupported inputs as intentional boundaries. This is
bounded local evidence from four workers because Agent Runner was unavailable;
it is not evidence of a distributed adversarial-agent campaign. XML
mixed-content extraction and dirty-prefix stripping remain outside Phase H and
are owned by Phase I; template identification remains future-phase work. They
are not silently treated as H.6 failures.

### Phase-I Extension Requirements

Phase I.1 accepts the following follow-on requirements. They remain separate
from the completed Phase-H delivery and are implemented by the numbered Phase-I
sprints.

### FR-17: Customer-Facing Raw-Text Extraction (Phase I.2)

- `ExtractFormat::Raw`, CLI `--format raw`, and Python `format="raw"` shall
  select one known-template, in-memory raw-text matcher.
- Raw mode shall reuse the shared H matcher and generic extraction report;
  it shall not parse structured formats, identify unknown templates, execute
  Jinja, reconstruct loops, or infer source types.
- Raw occurrences shall use `RawPathSegment` byte offsets and one-based
  line/column evidence, with `RawExtractionSource::TextSpan` provenance.
- Include/exclude filters shall retain the existing request semantics and
  filtered variables shall still participate in neighboring capture matching.
- The stable raw diagnostic set is
  `ERR_EXTRACT_INVALID_REQUEST`, `ERR_EXTRACT_TEMPLATE_UNSUPPORTED`,
  `ERR_EXTRACT_AMBIGUOUS`, and `WARN_EXTRACT_LOW_CONFIDENCE`.

### FR-18: XML Block and Mixed-Content Extraction (Phase I.3)

- A known XML element with one full-content placeholder may recover rendered
  text and approved child markup using deterministic canonical child
  serialization.
- Multiple placeholders, dynamic names, control-flow reconstruction,
  unmatched/truncated markup, multiple roots, post-root content, and unknown
  template identification remain unsupported.
- XML paths, source evidence, ambiguity handling, limits, CLI JSON, and Python
  reports shall remain consistent with the existing extraction model.

### FR-19: XML Dirty-Prefix Recovery (Phase I.4)

- Rendered XML may contain a leading UTF-8 text/whitespace preamble before one
  XML document. Complete comments and processing instructions in the retained
  prolog are allowed; an XML declaration is retained only when first in that
  prolog.
- Only bytes before the selected root may be removed. The report shall emit
  `WARN_EXTRACT_DIRTY_PREFIX_STRIPPED` with the removed span.
- Unmatched/truncated prefix markup, malformed suffixes, multiple roots,
  second documents, post-root content, and DTDs shall remain rejected.

### FR-20: Jinja Loop-Context Built-ins (Phase I.5)

- Strict token discovery shall treat `loop`, `loop.index`, `loop.index0`,
  `loop.revindex`, `loop.revindex0`, `loop.first`, `loop.last`,
  `loop.length`, `loop.depth`, `loop.depth0`, and `loop.cycle(...)` as
  implicit only inside an active `for` scope.
- Nested scopes shall be independent. A `loop` reference outside a `for` and
  arbitrary dotted names shall remain subject to normal undeclared-token
  policy.

### FR-21: YAML Merge-Key Var-File Safety (Phase I.6)

- YAML merge keys (`<<`) in JSON/YAML var-files shall fail closed with
  `ERR_CONFIG_VARFILE` before tagged-value unwrapping; the diagnostic shall
  identify the source line and column of the unsupported construct.
- The implementation shall not partially expand merge keys or silently lose
  inherited fields. The diagnostic shall direct callers to expand the mapping
  explicitly, which is the portable recovery.
- Valid JSON/YAML objects and existing duplicate-key, non-string-key, and
  value-shape policies shall remain unchanged.

### FR-22: CLI Conceptual Help Manuals

- The CLI shall provide a `sc-compose help [topic]` command distinct from
  clap-generated `--help`. `sc-compose help` with no argument shall print an
  index of available topics; `sc-compose help --list` shall print the same
  index in a stable, scriptable form.
- Each topic shall be a static, versioned manual page shipped inside the
  binary (no filesystem lookup, no network access) covering one CLI feature
  area: at minimum `render`, `resolve`, `validate`, `verify`, `extract`,
  `template-init`, `frontmatter-init`, `init`, `examples`, `templates`,
  `reports`, `observability-health`, and `exit-codes`. The `exit-codes` topic
  shall document the FR-7b contract (`0`/`1`/`2`/`3`) in full, since that
  contract is otherwise only discoverable by reading `docs/requirements.md`
  in the repository.
- Topic content shall be authored as one Markdown file per topic under
  `crates/sc-compose/docs/manual/` (e.g.
  `crates/sc-compose/docs/manual/render.md`), each embedded into the
  binary at compile time via a single canonical registry (one ordered
  `(topic_name, content)` array), not as hand-written Rust string constants
  and not as separate per-topic Rust modules. This registry is the single
  seam every topic-content change touches; the dispatch/command-handling
  code that reads it stays flat and topic-count-independent, so it cannot
  grow unbounded as topics are added. A scaffolding change must establish
  this registry mechanism and structure before any per-topic content is
  added, so that concurrent per-topic contributions only ever add a
  Markdown file plus one registry entry, never new Rust modules or
  dispatch branches.
- An unknown topic name shall fail closed with a usage-class exit code (per
  FR-7b, exit `3`) and shall list the valid topic names in its error output.
- The root parser shall disable clap's automatically registered `help`
  subcommand while retaining the generated `--help` flag, then register this
  conceptual `help` command explicitly. This keeps `sc-compose help` as one
  unambiguous route to the manual system and prevents clap's generated
  subcommand from colliding with it.
- Topic names are scoped to the explicit `help` command, not the root command
  namespace. A topic may therefore have the same name as a real command (for
  example, `sc-compose help render` displays the `render` manual while
  `sc-compose render` runs the renderer); topic lookup must not shadow or
  reinterpret any root command.
- `help` and `help --list` shall accept `--json` and use the versioned
  `DiagnosticEnvelope` transport. In text mode, `help --list` is a UTF-8,
  newline-delimited sequence containing exactly one canonical topic name per
  line, in registry order, with no labels or indentation; this explicit
  line-oriented schema is the stable shell-pipeline form. In JSON mode, its
  payload is `{ "topics": ["..."] }` in the standard envelope. A topic JSON
  response uses `{ "topic": "...", "manual": "..." }` as its payload.
- “Versioned” means the Markdown bytes are committed under
  `crates/sc-compose/docs/manual/`,
  embedded into the same released binary as the CLI, and identified by that
  binary's `sc-compose --version`; there is no independently fetched page or
  separate page-version field. A behavior change must update the source page
  and the corresponding CLI release together.
- The `help_topics` module and its ordered registry are exclusively owned by
  `sc-compose`; `sc-composer` and the Python bindings must not define, import,
  or mutate manual-topic metadata.
- Manual content shall be reviewed for drift against the corresponding
  command's actual flags/behavior whenever that command's CLI surface
  changes; this is a documentation-accuracy expectation, not an automated
  gate.
- The root `sc-compose --help` output shall end with a line pointing callers
  to `sc-compose help` for the full manual/topic index, so the manual system
  is discoverable without already knowing it exists.

### Phase HTML-Report Functional Requirements (FR-12 through FR-15)

### FR-12: Map/Object Variable Inputs

Implemented in Phase HTML-Report.

- Callers may pass structured object/map values as template variables.
- Object keys must be strings.
- Valid object fields must be accessible through normal Jinja field access such
  as:
  - `{{ pr.number }}`
  - `{{ pr.url }}`
- Bracket access remains valid when a key is not a valid dotted identifier.
- Structured inputs participate in the same precedence model as existing
  inputs:
  1. explicit input variables,
  2. environment-derived variables,
  3. user-template `input_defaults`,
  4. frontmatter defaults.
- `required_variables` may name nested field paths such as `pr.number` once
  structured inputs are implemented.
- Missing nested required fields must report the full field path, for example
  `pr.number`.
- Malformed object input must fail with stable diagnostics using
  `ERR_VAL_OBJECT_SHAPE`.
- Duplicate keys in JSON and YAML var-files must fail with
  `ERR_CONFIG_PARSE`; var-files do not use silent last-value-wins semantics.
- Nested required-path traversal that encounters a scalar where an object is
  required must fail with `ERR_VAL_SHAPE_MISMATCH`.
- `--var key=value` remains string-only in this phase. Structured input comes
  from `--var-file`, frontmatter defaults, or `template.json` `input_defaults`.
- JSON and YAML var-file documents remain top-level objects. Structured values
  are carried in object fields within that top-level object.

### FR-13: Arrays Of Objects

Implemented in Phase HTML-Report.

- Callers may pass arrays whose members are objects when the array itself is
  the variable value.
- Jinja loops such as `{% for item in list %}` must support field access within
  each array member object.
- Arrays of objects are valid through:
  - `--var-file`,
  - frontmatter defaults,
  - user-template `template.json` `input_defaults`.
- Empty arrays remain valid inputs.
- Arrays of objects may contain nested object fields and arrays, including
  jagged arrays and arrays nested inside object fields.
- Historical H2 note (2026-07-29): [ADR-E1](architecture.md#61-adr-e1-recursive-structured-input-contract-2026-07-29)
  supersedes this restriction; the current phase index names the
  recursive-input implementation Sprint E.1 to avoid colliding with completed
  Phase D identifiers.
- Missing nested fields inside array members must report stable field-path
  diagnostics using `ERR_VAL_MISSING_NESTED_FIELD`.
- `frontmatter-init` must discover variable references inside `for` loop
  bodies. References inside a loop body are attributed to the array variable:
  `{{ sprint.id }}` inside `{% for sprint in sprints %}` means `sprints` is a
  required variable, not `sprint` or `sprint.id`.

### FR-14: HTML Template Output

Implemented in Phase HTML-Report.

- `.html.j2` templates render like other file-mode templates.
- Output path derivation removes only the trailing `.j2` suffix and therefore
  preserves the `.html` extension.
- Rendered HTML is treated as a normal template artifact.
- `AutoEscape::Custom("sc-compose-html")` applies to `.html.j2`, `.htm.j2`,
  `.xml.j2`, and `.xhtml.j2` templates. It automatically escapes markup and
  represents XML-illegal control bytes with the legal replacement-character
  NCR `&#xfffd;`; template authors do not need to opt in.
- Self-contained output, XHTML shape, inline CSS, and browser-viewability are
  template-author responsibilities rather than core-engine enforcement.
- Dry-run, diagnostics, validation, and output-path rules apply to HTML
  templates the same way they apply to other file-mode templates.

#### ADR-style clarification (2026-08-06, FIX-278)

The shipped renderer's filename-aware `AutoEscape::Custom("sc-compose-html")`
policy covers `.html.j2`, `.htm.j2`, `.xml.j2`, and `.xhtml.j2`. The shared
formatter escapes markup and converts XML-illegal C0 control bytes to the legal
replacement-character NCR `&#xfffd;` while leaving tab, LF, and CR intact.
This is automatic behavior and requires no author opt-in. See
[architecture §21.6](architecture.md#216-h4-wrapper-owned-orchestration-pattern)
for the corresponding boundary statement. This clarification records shipped
behavior; it does not change the existing filename-dispatch mechanism.

### FR-15: Bundled HTML Report Example

Implemented in Phase HTML-Report.

- `sc-compose` shall ship a bundled example named `sprint-report-html`.
- The example must demonstrate FR-12, FR-13, and FR-14 together using a
  self-contained HTML sprint status report.
- The H3 example is a single flat file at
  `examples/sprint-report-html.html.j2`. Directory-based example-pack layout is
  deferred to H4 or a later architecture amendment.
- The example must include realistic structured input data showing:
  - report metadata,
  - sprint entries,
  - PR metadata,
  - CI status metadata and actionable links,
  - actionable links such as PR and CI URLs.
- The example must remain renderable through the standard examples command
  surface and var-file flow.
- The example must be a credible showcase for `sc-compose`, not just a
  hand-written HTML file stored in the repo.

### Semantic Report-Spec Contract

`sc-compose` accepts typed TOML semantic report-spec inputs so rendered diagram
formats such as Mermaid become outputs or migration inputs rather than the
long-term source of truth.

Initial implemented report-spec kinds:

- `state_machine`
- `sql_query`

`state_machine` semantic fields:

- `kind`
- `id`
- `title`
- `states`
- `transitions`
- optional per-transition fields:
  - `event`
  - `guard`
  - `actor`
  - `effect`
- optional metadata for ownership, tags, and renderer targets

`sql_query` semantic fields:

- `kind`
- `id`
- `title`
- `purpose`
- `tables_read`
- `tables_written`
- `filters`
- `ordering`
- `cardinality`
- `transactional_assumptions`
- optional metadata for ownership, tags, and renderer targets

Input format rule:

- semantic spec input files use TOML
- each spec file defines `[spec]`
- `sql_query` semantic fields live under `[sql_query]`

Transitional Mermaid rule:

- Mermaid may be emitted as an output renderer during migration
- Mermaid may be accepted as a migration input where repos already store it
- Mermaid is not the long-term semantic source model

Semantic QA direction:

- QA should validate structured semantic fields rather than string-compare only
  the rendered Mermaid output
- renderers may change over time without replacing the typed semantic source
  contract

Extension rule:

- repos may add new semantic report-spec kinds later without rewriting the
  shared artifact catalog or producer contracts

Boundary rules:

- the semantic source contract remains format-agnostic
- shared Phase A reporting boundary rules are centralized under
  `### Report Artifact Contract (Implemented In Sprint B1)`

### Report Artifact Contract (Implemented In Sprint B1)

Sprint B1 implements reporting as a generic artifact contract, not as a
one-off HTML sprint report feature.

Planned contract shape:

- authored docs remain under `docs/`
- report source and catalog inputs live outside `docs/` under a report-specific
  tree such as:
  - `reports/catalog/`
  - `reports/specs/`
  - `reports/templates/` for repo-authored template overrides and other checked-in
    template inputs
- generated evidence lives outside `docs/` under generated-output paths such
  as:
  - `reports/latest/<report-id>/`
  - `reports/archive/<timestamp>/<report-id>/`
- each generated report has one machine-readable metadata sidecar such as
  `reports/latest/<report-id>/report.json`

Planned canonical report catalog fields:

- `id`
- `kind`
- `producer`
- `required`
- `entrypoint`
- `metadata`

Requiredness rule:

- each catalog entry declares `required = true` or `required = false`
- `just reports` verification fails only when a report marked `required = true`
  is missing
- optional reports remain discoverable and publishable without failing shared
  verification

Planned ownership split:

- producer recipes such as `just lint`, `just test`, `just smoke`, and
  repo-specific producer commands own domain data gathering and report
  generation
- `sc-compose` owns rendering semantics where it is used as the report
  renderer
- consumer repos own domain-specific inputs, local producer surfaces, and
  publish destinations

Shared Phase A reporting boundary rule:

- network publishing remains outside the core engine
- browser-open behavior remains outside the core engine
- the artifact contract is intended to support generic lint, test, smoke,
  diagram, and custom reports through one shared metadata and filesystem shape

### Source-Driven Rendering Contract (Implemented In Sprint B3)

Sprint B3 implements a generic source-driven rendering contract for text
assets. This mechanism is not Mermaid-only.

Collection-input contract:

- source collections may be declared by glob or by another stable collection
  definition
- a collection declares which source files participate in one render-many run
- collection discovery is generic across Mermaid, SVG, Markdown, and other
  text-based assets

Metadata-extraction contract:

- comment-prefix metadata is supported
- block-comment metadata is supported
- the raw source body remains available to templates without external
  scripting
- parsed metadata and raw body are exposed together as render inputs
- `sets` metadata is a collection-local grouping field used to tag one source
  file into one or more logical sets for selective rendering, filtering, or
  aggregate grouping
- `sets` has type `Option<Vec<String>>` or equivalent optional string-list
  representation and defaults to `None` when absent

Render-many contract:

- one generated output is produced per discovered source file
- output derivation is deterministic from collection membership plus source
  identity
- aggregate templates and review tooling consume a generated manifest rather
  than ad hoc wrapper state

Generated-manifest contract:

- each source-driven run emits a manifest describing the discovered sources and
  generated outputs
- the manifest is intended for aggregate templates and review tooling
- browser automation and hosted site behavior remain out of scope for the core
  engine

Boundary rules for the source-driven line:

- the mechanism remains generic rather than diagram-format-specific
- shared Phase A reporting boundary rules are centralized under
  `### Phase A Follow-On Reporting Contract (Planning Only)`
- the scaffold owns creation of `reports/latest/smoke/`, and
  report-smoke execution writes into that prepared path rather than creating
  the output directory at runtime

### Latest/Archive Output And Reports Aggregator Contract (Implemented In Sprint B5)

Sprint B5 implements how producers write stable latest outputs, how optional
timestamped archive copies are named, and how `just reports` aggregates and
verifies generated evidence.

Output policy:

- producers overwrite the latest artifact in place at the canonical
  `reports/latest/<report-id>/...` path
- producers may also write timestamped archive copies under
  `reports/archive/<timestamp>/<report-id>/...`
- archive writes are deterministic and file-system-local

Canonical archive timestamp policy:

- timestamps use a filesystem-safe UTC form such as `2026-05-25T22-10-00Z`
- one producer run uses one stable timestamp prefix for all archive outputs
  generated in that run

`just reports` contract:

- verify required evidence exists
- summarize report status across producers
- build or refresh a combined index when the repo defines one
- print or summarize the latest report entrypoints/paths for the current latest
  report set
- optional wrapper-owned helpers may open those paths, but browser opening is
  outside the shared core contract

Verification and failure direction:

- `just reports` is a shared aggregator and verifier, not a producer that
  reruns all evidence collection
- missing required evidence causes report verification to fail
- required-vs-optional report expectations come from each shared report catalog
  entry's `required` field
- the scaffold owns creation of `reports/latest/smoke/`, and
  report-smoke execution writes into that prepared path rather than creating
  the output directory at runtime

Archive ownership note:

- archive directories are file-system-local
- archive directories may be consumer-managed
- archive directories may be gitignored
### Publish-Manifest And CI Handoff Contract

`sc-compose` emits one machine-readable handoff from generated report artifacts
to CI or wrapper-owned publication steps without moving network or hosting
behavior into the core engine.

Implemented publish-manifest contract:

- `sc-compose reports publish-manifest` writes
  `reports/latest/publish-manifest.json`
- the manifest is generated from the current report catalog plus latest
  sidecars and artifact sets, not from hard-coded per-report paths
- optional reports whose latest artifact sets are absent are skipped
- required reports whose latest artifact sets are absent make manifest
  generation fail
- artifact roles remain explicit in the manifest rather than inferred by CI

Manifest fields include:

- generated_at
- reports
- per-report report_id
- per-report kind
- per-report entrypoint
- per-report optional archive_root
- per-file role
- per-file path
- per-file intended publish destination

Identity rule:

- `report_id` must equal the canonical report catalog `id`

Ownership split:

- producers and renderers create artifacts plus manifest metadata
- CI or wrapper tooling performs upload, copy, or publication steps

Boundary rules:

- the artifact contract supports generic lint, test, smoke, diagram, and
  custom reports through one shared metadata and filesystem shape
- publish transport and hosting remain outside `sc-composer` and `sc-compose`
- machine-readable handoff is in scope; network transport is not

### Phase B Cross-Use-Case Proof Examples

Phase B implements one checked-in proof set in this repo so the shared
reporting runtime is exercised by real producer commands instead of docs only.

Implemented proof set:

- this repo ships one checked-in reference report catalog under
  `reports/catalog/reports.toml`
- this repo ships one checked-in source fixture tree under:
  - `reports/inputs/`
  - `reports/specs/`
  - `reports/smoke/`
  - `reports/vars/`
- this repo ships one reference `Justfile` producer surface for:
  - `just lint`
  - `just test`
  - `just smoke`
  - `just state-diagrams`
  - `just sql-diagrams`
  - `just reports`
  - `just reports-verify`
- generic producer-owned HTML outputs can be materialized into the shared
  report sidecar and archive shape with `sc-compose reports finalize`
- the repo proves two distinct consumer families through one shared runtime:
  - `sc-lint` style evidence reports
  - `atm-core` style diagram reports
- `atm-core` and `sc-lint` remain illustrative labels only; the template
  family key is still the runtime discriminator
- producer extension-point typing remains owned by the B1 report artifact
  runtime
- `report-evidence-summary` is a new bundled Phase B proof example
- `sprint-report-html` remains backward-compatible and stays covered by the
  shared proof harness

### Phase A Producer Recipe Contract (Planning Only)

Sprint B2 implements producer recipes as the owners of report generation.
Report generation is not centered on one catch-all `just reports` command.

Standard producer surface:

- `just lint`
- `just test`
- `just smoke`
- repo-specific producer commands such as:
  - `just state-diagrams`
  - `just sql-diagrams`
  - schema, migration, or other repo-local evidence producers

Producer contract:

- each producer command is responsible for generating the report artifacts for
  the report ids it owns
- each producer command writes evidence in the shared report artifact shape
- each producer command updates or emits the catalog/metadata entries for the
  report ids it owns
- adding a repo-specific producer command must not require changing the shared
  report aggregation or discovery contract

Boundary rules for the producer line:

- producer recipes own domain data gathering and invocation order
- `just reports` is reserved for aggregation, verification, combined-index
  refresh, and latest-entrypoint/path reporting
- optional wrapper-owned helpers such as `just reports-open` may exist locally,
  but they are not part of the shared Phase A command contract
- shared Phase A reporting boundary rules are centralized under
  `### Phase A Follow-On Reporting Contract (Planning Only)`
- the report ids owned by a producer are declared through the shared report
  catalog rather than inferred from hard-coded aggregator behavior
- the scaffold owns creation of `reports/latest/smoke/`, and
  report-smoke execution writes into that prepared path rather than creating
  the output directory at runtime

### Template-Family And Panel-Chrome Contract (Implemented In Sprint B4)

Sprint B4 implements shared template families and shared panel chrome so
report UI behavior does not need to be reimplemented per consumer repo.

Initial template families:

- lint/test/smoke evidence reports
- public API, CLI, and ICD style reports
- diagram, state-machine, and SQL-query reports

Override contract:

The authoritative override contract, shared lookup namespace, consumer
activation config, template block boundary, required template variables, and
include deferral are defined in `docs/phase-A/sprint-A5.md`.

Repo-authored versus bundled template rule:

- repo-authored template overrides live under the consumer repo's
  `reports/templates/` tree
- `shared:<family>` resolves to bundled CLI-owned assets and is not a reference
  to the consumer repo's authored `reports/templates/` tree

Shared panel contract:

- stable panel id
- title
- body content
- required copy-text action
- optional copy-JSON action
- optional fragment or open link

Ownership split:

- shared panel chrome owns panel framing and shared actions
- consumer-specific templates own the panel body content for their report
  family or repo-local override

Boundary rules:

- per-panel text copy is mandatory
- per-panel JSON copy is optional but first-class
- panel chrome remains part of shared template behavior rather than wrapper-only
  logic
- shared Phase A reporting boundary rules are centralized under
  `### Phase A Follow-On Reporting Contract (Planning Only)`

## 5. Non-Functional Requirements

- Cross-platform support is required for macOS, Linux, and Windows.
- The product must not rely on shell-specific behavior.
- Single-template `render`, `resolve`, and `validate` operations must be fast
  enough for interactive terminal use on local repositories.
- The public library API must be stable enough for downstream integration and
  semver-governed once released.
- The library and CLI must remain separable: `sc-compose` may depend on
  `sc-composer`, but `sc-composer` must not depend on the CLI crate.
- Observability integration must emit structured events at the resolve,
  include-expand, validate, and render pipeline stages with stable target,
  action, and message conventions.
- Observability health state must be queryable without mutating composition
  behavior so operators and embedded hosts can inspect runtime health safely.
- Process shutdown must flush pending observability output and degrade
  gracefully when sink flushing reports errors.

## 6. Stability Policy

- The `sc-composer` public API is semver-governed.
- Before `1.0`, breaking API changes require a minor version bump.
- After `1.0`, patch releases contain backward-compatible bug fixes only.
- After `1.0`, minor releases contain backward-compatible new features.
- After `1.0`, major releases contain breaking changes.
- Exception: the `1.3.0` change to
  `Renderer::with_delimiters(open, close) -> Result<Self, RenderError>` ships
  under the narrow carve-out documented in
  [ADR-0010](adrs/0010-renderer-delimiter-fallibility-minor-exception.md);
  this exception is limited to that one constructor change and does not weaken
  the general major-version rule.
- [ADR-0009](adrs/0009-phase-d-python-binding-parity-sequencing.md) governs
  Phase D delivery sequencing and Python parity scope; it is intentionally out
  of scope for this Section 6 stability policy.
- `render_template()` is a stable convenience API for one-shot rendering.
- `Renderer` is the primary stable API for repeated rendering and long-lived
  library use.

## 7. Testing Requirements

Required unit coverage includes:

- frontmatter parsing,
- frontmatter omission defaults,
- variable precedence,
- required-variable enforcement,
- undeclared-variable behavior in normal and strict modes,
- unknown-variable policy handling,
- include resolution, cycle detection, and depth limits,
- include-driven defaults and required-variable propagation,
- path confinement,
- resolver precedence.

Required integration coverage includes:

- CLI `render`,
- CLI `resolve`,
- CLI `validate`,
- CLI `frontmatter-init`,
- CLI `init`,
- CLI `observability-health`,
- CLI `examples list`,
- CLI `examples <name>`,
- CLI `templates list`,
- CLI `templates add`,
- CLI `templates <name>`,
- command lifecycle logging,
- resolve/include-expand/validate/render event emission,
- `--dry-run` no-write guarantees,
- JSON diagnostics contract,
- cross-platform path behavior,
- template-pack discovery and add semantics,
- list/array input behavior through frontmatter defaults, `template.json`
  `input_defaults` for user templates, and `--var-file`.

## 8. Out of Scope for the Initial Release

- Remote includes such as `http` or `https`
- Arbitrary plugin execution from templates
- Runtime-specific hooks and event integrations inside the core composition
  engine
- `prepare-hook` and `post-render-hook` execution
- Named render for packs with multiple root-level `*.j2` entry candidates
- Template deletion, update, sync, or remote registry features
- Multi-panel HTML/XHTML report expansion and wrapper-level output viewing
  behavior remain deferred to the follow-on design track in
  [docs/html-sprint-report-plan.md](html-sprint-report-plan.md)