codexspec 0.7.11__tar.gz → 0.7.12__tar.gz

{codexspec-0.7.11 → codexspec-0.7.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codexspec
-Version: 0.7.11
+Version: 0.7.12
 Summary: CodexSpec - A Requirements-First SDD toolkit for Claude Code
 Project-URL: Homepage, https://github.com/Zts0hg/codexspec
 Project-URL: Repository, https://github.com/Zts0hg/codexspec

{codexspec-0.7.11 → codexspec-0.7.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codexspec"
-version = "0.7.11"
+version = "0.7.12"
 description = "CodexSpec - A Requirements-First SDD toolkit for Claude Code"
 readme = "README.md"
 requires-python = ">=3.11"

{codexspec-0.7.11 → codexspec-0.7.12}/src/codexspec/__init__.py

@@ -44,7 +44,7 @@ from .profile import ensure_profile_scaffold, inject_profile_block
 from .translator import SUPPORTED_LANGUAGES, translate
 
 # Version info
-__version__ = "0.7.11"
+__version__ = "0.7.12"
 __author__ = "CodexSpec Team"
 
 # Constitution file path constants

{codexspec-0.7.11 → codexspec-0.7.12}/src/codexspec/profile.py

@@ -4,13 +4,13 @@ Wires a user project's ``.codexspec/profile/`` into the AI context files so that
 knowledge distilled by ``/codexspec:distill`` is consulted in later work.
 
 Store layout: **one record per file** under a per-category directory
-(``constraints/`` ``conventions/`` ``pitfalls/`` ``decisions/``). Because parallel
-feature branches each add differently-named record files, their distilled
-knowledge merges without conflict.
+(``constraints/`` ``conventions/`` ``pitfalls/`` ``decisions/`` ``strategies/``
+``runbooks/``). Because parallel feature branches each add differently-named
+record files, their distilled knowledge merges without conflict.
 
 Two concerns live here:
 
-- ``ensure_profile_scaffold`` — create the four category directories (each kept
+- ``ensure_profile_scaffold`` — create the six category directories (each kept
   by a ``.gitkeep``) so every injected reference resolves, independent of whether
   any knowledge has been distilled yet.
 - ``render_profile_block`` / ``inject_profile_block`` — render a bounded,
@@ -27,7 +27,14 @@ from pathlib import Path
 
 # Ordered: constraints first (highest weight, honored first). Each is a directory
 # holding one record per file.
-PROFILE_CATEGORIES = ("constraints", "conventions", "pitfalls", "decisions")
+PROFILE_CATEGORIES = (
+    "constraints",
+    "conventions",
+    "pitfalls",
+    "decisions",
+    "strategies",
+    "runbooks",
+)
 
 PROFILE_BLOCK_START = "<!-- CODEXSPEC PROFILE START -->"
 PROFILE_BLOCK_END = "<!-- CODEXSPEC PROFILE END -->"
@@ -43,24 +50,33 @@ _PROFILE_BLOCK = "".join(
         "**Project constraints (highest priority — read these FIRST):** before any non-trivial work you MUST ",
         "read every record under `.codexspec/profile/constraints/` — the project's hard prohibitions ",
         "(严禁 / 仅允许). Honor them before anything else.\n\n",
-        "**Project profile — consult on demand when relevant to the task** ",
+        "**Actively recall relevant knowledge before non-trivial work.** Do not wait to stumble on it: ",
+        "scan the record headings and their `scope/when` (and, for strategies, `trigger`) lines across the ",
+        "categories below, and read every record whose condition matches the task you are about to start ",
         "(each directory holds one record per file):\n\n",
         "- `.codexspec/profile/conventions/` — cross-feature conventions / steering; ",
         "read before adopting a pattern, structure, or naming choice.\n",
         "- `.codexspec/profile/pitfalls/` — known traps and their workarounds; ",
         "read before implementing or debugging in an area that may have bitten before.\n",
         "- `.codexspec/profile/decisions/` — past cross-feature / architectural decisions; ",
-        "read before deciding in the same area, to reuse prior rationale rather than re-litigate it.\n\n",
+        "read before deciding in the same area, to reuse prior rationale rather than re-litigate it.\n",
+        "- `.codexspec/profile/strategies/` — metacognitive trigger→action rules (and `scope: self` notes on ",
+        "the agent's own recurring slips); read before choosing an approach or when a fix is not converging.\n",
+        "- `.codexspec/profile/runbooks/` — ordered multi-step procedures with failure recovery; ",
+        "read before carrying out a known multi-step task.\n\n",
         "Read the full record — each carries a `status` of `candidate` or `vetted`; ",
         "weight `candidate` items with appropriate caution. A directory may be empty ",
-        "until `/codexspec:distill` has captured knowledge.\n",
+        "until `/codexspec:distill` has captured knowledge.\n\n",
+        "**Capture knowledge as you go.** When this session produces reusable cross-feature knowledge — even ",
+        "in plain chat or a non-SDD fix — run `/codexspec:distill` near that moment rather than only at ",
+        "wrap-up. It is non-blocking and early-exits when there is nothing new.\n",
         f"{PROFILE_BLOCK_END}\n",
     ]
 )
 
 
 def ensure_profile_scaffold(target_dir: Path) -> Path:
-    """Create ``.codexspec/profile/`` and its four category directories if absent.
+    """Create ``.codexspec/profile/`` and its six category directories if absent.
 
     Each category is a directory of one-record-per-file entries; a ``.gitkeep``
     keeps an empty category tracked so every pointer resolves. Idempotent and
@@ -79,10 +95,13 @@ def ensure_profile_scaffold(target_dir: Path) -> Path:
 def render_profile_block() -> str:
     """Render the bounded managed profile block.
 
-    Identical for CLAUDE.md and AGENTS.md: constraints and the three on-demand
+    Identical for CLAUDE.md and AGENTS.md: constraints and the five on-demand
     categories are all delivered as pointers to their directories — no ``@import``
     anywhere — so the block is channel-neutral and the store can be
-    one-file-per-record directories that merge without conflict.
+    one-file-per-record directories that merge without conflict. The block also
+    directs active recall (scan record ``scope/when``/``trigger`` and read matches
+    before non-trivial work) and near-moment ``distill`` capture; it is a fixed
+    directive whose size is independent of how many records the profile holds.
     """
     return _PROFILE_BLOCK
 

{codexspec-0.7.11 → codexspec-0.7.12}/templates/commands/distill.md

@@ -23,6 +23,8 @@ Converse in the interaction language and author artifacts in the document langua
 `distill` extracts the reusable, cross-feature knowledge produced during work and persists it to the project-level store `.codexspec/profile/`. It runs two ways:
 
 - **Auto (primary)**: embedded in wrap-up commands (`implement-tasks` on completion, `commit-staged`, `pr`), gated by `workflow.auto_distill` in `.codexspec/config.yml` (**default enabled**; disabled only when explicitly set to the literal `false`).
+- **Near-moment (ambient)**: driven by the profile block's "capture knowledge as you go" rule, distill may be invoked **near the moment** reusable cross-feature knowledge is produced — in **any session**, including plain chat or a **non-SDD fix** that never reaches a wrap-up command. This is the primary way knowledge from ad-hoc work is captured at all.
+- **Long-run**: in a long-running `implement-tasks`, distill **along the way** near each knowledge-producing event rather than only at the very end, so mid-task evidence is not lost to context compaction; the end-of-task `auto_distill` still runs as a **backstop**.
 - **Manual (fallback)**: invoked directly on the supplied or most-recent interaction segment.
 
 distill is **non-blocking and non-interactive**: it never prompts, never gates another command, and **early-exits without writing** when the delta contains nothing reusable.
@@ -42,12 +44,16 @@ Apply this boundary test to every candidate: **"Would a single feature's `requir
 
 ## The profile store: `.codexspec/profile/`
 
-Four **category directories**, each holding **one record per file** (`<id>.md`) with **only current-effective** knowledge — dense, with no "retired" section (git history is the ledger). One-file-per-record is deliberate: parallel feature branches each add differently-named files, so distilled knowledge merges without conflict. Create the directory and record file on first write.
+Six **category directories**, each holding **one record per file** (`<id>.md`) with **only current-effective** knowledge — dense, with no "retired" section (git history is the ledger). One-file-per-record is deliberate: parallel feature branches each add differently-named files, so distilled knowledge merges without conflict. Create the directory and record file on first write.
 
 - `constraints/` — negative constraints (`严禁 / 仅允许`). These carry the **highest** weight and MUST be honored first.
 - `conventions/` — positive cross-feature conventions / steering.
 - `pitfalls/` — cross-feature traps and their workarounds.
 - `decisions/` — cross-feature / architectural decisions only (ADR-lite). **Never** single-feature requirement rationale.
+- `strategies/` — metacognitive `trigger → action` rules: when you recognize signal X, switch to approach Y. A **self-model** (knowledge about the agent's own recurring slips in this project) lives here too, marked `scope: self`. A strategy is the layer **above** a pitfall — the transferable "what to do when" generalized across many specific traps.
+- `runbooks/` — ordered multi-step procedures with failure recovery: how to carry out a known multi-step task (e.g. a release), step by step, including what to do when a step fails.
+
+There is **no** `facts/` category — a bare fact with no "therefore do X" is either feature-scoped (leave it in `requirements.md`) or belongs as a `convention`/`constraint` with an evidence anchor.
 
 ### Record format — `claim` and `evidence` physically separated
 
@@ -55,7 +61,7 @@ Every record MUST separate the distilled claim from the evidence it rests on:
 
 - `id` — **type letter + full source-feature id + local sequence**, e.g. `P-2026-0812-14054p-1` or `Con-2026-0812-14054p-1`. It is **both** the record's `### <id>: <title>` heading **and its filename** (`pitfalls/P-2026-0812-14054p-1.md`). The **source-feature id** is the distilling feature's full spec-dir id `{YYYY-MMDD-HHMM}{rr}` (e.g. `2026-0812-14054p`); it is globally unique by the timestamp+random scheme spec directories use, so records distilled on parallel feature branches never collide on id **or filename** (they merge with no conflict). Keep the **full** id (not a short tail) so the record is self-describing: the date supports recency/staleness reading, and the feature id ties the record to its originating change for decision context and scope. When distilling with no feature context, generate a fresh `{YYYY-MMDD-HHMM}{rr}` id now (same convention as create-new-feature). **Never** use a bare sequential id such as `P-001` — those collide across parallel branches.
 - `claim` — one-sentence reusable **summary** (a title line, not the actionable body — for a `pitfall` the usable content lives in the three body parts below, not in this sentence).
-- `type` — `convention` | `constraint` | `pitfall` | `decision` (`constraint` = highest priority).
+- `type` — `convention` | `constraint` | `pitfall` | `decision` | `strategy` | `runbook` (`constraint` = highest priority).
 - `scope/when` — natural-language applicability condition (e.g. "when editing Python code"); omit for global. **No formal syntax.**
 - `evidence.facts` — the concrete observations behind it; **quote the user's original words, do not paraphrase**.
 - `evidence.state` — the context/validity when true (feature / commit / config; still valid?).
@@ -70,6 +76,20 @@ Every record MUST separate the distilled claim from the evidence it rests on:
 
 If you cannot state all three, the pitfall is not yet understood well enough to record. `convention` / `constraint` / `decision` records usually need only `claim` + `evidence`; this three-part body is required specifically for traps.
 
+**Strategy records carry a `trigger → action` body.** A `strategy` MUST, beyond `claim` and `evidence`, spell out two parts:
+
+- `trigger` — the **signature** by which you recognize you are in this situation (e.g. "a substring contract test fails", "a fix is not converging after several attempts"). This is what lets the strategy be recalled by the situation, not by remembering the one incident that produced it.
+- `action` — what to do when the trigger fires.
+
+A **self-model** — a strategy about your *own* recurring slip (e.g. "I keep forgetting to regenerate derived forms") — is a strategy marked `scope: self`; its `trigger` is self-referential but the body is identical.
+
+**Runbook records carry an ordered body.** A `runbook` MUST, beyond `claim` and `evidence`, spell out:
+
+- `steps` — the ordered steps to carry out the task.
+- `failure-recovery` — for the steps that can fail, what to do to recover (the branch that a flat one-line record loses).
+
+If you cannot state these parts, the strategy or runbook is not yet worth recording — the same anti-hollow bar as pitfalls.
+
 > **onboard variant**: `/codexspec:onboard` writes to this same store and format, with one difference — its records are inferred from code, so `evidence.facts` holds a verbatim **code observation** (path + snippet) instead of a user quote, `provenance` marks the onboard scan, and `derivation` is always `inferred`. onboard therefore writes `status: candidate` **at write time** (it never writes `vetted` itself); such a record can still be promoted to `vetted` later once it is outcome-verified and approved in `/distill review` — its `inferred` origin is not a barrier (per the `status` rule above).
 
 This separation is what makes a later error locatable as **misread** (facts wrong) vs **overreach** (claim over-generalized) vs **stale** (state no longer holds).
@@ -103,12 +123,50 @@ Example — a `pitfall` (note the required `root-cause` / `workaround` / `lesson
 - status: candidate
 ```
 
+Example — a `strategy` (note the `trigger` / `action` body), file `strategies/S-2026-0813-1606fz-1.md`:
+
+```markdown
+### S-2026-0813-1606fz-1: When a substring contract test fails, suspect markdown emphasis first
+- claim: A failing substring assertion over a prose template is usually a wrong assertion, not a wrong template.
+- type: strategy
+- scope/when: writing or debugging substring contract tests over `templates/commands/*.md`
+- trigger: a `test_*_template.py` substring assertion fails on a phrase you believe the template contains.
+- action: check whether the template wrote inline `**`/`*`/backticks inside the asserted span before touching the template; re-target the assertion at an emphasis-free span.
+- evidence.facts: "断言 span 里含 `**not**` 导致子串匹配失败"
+- evidence.state: confirmed at feature 2026-0813-1606fz; still valid.
+- provenance: distill @implement-tasks, 2026-08-13, derivation: inferred, confidence: high
+- status: candidate
+```
+
+Example — a `runbook` (note the ordered `steps` + `failure-recovery` body), file `runbooks/R-2026-0813-1143el-1.md`:
+
+```markdown
+### R-2026-0813-1143el-1: Release a new CodexSpec version
+- claim: The end-to-end steps (and failure recovery) to cut a release.
+- type: runbook
+- scope/when: publishing a new version of this repo
+- steps: 1) bump the version manually in `pyproject.toml`, `__version__`, and `uv.lock`; 2) run `publish.sh`; 3) push the tag; 4) commit the marketplace update.
+- failure-recovery: if the `pip-audit` pre-commit hook aborts on a transient SSL error, reset the half-applied bump and re-run with `SKIP=pip-audit`.
+- evidence.facts: "publish.sh 不自动 bump __version__；pip-audit 偶发 SSL 失败中止发布"
+- evidence.state: confirmed at feature 2026-0813-1143el; still valid.
+- provenance: distill @implement-tasks, 2026-08-13, derivation: inferred, confidence: high
+- status: candidate
+```
+
 ## Extraction
 
 Read the interaction segment and extract, per the dimensions above, only **verified** knowledge — prefer facts confirmed by outcomes over speculation; speculation MUST NOT become `vetted`.
 
 Before writing, **read the current profile** (the record files under each category directory) and skip anything already covered; update anything changed via `replace`. **This is how deduplication is done — by judgment, not an algorithm.**
 
+## Debounce across the trigger surface
+
+distill can now fire from several points close together — the near-moment ambient rule, the long-run along-the-way calls, and the wrap-up hooks (`implement-tasks` → `commit-staged` → `pr`) — often over largely the **same** work. To avoid re-distilling and near-duplicate records, apply a lightweight debounce:
+
+- **Session-local boundary.** Keep a **session-local already-distilled boundary** — your own memory, in this conversation's context, of what you have already distilled this session and up to which point of the interaction. This is held **in conversation context**; introduce **no persistent runtime state** (no marker file, no counter on disk).
+- **Delta-only.** On a later trigger, distill only the **substantive new delta** since that boundary. If nothing substantive was produced since, **early-exit** (report "nothing to distill") without deep-reading the whole profile.
+- **Cross-session fallback.** When the boundary is unavailable — a new session, or context was compacted — there is no session memory to lean on, so distill **falls back to reading the profile and skipping covered records** (the judgment dedup above). Worst case is one extra early-exiting scan, never a duplicate.
+
 ## Conflict adjudication
 
 When a new item conflicts with an existing rule, resolve in this order:
@@ -128,12 +186,24 @@ Change the profile **only** through three conceptual operations (you edit the fi
 
 git history is the audit ledger. Do **NOT** keep a retired file or a retired section.
 
+## Consolidation (compress narrow records into general rules)
+
+Growth is not just accumulation: many narrow records on one theme should compress into **one general rule plus its exceptions** (the way experience compacts into judgment). distill performs the **detect-and-mark** half automatically; a human performs the **merge** half in `/distill review`.
+
+- **Mark, don't merge.** When you notice a cluster of narrow records sharing a generalization (e.g. several derived-artifact pitfalls, or several lockstep conventions), **mark** them as **consolidation candidates** by writing a **per-record field** into each member's own file — `consolidation: candidate; cluster: <short-theme-key>` — using the same shared `<short-theme-key>` on every member. This is judgment, not an algorithm. It is **non-destructive**: marking **does not auto-rewrite or delete** any record.
+- **No central index.** The cluster lives only as that shared key across the members' own files — there is **no central index** or manifest file (which would be a merge-conflict magnet and break the conflict-free store). `/distill review` discovers a cluster by scanning for records that share a `cluster:` key.
+- **Cross-category promotion.** A consolidation may cross categories — e.g. **promoting several** `pitfalls` **into one** `strategy` (the transferable "what to do when" above the individual traps). The general record is written in whichever category fits the generalized claim.
+
+The merge itself is confirmed by a human in `/distill review` (below); distill never merges unattended.
+
 ## Vetting candidates (manual, interactive)
 
 Auto-distill writes `candidate` records non-interactively and **never prompts**. Promote them through the **manual review mode** — `/distill review` (or `/distill` with no new segment to distill): list every pending `candidate` compactly (claim + evidence + provenance) and let the user approve inline — "vet all", "vet 1,3", "edit 2", "drop 4". Apply the choices by editing each record's `status` (a `replace`). **The user never hand-edits the profile files.**
 
 The user's approval here **is** the human endorsement half of the `vetted` gate: an approved `candidate` that is already outcome-verified becomes `vetted` **regardless of its original `derivation`** (an `inferred` record is not blocked from vetting). If a candidate has not yet been outcome-verified, approval keeps it `candidate` (or the user may attest the outcome to complete the gate). This is the path by which `inferred` knowledge — including everything `/codexspec:onboard` writes — reaches `vetted` and becomes `evolve`-eligible.
 
+**Consolidation review.** In the same review mode, also surface any **consolidation candidate** clusters (records sharing a `cluster:` key, from the Consolidation section above): show the cluster's members compactly and let the user confirm the merge inline — "merge 1", "merge all", "keep separate". On confirmation, write the single general record (a **general rule plus its exceptions**), `remove` the superseded members, and clear the `cluster:`/`consolidation:` marker from anything that survives so no stale flag lingers. If the user declines, leave every member untouched. distill only ever **marked** the cluster; the merge happens **only** here, on explicit confirmation.
+
 ## Self-check before finishing
 
 A lightweight judgment pass (not an engineered lint) over what you just wrote:

{codexspec-0.7.11 → codexspec-0.7.12}/templates/commands/evolve.md

@@ -31,6 +31,8 @@ Promote only records that are **both**:
 
 Project-specific knowledge **stays** in the profile. Only generally-useful capability is promoted upstream. When nothing qualifies, stop and report — do not force a promotion.
 
+This selection spans **all six** profile categories. `strategies/` (metacognitive `trigger → action` rules) and `runbooks/` (ordered multi-step procedures) are often the **most** promotable material — a vetted, general strategy or runbook compiles cleanly into a reusable skill/command — but they clear the **same** `vetted` gate as every other category; the gate is unchanged.
+
 ## Compiling the draft
 
 Compile the selected sediment into a SKILL.md / command-template draft that conforms to both:

{codexspec-0.7.11 → codexspec-0.7.12}/templates/commands/onboard.md

@@ -30,7 +30,7 @@ Converse in the interaction language and author artifacts in the document langua
 Before scanning:
 
 - If `.codexspec/` is **absent**, the project is not codexspec-initialized. **Stop** and direct the user to run `codexspec init`. Do not scaffold a whole project.
-- If `.codexspec/` is present but the profile store is missing, **ensure the canonical scaffold** — the four category directories `.codexspec/profile/{constraints,conventions,pitfalls,decisions}/` (matching what `codexspec init` produces) — before writing.
+- If `.codexspec/` is present but the profile store is missing, **ensure the canonical scaffold** — the six category directories `.codexspec/profile/{constraints,conventions,pitfalls,decisions,strategies,runbooks}/` (matching what `codexspec init` produces) — before writing.
 - git is **not required**. onboard runs on a plain directory.
 
 ## Codebase Scan
@@ -45,12 +45,12 @@ Scan strategy is **high-signal-first over the whole repository in a single pass*
 
 ## What onboard Extracts — and What It Must NOT
 
-Extraction uses your **flexible judgment over what the code actually shows** — not a fixed checklist of filenames or markers. onboard actively extracts **only two** of the four profile categories:
+Extraction uses your **flexible judgment over what the code actually shows** — not a fixed checklist of filenames or markers. onboard actively extracts **only two** of the six profile categories:
 
 - **`conventions`** (the primary yield) — the code's observable regularities: directory/module structure, naming schemes, import style, the tech stack and toolchain (read from manifests), lint/format/type configuration, test framework and layout, and patterns repeated across the codebase. **Observable architecture / tech-stack facts** are captured here as fact-plus-steering, not as ADR-style decisions.
 - **`constraints`** (narrow, high-risk) — **only** config-level **explicit hard prohibitions**: lint/type rules set to *error* that ban imports or APIs, `do not edit` / generated-file / managed-block markers, and CODEOWNERS / protected-path conventions. Every constraint candidate carries a **precise evidence anchor** (`file:line` or a config snippet). **Absent an explicit prohibition signal, propose no constraint** — silence, never a guess.
 
-onboard **never** extracts `decisions` or `pitfalls`. A documented decision or pitfall is already readable in the repo (redundant to copy); an undocumented one is unreliable to infer from a cold scan (pitfalls are experiential; decision rationale would be fabricated). Those two categories remain `distill`'s channels, where the rationale and lived experience are available.
+onboard **never** extracts `decisions`, `pitfalls`, `strategies`, or `runbooks`. A documented decision or pitfall is already readable in the repo (redundant to copy); an undocumented one is unreliable to infer from a cold scan (pitfalls are experiential; decision rationale would be fabricated). `strategies` (metacognitive trigger→action rules) and `runbooks` (lived multi-step procedures) are likewise experiential — a cold scan cannot reliably infer either. All four remain `distill`'s channels, where the rationale and lived experience are available.
 
 ## Record Format
 
@@ -85,5 +85,5 @@ Report concisely in the interaction language: the records added / updated per ca
 
 - Read-only on code; write-only to `.codexspec/profile/`; no source / test / git / constitution mutation.
 - Standalone: no auto-next, no automatic hook, and **no Automatic Distillation step** (onboard is not a wrap-up command).
-- Writes only `conventions` and `constraints`; never `decisions` or `pitfalls`.
+- Writes only `conventions` and `constraints`; never `decisions`, `pitfalls`, `strategies`, or `runbooks`.
 - Produces no persistent document beyond profile records.

{codexspec-0.7.11 → codexspec-0.7.12}/templates/commands/specify.md

@@ -55,7 +55,7 @@ When the argument identifies an existing feature:
 Before discussing and finalizing requirements, read the project profile under `.codexspec/profile/` when it exists so the confirmed `requirements.md` is a synthesis that already accounts for accumulated project knowledge. Each category is a directory holding one record per file:
 
 - `constraints/` first — the project's hard prohibitions (highest weight); requirements MUST NOT contradict them.
-- `pitfalls/`, `conventions/`, `decisions/` — read the records relevant to this feature's area, to avoid re-hitting known traps, to follow established conventions, and to reuse past cross-feature/architectural decisions rather than re-litigating them.
+- `pitfalls/`, `conventions/`, `decisions/`, `strategies/`, `runbooks/` — read the records relevant to this feature's area, to avoid re-hitting known traps, to follow established conventions, to reuse past cross-feature/architectural decisions rather than re-litigating them, and to apply proven strategies and procedures.
 
 Each record carries a `status` (`candidate` or `vetted`); weight `candidate` entries with appropriate caution. Fold what is relevant into the discussion and the resulting entries; cite a profile record as evidence when it materially shapes a decision. This is the single point where the profile enters the SDD pipeline — downstream stages keep `requirements.md` as authority and do not re-read the profile. Degrade silently when the profile is absent or empty (nothing to apply); never block on it.