@shiftleftpt/sbd-toe-mcp 0.10.3 → 0.11.0

package/dist/tools/prepare-codegen-context.d.ts

@@ -29,6 +29,32 @@
 import type { Affordance } from "../serving/protocol-envelope.js";
 export type CodegenMode = "codegen" | "review" | "test-plan";
 export type RiskLevel = "L1" | "L2" | "L3";
+/**
+ * Response ENCODING level (v2 token diet, epic v2-token-diet slice s1).
+ *
+ * - `full` (default): classic payload, byte-identical to previous releases —
+ *   whether `detail` is omitted or explicitly "full".
+ * - `standard` / `minimal`: same citable ID set, deduplicated encoding
+ *   (inverted `citations`, grouped `manual_grounding`, top-level
+ *   `provenance_legend` instead of per-item `source`). No information is
+ *   lost — only the serialization changes. Since s3b (revised ADENDA
+ *   2026-07-05 — no top-N/subsetting) `minimal` differs from `standard`
+ *   ONLY in traceability serialization: evidence cap 10→5 and the minimal
+ *   `manual_grounding` form; the activated scope stays complete and
+ *   byte-identical to `standard`.
+ * - `ultrathin` (s3c, reactivated by the operator 2026-07-05): one level below
+ *   `minimal`, same rules (COMPLETE activated set, no top-k, nothing id-only,
+ *   never silent) but requirements/controls WITHOUT the published
+ *   `description` (executable `descriptions_ref` → detail="minimal"),
+ *   evidence_patterns 0 inline (counts + rest-ref → detail="minimal"),
+ *   `manual_grounding` reduced to {total_entries, manual_commit_sha,
+ *   groups_ref} and `completeness_report` diagnostics trimmed to exact counts
+ *   (+ executable ref). Citable ID set unchanged (invariant 3).
+ *
+ * The default flips to `standard` only at graduation to the next stable
+ * release (documented as breaking) — never on the beta line.
+ */
+export type CodegenDetailLevel = "ultrathin" | "minimal" | "standard" | "full";
 export interface PrepareCodegenContextInput {
     task: string;
     risk_level?: RiskLevel;
@@ -40,12 +66,21 @@ export interface PrepareCodegenContextInput {
     changed_files?: string[];
     regulatory_frameworks?: string[];
     include_regulatory_overlay?: boolean;
+    detail?: CodegenDetailLevel;
+    /**
+     * v2 token diet, s2 — escape hatch for clients that cannot make a second
+     * call: when true, `detail: "standard" | "minimal"` keeps `g2_context.relations`
+     * inline (dieted: no per-item `source`) instead of `relations_ref`.
+     * Ignored at `detail: "full"` (full is always byte-identical to the classic
+     * payload, relations inline).
+     */
+    include_relations?: boolean;
     debug?: boolean;
 }
 export type PrepareCodegenStatus = "ready_for_codegen" | "needs_clarification" | "needs_decomposition" | "unsupported_scope";
 export interface ActivationTraceEntry {
     /** Triggered by: explicit concern, task term, changed file, framework hint, semantic alias, compound term, or intent keyword. */
-    source: "explicit_concern" | "task_term" | "compound_term" | "alias_expansion" | "intent_keyword" | "changed_file" | "regulatory_framework" | "risk_level" | "scope_gate";
+    source: "explicit_concern" | "task_term" | "compound_term" | "alias_expansion" | "intent_keyword" | "changed_file" | "regulatory_framework" | "risk_level" | "exposure" | "data_sensitivity" | "context_chapter" | "scope_gate";
     /** What the activation produced (concern, slice_family, framework_id, decision). */
     produced: string;
     /** The literal token or input that triggered the activation. */
@@ -202,6 +237,22 @@ export interface CompletenessReport {
     evidence_patterns_capped: number;
     /** Cap value applied during this resolution. */
     evidence_pattern_cap: number;
+    /**
+     * MP1 selection summary (G-mp1a O2, 2026-08-31): the requirement set comes from
+     * the selection engine (baseline ∪ context-activated chapters, narrowed by the
+     * task's declared signals). Never-silent: what the narrowing excluded is counted
+     * here and fully listed by the executable ref. Additive key.
+     */
+    selection?: {
+        eligible: number;
+        selected: number;
+        narrowed_out_categories: number;
+        narrowed_out_requirements: number;
+        narrowed_out_ref: {
+            tool: "select_sbd_toe_requirements";
+            note: string;
+        };
+    };
 }
 export interface SecurityRationaleTemplate {
     task: string;
@@ -261,12 +312,581 @@ export interface PrepareCodegenContextResultBlocked {
         notes: string[];
     };
 }
-export type PrepareCodegenContextResult = PrepareCodegenContextResultReady | PrepareCodegenContextResultBlocked;
-declare const VALID_CONCERNS: readonly ["auth", "logging", "validation", "api", "config", "integrity", "distribution", "ide", "requirements", "architecture", "iac", "encryption", "secrets", "build", "supply_chain", "testing", "threat_modeling", "monitoring", "release", "deployment", "integration"];
+/** An item shape with the repeated per-item `source` field removed (the
+ * provenance is carried once, in `provenance_legend`). */
+export type WithoutSource<T> = Omit<T, "source">;
+/**
+ * Inverted citation encoding (replaces `citation_map` in `standard`/`minimal`).
+ * Grouped by source; `source_data` is an ORDERED run-length map
+ * `file → count`: the first N₁ citable ids come from the first file, the
+ * next N₂ from the second, and so on. This preserves the exact per-id
+ * `{source, source_data}` of the classic `citation_map` with zero repetition.
+ *
+ * s3: the ids themselves are NOT repeated when they already appear verbatim in
+ * a payload section — `ids_from` lists, aligned 1:1 with the `source_data`
+ * files, the payload path whose ids (in payload order) are the run for that
+ * file. `keys(section[slice])` paths iterate the slice groups in order, then
+ * the entity-id keys in order. The explicit `ids` array is kept ONLY as a
+ * lossless fallback when a file has no static payload-path mapping (expected
+ * never for the published bundle). Exactly one of `ids_from`/`ids` is present.
+ */
+export interface CitationsGroup {
+    /** Ordered map: published file → number of consecutive citable ids. */
+    source_data: Record<string, number>;
+    /** Payload paths (aligned with `source_data` keys) whose ids, in payload
+     * order, are the ids for each file's run. */
+    ids_from?: string[];
+    /** Lossless fallback: explicit ids, ordered by the `source_data` runs. */
+    ids?: string[];
+}
+export type CitationsBySource = Partial<Record<CitationMapEntry["source"], CitationsGroup>>;
+/**
+ * `manual_grounding` grouped by (rastreabilidade_role, manual_chapter,
+ * manual_file, manual_commit_sha) — the fields that repeat verbatim across
+ * entries. Total information is preserved: `v1_entity_ids` lists every entry
+ * of the group, and `v1_entity_names` carries ONLY the names that are not
+ * already recoverable from the `g2_context` entity lists in the same payload
+ * (normally empty — names come from the same rastreabilidade source).
+ */
+export interface ManualGroundingGroup {
+    rastreabilidade_role: string;
+    manual_chapter?: string | null;
+    manual_file?: string | null;
+    manual_commit_sha?: string;
+    v1_entity_ids: string[];
+    /** Lossless guard: names NOT recoverable via g2_context entity `name`. */
+    v1_entity_names?: Record<string, string>;
+}
+export interface ManualGroundingGrouped {
+    /** Number of flat entries the groups encode (dedup audit: sum of group sizes). */
+    total_entries: number;
+    groups: ManualGroundingGroup[];
+    /** Lossless guard: entries without a v1_entity_id (expected empty). */
+    ungrouped?: Array<WithoutSource<ManualGroundingEntry>>;
+}
+/**
+ * v2 token diet, s3b (revised ADENDA 2026-07-05) — minimal-form grounding
+ * group: the SAME group as {@link ManualGroundingGroup} (1:1, same order) with
+ * the per-group `v1_entity_ids` list replaced by its exact count (`entries`).
+ * The grounding id SET is NOT lost: every grounding v1_entity_id is an
+ * activated entity id already present verbatim in this payload's
+ * `g2_context` entity maps (the grounding is resolved FROM those ids) — only
+ * the id→(chapter,file) traceability assignment moves behind the executable
+ * `groups_ref` (same input, detail="standard"). Never silent: `entries`
+ * counts sum to `total_entries`.
+ */
+export interface ManualGroundingMinimalGroup {
+    rastreabilidade_role: string;
+    manual_chapter?: string | null;
+    manual_file?: string | null;
+    /** Present ONLY when the sha could not be hoisted to the top level
+     * (mixed/absent shas across groups — never expected for the published
+     * bundle; lossless guard). */
+    manual_commit_sha?: string;
+    /** Exact number of v1_entity_ids the detail="standard" group carries. */
+    entries: number;
+    /** Lossless guard: names NOT recoverable via g2_context entity `name`
+     * (kept verbatim from the standard group; expected never). */
+    v1_entity_names?: Record<string, string>;
+}
+/** Executable reference to the full per-group grounding ids (s3b). */
+export interface GroundingGroupsRef {
+    tool: "prepare_sbd_toe_codegen_context";
+    /** Merge over this call's input_echo: same input, detail="standard". */
+    with: {
+        detail: "standard";
+    };
+    note: string;
+}
+/**
+ * `manual_grounding` at `detail: "minimal"` (s3b revised): aggregated
+ * provenance — total count, the manual_commit_sha shared by every group
+ * (hoisted), and the (role, chapter, file) group list with per-group entry
+ * COUNTS instead of per-group id lists — plus the executable `groups_ref`.
+ * The citable id set is untouched (invariant 3): grounding ids never feed
+ * `citations`/`ids_from`, and the id set itself stays reconstructible from
+ * this same payload's g2_context entity maps without any extra call.
+ */
+export interface ManualGroundingMinimal {
+    /** Number of flat detail="full" entries the groups encode (Σ entries). */
+    total_entries: number;
+    /** Hoisted provenance: present iff EVERY group carries this same sha
+     * (expected always for the published bundle); otherwise each group keeps
+     * its own `manual_commit_sha` inline (lossless guard). */
+    manual_commit_sha?: string;
+    groups: ManualGroundingMinimalGroup[];
+    /** How to obtain the full per-group v1_entity_ids (detail="standard"). */
+    groups_ref: GroundingGroupsRef;
+    /** Lossless guard: entries without a v1_entity_id (expected empty). */
+    ungrouped?: Array<WithoutSource<ManualGroundingEntry>>;
+}
+/**
+ * `manual_grounding` at `detail: "ultrathin"` (s3c): aggregate provenance ONLY
+ * — `{total_entries, manual_commit_sha, groups_ref}` — derived from the s3b
+ * minimal form with the (role, chapter, file) group list elided too. Never
+ * silent: `total_entries` is the exact flat detail="full" entry count and
+ * `groups_ref` is the executable reference (same input, detail="standard")
+ * that returns the full 1:1 grouping with per-group v1_entity_ids. Lossless
+ * guards (both expected never for the published bundle): if the sha could not
+ * be hoisted OR any group carries non-recoverable `v1_entity_names`, the s3b
+ * minimal `groups` list survives inline; `ungrouped` entries survive verbatim.
+ * Invariant-3 note (same as minimal): grounding ids never feed
+ * `citations`/`ids_from`, and the grounding id SET stays reconstructible from
+ * this same payload's g2_context entity maps without any extra call.
+ */
+export interface ManualGroundingUltrathin {
+    /** Number of flat detail="full" entries the elided groups encode. */
+    total_entries: number;
+    /** Hoisted provenance (expected always: one published manual commit). */
+    manual_commit_sha?: string;
+    /** Lossless guard: present ONLY when hoisting failed or a group carried
+     * v1_entity_names (never expected) — the s3b minimal groups, verbatim. */
+    groups?: ManualGroundingMinimalGroup[];
+    /** How to obtain the full per-group v1_entity_ids (detail="standard"). */
+    groups_ref: GroundingGroupsRef;
+    /** Lossless guard: entries without a v1_entity_id (expected empty). */
+    ungrouped?: Array<WithoutSource<ManualGroundingEntry>>;
+}
+/**
+ * v2 token diet, s3 — dieted requirement projection. `category` is elided when
+ * (and only when) it equals the category segment of the `requirement_id` —
+ * the segment immediately before the number (`AUT-003` → `AUT`,
+ * `REQ-AGN-001` → `AGN`; consumer contract v1.10 §1.18, single source
+ * `src/serving/requirement-id.ts`). True for all 255 published requirements;
+ * the field survives verbatim on any future mismatch — lossless guard. `description` is the PUBLISHED bundle
+ * field (data/publish/runtime/requirements.json), verbatim, never paraphrased
+ * — the "how" the full projection historically dropped.
+ */
+export interface DietedRequirement {
+    requirement_id: string;
+    name: string;
+    type?: string;
+    /** Present only on the (never expected) category ≠ id-category-segment mismatch. */
+    category?: string;
+    /** Verbatim `description` from the published bundle. */
+    description?: string;
+}
+/**
+ * v2 token diet, s3 — dieted control projection: classic fields minus `source`
+ * plus, for `confidence: "direct"` controls only, the verbatim published
+ * `description` (data/publish/runtime/controls.json).
+ */
+export type DietedControl = WithoutSource<ActivatedScope["controls"][number]> & {
+    description?: string;
+};
+/**
+ * v2 token diet, s3c — executable reference left in `activated_scope` at
+ * `detail: "ultrathin"`, where the verbatim published `description` fields
+ * (the "how", s3) are elided from requirements and direct controls. Never
+ * silent: the lists themselves stay COMPLETE (same ids, same order, name
+ * always present — nothing id-only); only the description field moves behind
+ * this reference. detail="minimal" is the cheapest level that returns the
+ * same complete scope WITH the descriptions (verbatim, never paraphrased).
+ */
+export interface ActivatedScopeDescriptionsRef {
+    tool: "prepare_sbd_toe_codegen_context";
+    /** Merge over this call's input_echo: same input, detail="minimal". */
+    with: {
+        detail: "minimal";
+    };
+    note: string;
+}
+export interface DietedActivatedScope {
+    requirements: DietedRequirement[];
+    controls: DietedControl[];
+    slices: Array<WithoutSource<ActivatedScope["slices"][number]>>;
+    regulatory_obligations: Array<WithoutSource<ActivatedScope["regulatory_obligations"][number]>>;
+    /** Present ONLY at detail="ultrathin" (s3c): how to obtain the verbatim
+     * published descriptions elided from requirements + direct controls. */
+    descriptions_ref?: ActivatedScopeDescriptionsRef;
+}
+/**
+ * v2 token diet, s2 — Relations on-demand. In `standard`/`minimal` the inline
+ * `g2_context.relations` array (~4.3K tokens) is replaced by a REFERENCE to
+ * executable calls of the `trace_sbd_toe_graph` tool whose union returns a
+ * superset of the elided relations. Anchors are activated slice_ids/entity_ids
+ * from THIS payload — domain ids, never internal IRIs (EPIC invariant 6).
+ *
+ * Relation kind → curated lens mapping (see buildRelationsRef):
+ *  - (objective → mechanism/practice) edges, where the objective has a
+ *    belongsToSlice edge to an activated slice S:
+ *      `slice_implementation(anchor=S)` — each row (slice, objective, kind,
+ *      target) carries BOTH the objective→target edge (kind selects the
+ *      predicate) and the objective's belongsToSlice edge.
+ *  - (objective, belongsToSlice, S) for objectives with ≥1 mechanism/practice
+ *    edge: same `slice_implementation(anchor=S)` rows.
+ *  - (objective → target) edges whose objective is activated but has NO
+ *    belongsToSlice edge in the published graph (data gap):
+ *      `objective_realization(anchor=objective)`.
+ *  - (objective → target) edges where only the TARGET is activated
+ *    (cross-slice): `mechanism_provenance(anchor=target)` — the predicate is
+ *    recovered from the target's entity_type in this same payload.
+ *  - (entity, belongsToSlice, slice) for Mechanism/Practice/Artifact subjects
+ *    (and objectives without mechanism/practice edges): NO curated lens
+ *    returns these edges, and they are 100% redundant with the payload — every
+ *    `g2_context` entity already carries `slice_id`. Counted as
+ *    `coverage.implicit_in_entities` (never silently dropped).
+ *  - Anything not covered above stays INLINE in `residual_relations`
+ *    (expected empty; never-silent guard).
+ */
+export interface RelationsRefLensCall {
+    lens: "slice_implementation" | "objective_realization" | "mechanism_provenance";
+    /** Activated slice_id or entity_id from this payload (id, never an IRI). */
+    anchor: string;
+}
+export interface RelationsRef {
+    tool: "trace_sbd_toe_graph";
+    /** Executable calls whose union covers the lens-recoverable relations. */
+    lenses: RelationsRefLensCall[];
+    /** Exact number of relations that would go inline at detail=full (audit). */
+    total_relations: number;
+    /** Never-silent split of total_relations by recovery path. */
+    coverage: {
+        /** Recoverable by executing the `lenses` calls above. */
+        via_lenses: number;
+        /** belongsToSlice edges equal to the `slice_id` field of a g2_context entity. */
+        implicit_in_entities: number;
+        /** Relations kept inline in `residual_relations` (expected 0). */
+        residual_inline: number;
+    };
+    /** Only present when a relation is neither lens-recoverable nor implicit. */
+    residual_relations?: Array<WithoutSource<G2ContextRelation>>;
+    note: string;
+}
+/**
+ * v2 token diet, s3 — slice-grouped entity encoding for `standard`/`minimal`:
+ * `{ slice_id: { entity_id: name | null } }`. Lossless re-encoding of the
+ * classic entity list: `entity_type` is the list the map lives in,
+ * `slice_id` is the group key, `slice_family` is
+ * `activated_scope.slices[].objective_family` for that slice_id, and a `null`
+ * name means the full projection omits `name` (unnamed in rastreabilidade).
+ * Group/key order preserves the classic list order (insertion order).
+ */
+export type SliceGroupedEntityNames = Record<string, Record<string, string | null>>;
+/**
+ * v2 token diet, s3 — dieted evidence pattern: classic projection minus
+ * `source` (s1 legend) and minus the tool-computed `relevance_score` (the
+ * DETERMINISTIC list order — relevance_score desc, then id asc — already
+ * carries the ranking; documented in the codegen-instructions resource).
+ */
+export type DietedEvidencePattern = Omit<G2ContextEvidencePattern, "source" | "relevance_score">;
+export interface DietedG2Context {
+    control_objectives: SliceGroupedEntityNames;
+    mechanisms: SliceGroupedEntityNames;
+    practices: SliceGroupedEntityNames;
+    artifacts: SliceGroupedEntityNames;
+    /** Inline only with `include_relations: true` (s2); otherwise see relations_ref. */
+    relations?: Array<WithoutSource<G2ContextRelation>>;
+    /** Present when relations are elided (s2 default at standard/minimal). */
+    relations_ref?: RelationsRef;
+    /** s3: deterministic top-{@link STANDARD_EVIDENCE_PATTERN_CAP} prefix of the
+     * classic list (see completeness_report for the never-silent counts). */
+    evidence_patterns: DietedEvidencePattern[];
+}
+export interface DietedRegulatoryOverlayContext {
+    frameworks: Array<WithoutSource<RegulatoryOverlayContext["frameworks"][number]>>;
+    obligations: Array<WithoutSource<RegulatoryOverlayContext["obligations"][number]>>;
+    mappings: Array<WithoutSource<RegulatoryOverlayContext["mappings"][number]>>;
+    playbooks: Array<WithoutSource<RegulatoryOverlayContext["playbooks"][number]>>;
+}
+/**
+ * Inline legend for `standard`/`minimal` (s3: slim pointer — the full legend,
+ * including the section→source table and every derivation rule of the dieted
+ * encoding, lives in the `sbd://toe/codegen-instructions/{mode}` resource,
+ * section `detail_encoding`).
+ */
+declare const PROVENANCE_LEGEND: {
+    readonly note: string;
+};
+export type ProvenanceLegend = typeof PROVENANCE_LEGEND;
+/**
+ * v2 token diet, s4 — cheap turns, not fewer turns: short note (≈50 tokens)
+ * appended to every `standard`/`minimal` ready payload. The production
+ * write-test-edit loop is legitimate; what must not repeat is the cost of
+ * re-requesting THIS payload — an identical call returns a byte-identical
+ * result (deterministic, tested), so the context already in the session is
+ * the source for the loop. Follow-ups that genuinely need more go through
+ * `detail: "minimal"` or a targeted `consult_security_requirements` call —
+ * never a repeat of the full payload. `full` carries NO hint (byte-identical
+ * to the classic payload, EPIC invariant 1).
+ */
+export declare const REPEAT_CALL_HINT: string;
+/**
+ * v2 token diet, s3 — reference that replaces the inline
+ * `llm_codegen_instructions` + `security_rationale_template` boilerplate at
+ * `detail: "standard" | "minimal"` (both stay inline at `full`). The MCP
+ * resource carries, per mode, the exact instruction slots and the template
+ * skeleton; `active_conditions` lists which conditional slots apply to THIS
+ * call, so the inline full content is reconstructible byte-identically.
+ */
+export interface CodegenInstructionsRef {
+    resource: string;
+    /** Conditional instruction slots active for this call (see the resource's
+     * `llm_codegen_instructions.slots[].when`). */
+    active_conditions: InstructionCondition[];
+    note: string;
+}
+/**
+ * v2 token diet, s3 — never-silent counter left in place of the elided
+ * `activation_trace` at `detail: "standard" | "minimal"` (the full trace is
+ * included when `debug: true`, and always at `detail: "full"`).
+ */
+export interface ActivationTraceRef {
+    entries: number;
+    note: string;
+}
+/**
+ * v2 token diet, s3 — executable reference for retrieving the evidence
+ * patterns omitted by the standard cap (boundList discipline: the counts live
+ * in the same completeness_report; this says HOW to get the rest).
+ */
+export interface EvidencePatternsRest {
+    tool: "prepare_sbd_toe_codegen_context";
+    /** Merge over this call's input_echo: same input, detail="full" (the
+     * classic top-25) at standard/minimal; detail="minimal" (the CHEAPEST level
+     * that returns patterns inline) at ultrathin (s3c). */
+    with: {
+        detail: "full";
+    } | {
+        detail: "minimal";
+    };
+    note: string;
+}
+/** Completeness report at `standard`/`minimal`: classic counters (with the
+ * s3 cap values) plus, when patterns were cut, the executable rest-reference. */
+export type DietedCompletenessReport = CompletenessReport & {
+    evidence_patterns_rest?: EvidencePatternsRest;
+};
+/**
+ * v2 token diet, s3c — executable reference for the completeness diagnostics
+ * elided at `detail: "ultrathin"` (never silent: exact counts stay inline;
+ * detail="minimal" is the cheapest level whose completeness_report carries
+ * the full text arrays inline).
+ */
+export interface V1DiagnosticsRef {
+    tool: "prepare_sbd_toe_codegen_context";
+    /** Merge over this call's input_echo: same input, detail="minimal". */
+    with: {
+        detail: "minimal";
+    };
+    note: string;
+}
+/**
+ * Completeness report at `detail: "ultrathin"` (s3c) — trimmed to the
+ * essentials that support the never-silent discipline. KEPT verbatim: every
+ * expected/returned count and m_recall (recall audit), named/unnamed entity
+ * counts, and the evidence counts (total / returned=0 / capped=total / cap=0)
+ * with the executable `evidence_patterns_rest`. CUT (serialization only, each
+ * replaced by its exact count + the executable `v1_diagnostics_ref` when any
+ * count > 0): the `v1_consistency_mismatches` and `v1_manifest_warnings` TEXT
+ * arrays (the verbose per-slice contract-warning strings, ~100 tokens/call).
+ */
+export type UltrathinCompletenessReport = Omit<DietedCompletenessReport, "v1_consistency_mismatches" | "v1_manifest_warnings"> & {
+    /** Exact length of the elided v1_consistency_mismatches array (expected 0). */
+    v1_consistency_mismatches_count: number;
+    /** Exact length of the elided v1_manifest_warnings array. */
+    v1_manifest_warnings_count: number;
+    /** Present iff either count above is > 0: how to obtain the full texts. */
+    v1_diagnostics_ref?: V1DiagnosticsRef;
+};
+/**
+ * `ready_for_codegen` result at `detail: "standard" | "minimal"`. Same citable
+ * ID set as the full result (invariant 3) — the encoding is deduplicated (s1),
+ * relations are served on-demand (s2) and, since s3:
+ *   - `g2_context.evidence_patterns` is capped 25→10 (deterministic prefix;
+ *     never-silent counts + rest-reference in `completeness_report`);
+ *   - `llm_codegen_instructions` + `security_rationale_template` move to the
+ *     `sbd://toe/codegen-instructions/{mode}` MCP resource
+ *     (`codegen_instructions_ref` carries the URI + active conditions);
+ *   - `activation_trace` is included only with `debug: true`
+ *     (`activation_trace_ref` keeps the never-silent count otherwise);
+ *   - requirements and `direct` controls carry the verbatim published
+ *     `description` (the "how"), and derivable fields (`category`,
+ *     `entity_type`, `slice_family`, `relevance_score`, repeated citation ids)
+ *     are elided per the resource's `detail_encoding` legend.
+ *
+ * s3b (revised per the 2026-07-05 operator ADENDA — NO top-N/subsetting):
+ * `minimal` diverges from `standard` ONLY in serialization of traceability,
+ * never in execution context. The activated scope (requirements + controls
+ * with descriptions, slices, obligations, g2 entities, citations,
+ * relations_ref) is byte-identical to `standard`; `minimal` additionally
+ *   - caps `g2_context.evidence_patterns` 10→5 (same s3 mechanism: prefix,
+ *     counts, rest-ref);
+ *   - serves `manual_grounding` in the minimal form ({@link
+ *     ManualGroundingMinimal}: counts + hoisted sha + executable groups_ref).
+ *
+ * s3c (`detail: "ultrathin"`, operator ADENDA 2026-07-05): one level below
+ * `minimal`, same rules (activated set COMPLETE, no top-k, nothing id-only,
+ * never silent). Diverges from `minimal` ONLY in:
+ *   - requirements/controls WITHOUT the published `description` (fields kept:
+ *     requirement {requirement_id, name, type}; control {control_id, name,
+ *     domain, control_type, confidence}; the `category` lossless guard is
+ *     unchanged) + executable `activated_scope.descriptions_ref`;
+ *   - `g2_context.evidence_patterns` cap 5→0 (counts + rest-ref to the
+ *     cheapest level that returns them: detail="minimal");
+ *   - `manual_grounding` in the ultrathin form ({@link ManualGroundingUltrathin}:
+ *     total + hoisted sha + executable groups_ref, group list elided);
+ *   - `completeness_report` diagnostics trimmed ({@link
+ *     UltrathinCompletenessReport}: text arrays → exact counts + executable ref).
+ * Everything else — g2 entity maps (id→name|null), relations_ref, citations,
+ * codegen_instructions_ref, repeat_call_hint, provenance, next — is
+ * byte-identical to the other dieted levels.
+ */
+export interface PrepareCodegenContextResultReadyDieted {
+    status: "ready_for_codegen";
+    /** RF-H advisory band — adjacent tools the caller likely needs next. */
+    next?: Affordance[];
+    mode: CodegenMode;
+    input_echo: PrepareCodegenContextResultReady["input_echo"];
+    /** Present only with `debug: true` (s3); see activation_trace_ref otherwise. */
+    activation_trace?: ActivationTraceEntry[];
+    /** Present when activation_trace is elided (never-silent counter). */
+    activation_trace_ref?: ActivationTraceRef;
+    provenance_legend: ProvenanceLegend;
+    activated_scope: DietedActivatedScope;
+    g2_context: DietedG2Context;
+    /** Grouped (standard), minimal (s3b) or ultrathin form (s3c). */
+    manual_grounding: ManualGroundingGrouped | ManualGroundingMinimal | ManualGroundingUltrathin;
+    regulatory_overlay: DietedRegulatoryOverlayContext;
+    citations: CitationsBySource;
+    completeness_report: DietedCompletenessReport | UltrathinCompletenessReport;
+    codegen_instructions_ref: CodegenInstructionsRef;
+    /** s4 — reuse note ({@link REPEAT_CALL_HINT}): identical re-call is
+     * deterministic; the context already received is the loop's source. */
+    repeat_call_hint: string;
+    provenance: PrepareCodegenContextResultReady["provenance"];
+    debug?: PrepareCodegenContextResultReady["debug"];
+}
+export type PrepareCodegenContextResult = PrepareCodegenContextResultReady | PrepareCodegenContextResultReadyDieted | PrepareCodegenContextResultBlocked;
+declare const VALID_CONCERNS: readonly ["auth", "logging", "validation", "api", "config", "integrity", "distribution", "ide", "requirements", "architecture", "iac", "encryption", "secrets", "build", "supply_chain", "testing", "threat_modeling", "monitoring", "release", "deployment", "integration", "agents"];
 export type Concern = (typeof VALID_CONCERNS)[number];
+export interface NormalizedInput {
+    task: string;
+    taskTrimmed: string;
+    taskLower: string;
+    tokenCount: number;
+    mode: CodegenMode;
+    risk_level?: RiskLevel;
+    stack?: string;
+    exposure?: PrepareCodegenContextInput["exposure"];
+    data_sensitivity?: PrepareCodegenContextInput["data_sensitivity"];
+    concerns: Concern[];
+    unknownConcerns: string[];
+    changed_files: string[];
+    regulatory_frameworks: string[];
+    include_regulatory_overlay: boolean;
+    debug: boolean;
+}
+export declare function normalizeInput(raw: unknown): NormalizedInput;
+export interface ActivationResult {
+    concerns: Concern[];
+    sliceFamilies: string[];
+    /** P3 do ciclo MP1 (2026-08-31): famílias contadas para o gate de decomposição —
+     * UM SINAL = UMA SUPERFÍCIE. Só o concern PRIMÁRIO de cada sinal (posição 0 do
+     * mapeamento do termo/frase; explícitos/intents/ficheiros contam por si) contribui
+     * a sua família; concerns de suporte (posições secundárias, ex.: mtls→secrets,
+     * message queue→logging) activam categorias mas não são superfícies novas.
+     * `sliceFamilies` (grounding) fica intocado. */
+    decompositionFamilies: string[];
+    trace: ActivationTraceEntry[];
+    rejected: ActivationTraceEntry[];
+    notes: string[];
+    /** Per-concern aggregated score (max over contributing trace entries). */
+    concernScores: Map<Concern, number>;
+    /** Per-slice-family aggregated score. */
+    sliceFamilyScores: Map<string, number>;
+}
+export declare function activate(input: NormalizedInput): ActivationResult;
+export declare function categoriesForConcerns(concerns: Concern[]): Set<string>;
+/**
+ * Conditions under which a conditional instruction slot is included inline at
+ * `detail: "full"`. The dieted `codegen_instructions_ref.active_conditions`
+ * lists the conditions active for a given call, so a client reading the
+ * resource reconstructs the inline instruction list byte-identically.
+ */
+export type InstructionCondition = "always" | "regulatory_overlay" | "risk_level:L1" | "risk_level:L2" | "risk_level:L3" | "citation_map_empty";
+export interface InstructionSlot {
+    when: InstructionCondition;
+    text: string;
+}
+/**
+ * Ordered instruction slots for a mode. The emission order of
+ * {@link buildLlmInstructions} is EXACTLY this list filtered by active
+ * conditions — the classic (pre-s3) output is byte-identical by construction.
+ */
+export declare function instructionSlotsForMode(mode: CodegenMode): InstructionSlot[];
+export declare const CODEGEN_INSTRUCTION_MODES: readonly CodegenMode[];
+export declare const CODEGEN_INSTRUCTIONS_RESOURCE_URI_PREFIX = "sbd://toe/codegen-instructions/";
+export declare function codegenInstructionsResourceUri(mode: CodegenMode): string;
+/**
+ * Full legend of the dieted (`standard`/`minimal`) encoding, published in the
+ * codegen-instructions resource. Every rule here is a lossless, deterministic
+ * derivation over the SAME payload (or an executable reference) — nothing is
+ * silently dropped (EPIC invariant 2) and no data changes, only serialization
+ * (EPIC invariant 4).
+ */
+declare const DETAIL_ENCODING_LEGEND: {
+    readonly note: string;
+    readonly sources: {
+        readonly note: string;
+        readonly map: {
+            readonly "activated_scope.requirements": "runtime_v0";
+            readonly "activated_scope.controls": "runtime_v0";
+            readonly "activated_scope.slices": "runtime_v1";
+            readonly "activated_scope.regulatory_obligations": "overlay";
+            readonly "g2_context.control_objectives": "runtime_v1";
+            readonly "g2_context.mechanisms": "runtime_v1";
+            readonly "g2_context.practices": "runtime_v1";
+            readonly "g2_context.artifacts": "runtime_v1";
+            readonly "g2_context.relations": "runtime_v1";
+            readonly "g2_context.evidence_patterns": "runtime_v0";
+            readonly "manual_grounding.groups": "runtime_v1";
+            readonly "regulatory_overlay.frameworks": "overlay";
+            readonly "regulatory_overlay.obligations": "overlay";
+            readonly "regulatory_overlay.mappings": "overlay";
+            readonly "regulatory_overlay.playbooks": "overlay";
+        };
+    };
+    readonly citations: string;
+    readonly activated_scope_requirements: string;
+    readonly activated_scope_controls: string;
+    readonly g2_entities: string;
+    readonly evidence_patterns: string;
+    readonly manual_grounding_minimal: string;
+    readonly activation_trace: string;
+    readonly relations_ref: string;
+    readonly ultrathin: string;
+};
+export interface CodegenInstructionsResourceContent {
+    resource: string;
+    mode: CodegenMode;
+    note: string;
+    llm_codegen_instructions: {
+        assembly: string;
+        slots: InstructionSlot[];
+    };
+    security_rationale_template: {
+        assembly: string;
+        template: {
+            task: null;
+        } & Omit<SecurityRationaleTemplate, "task">;
+    };
+    detail_encoding: typeof DETAIL_ENCODING_LEGEND;
+}
+/**
+ * Content of the `sbd://toe/codegen-instructions/{mode}` MCP resource — the
+ * static-per-mode boilerplate that detail=standard/minimal payloads reference
+ * instead of carrying inline. Reconstructing the inline `full` content from
+ * this resource is byte-exact (tested):
+ *   - llm_codegen_instructions = slots filtered by `when` ("always" +
+ *     codegen_instructions_ref.active_conditions), in order;
+ *   - security_rationale_template = template with `task` set to the trimmed
+ *     task string (input_echo.task.trim()).
+ */
+export declare function buildCodegenInstructionsResourceContent(mode: CodegenMode): CodegenInstructionsResourceContent;
 export declare function handlePrepareCodegenContext(raw: PrepareCodegenContextInput): PrepareCodegenContextResult;
 export declare const __wp5Lexicon: {
-    VALID_CONCERNS: readonly ["auth", "logging", "validation", "api", "config", "integrity", "distribution", "ide", "requirements", "architecture", "iac", "encryption", "secrets", "build", "supply_chain", "testing", "threat_modeling", "monitoring", "release", "deployment", "integration"];
-    CONCERN_TO_SLICE_FAMILY: Readonly<Record<"release" | "auth" | "logging" | "validation" | "api" | "config" | "integrity" | "distribution" | "ide" | "requirements" | "architecture" | "iac" | "encryption" | "monitoring" | "build" | "secrets" | "supply_chain" | "testing" | "threat_modeling" | "deployment" | "integration", string | null>>;
+    VALID_CONCERNS: readonly ["auth", "logging", "validation", "api", "config", "integrity", "distribution", "ide", "requirements", "architecture", "iac", "encryption", "secrets", "build", "supply_chain", "testing", "threat_modeling", "monitoring", "release", "deployment", "integration", "agents"];
+    CONCERN_TO_SLICE_FAMILY: Readonly<Record<"release" | "auth" | "logging" | "validation" | "api" | "config" | "integrity" | "distribution" | "ide" | "requirements" | "architecture" | "iac" | "encryption" | "agents" | "monitoring" | "build" | "secrets" | "supply_chain" | "testing" | "threat_modeling" | "deployment" | "integration", string | null>>;
 };
 export {};