renma 0.18.0 → 0.18.2

package/docs/diagnostics.md

@@ -57,6 +57,259 @@ Structured facts in `details` are the authoritative inputs for review tooling.
 `llmHint` is guidance only; changing hint wording should not change bundle
 grouping, affected files, affected assets, or repair decisions.
 
+## Classification Evidence
+
+`inspect`, `suggest-metadata`, and relevant scan finding or diagnostic
+`details` include additive `classification` evidence. Classification answers
+what path rule matched; governance separately answers whether owner, policy, or
+metadata is declared, inherited, missing, or not required. A file's kind never
+implies that it has an owner. `inspect` additionally exposes
+`repositoryBoundary`, preserving resolution source and repository-relative path
+when resolved or stable unresolved/ambiguous reason evidence and candidate
+roots when no safe boundary can be selected.
+
+For marker-free directory-segment inference, only `.agents`, `skills`,
+`contexts`, `context`, `lenses`, and `tools` can positively establish a
+structural boundary. Recognized root filenames are handled separately:
+`AGENTS.md` may establish its containing directory as the structural root when
+no stronger repository marker is available, while `renma.config.json` and
+`.renma.json` normally establish the boundary through repository-marker
+detection. The support-like names `profiles`, `references`, `examples`,
+`scripts`, and `assets` are guards only: they can block a later boundary-like
+segment or contribute ambiguity evidence, but never establish a repository root
+by themselves.
+
+> Classification describes how Renma interpreted repository structure. It does
+> not by itself prove ownership, policy, lifecycle, source-of-truth status, or
+> human intent.
+
+> Governance evidence describes what is actually declared or inherited.
+
+> Decision evidence describes whether Renma recommends a change, blocks one,
+> requires confirmation, or recommends no change.
+
+### How to Read Classification Evidence
+
+These fields answer different questions and must not be substituted for one
+another:
+
+| Field | What it indicates | What it does not indicate |
+| --- | --- | --- |
+| `kind` | The semantic parsing or inventory role Renma assigned to the file. | Governance scope, ownership, policy, lifecycle, validity, or human intent. |
+| `scope` | The structural governance boundary implied by the path. | That governance metadata exists, is valid, or may be inherited. |
+| `matchedRule` | The primary stable structural rule that classified the normalized repository-relative path. | That the resulting asset is owned, current, authoritative, or safe to change. |
+| `reasonCode` | A more specific deterministic reason for the rule result. | Governance or a repair decision by itself. |
+| `parentResolution` | How repository evidence resolved the parent implied by a Skill-local path. | The parent's owner or policy values. It is normally absent outside Skill-local classification. |
+| `governance` | Declared or inherited ownership, policy, and metadata provenance supported by repository evidence. | Human intent beyond the declarations Renma found. |
+| `decisionStatus` | The application gate for a command that can recommend a change. It is decision evidence, not classification evidence. | A different structural classification or permission to ignore blocked evidence. |
+
+`kind` is one of `skill`, `agent`, `context`, `context_lens`, `profile`,
+`reference`, `example`, `script`, `asset`, `config`, or `unknown`. It selects a
+semantic parsing or inventory role. It is not equivalent to `scope`: for
+example, a `reference` can be `skill-local`, while a repository tool currently
+has `kind: "unknown"` and `scope: "repository-support"`. Metadata can refine a
+file under a Context root from `context` to `context_lens` without changing the
+structural rule that matched.
+
+Optional classification fields add evidence without changing those core
+meanings:
+
+| Field | Meaning | Do not infer |
+| --- | --- | --- |
+| `reason` | Human-readable explanation of the current result. | A stable machine branch; wording may improve without a contract change. |
+| `recognizedRoot` | The repository-relative asset root or boundary recognized by the matched rule, such as `skills`, `.agents/skills`, or `contexts`. | The absolute filesystem repository root; use `repositoryBoundary` for that evidence. |
+| `parentAssetCandidatePath` | The parent Skill path implied by structure before repository resolution. | That the file exists or supplies governance. |
+| `parentAssetPath` | The one parent Skill source path selected by a `resolved` result. | That the parent declares an owner or policy. |
+| `parentAssetCandidates` | All plausible parent Skill paths retained by an `ambiguous` result. | That the first candidate is preferred or safe to select. |
+| `supportDirectory` | The support-like directory involved in classification, such as `references` or `scripts`. | That the directory is valid Skill-local support without the matching rule and parent evidence. |
+| `ignoredNestedSegments` | Nested support-like names that did not override a higher-priority recognized root. | That Renma ignored the file's content or omitted it from inventory. |
+| `competingRules` | Stable negative evidence explaining why a nearby alternative rule did not match. | An additional positive classification or permission to choose that rule. |
+
+#### Scope
+
+| `scope` | Meaning | Do not infer |
+| --- | --- | --- |
+| `independent` | The path establishes a recognized first-class asset or agent boundary rather than Skill-local or repository-support placement. | That owner, policy, lifecycle, or source-of-truth metadata exists or is valid. |
+| `skill-local` | The path is under a recognized canonical Skill support directory. | That a parent Skill exists or that inheritance is valid. Check `parentResolution` and `governance`. |
+| `repository-support` | The path is recognized as repository implementation or configuration support. | That it is an independently governed Context Asset. |
+| `unknown` | The path rule does not establish a known governance scope. | That the file is irrelevant, safe, unowned, or outside the repository. |
+
+#### Matched Rules
+
+`matchedRule` is the primary stable structural classification. Rules are applied
+in the precedence shown after this table, so a higher-priority match prevents a
+later, more generic interpretation.
+
+| `matchedRule` | Repository evidence matched | Indicates | Must not be inferred |
+| --- | --- | --- | --- |
+| `skill-entrypoint` | A recognized canonical or historical Skill entrypoint shape under `skills/**` or `.agents/skills/**`. | The file is classified as a Skill entrypoint with independent scope. | That Agent Skills frontmatter is valid, that governance is complete, or that no migration is needed. |
+| `skill-local-support` | A path inside `references/`, `profiles/`, `examples/`, `scripts/`, or `assets/` beneath a recognized Skill path shape. | The file has a structurally implied Skill parent candidate and Skill-local scope. | That the parent exists or inheritance is valid. Require `parentResolution: "resolved"` and governance evidence. |
+| `context-root` | A file under `contexts/**`. | The file is an independent Context Asset by structure; metadata may refine its `kind` to `context_lens`. | That owner, lifecycle, policy, or source-of-truth metadata is complete or valid. |
+| `context-root-legacy` | A file under the supported legacy `context/**` root. | The file is an independent Context Asset by the compatibility path rule. | That it is current, owned, authoritative, or should be moved automatically. |
+| `lens-root` | A file under `lenses/**`. | The file is an independent Context Lens by structure. | That Lens targets, governance, or policy declarations are valid. |
+| `agent-root` | `AGENTS.md` or a file under `.agents/**` after higher-priority Skill entrypoint rules. | The file is repository agent guidance with independent scope. | That it is an Agent Skill, that its instructions are valid, or that governance is complete. |
+| `repository-tool` | A file under top-level `tools/**`. | The file is repository implementation with repository-support scope. | That it is an independently governed Context Asset. |
+| `config-file` | A filename matching `renma.config.json` or `.renma.json` after higher-priority rules. | The file is recognized as Renma configuration support. | That its contents are valid, effective for a particular target, or proof of asset governance. |
+| `generic-reference` | A nested `references/` directory outside recognized independent and Skill-local asset boundaries. | The file receives the `reference` parsing or inventory role, but its scope remains unknown. | That it belongs to a Skill, may inherit governance, or is an independent Context Asset. |
+| `generic-example` | A nested `examples/` directory outside recognized independent and Skill-local asset boundaries. | The file receives the `example` parsing or inventory role, but its scope remains unknown. | That it belongs to a Skill, may inherit governance, or is independently governed. |
+| `generic-profile` | A nested `profiles/` directory outside recognized independent and Skill-local asset boundaries. | The file receives the `profile` parsing or inventory role, but its scope remains unknown. | That it is selected by a Skill, may inherit governance, or defines effective policy. |
+| `unknown` | No supported positive structural rule matched, or the path uses an unsupported reserved layout. | Renma has no more specific structural classification for the path. | That the file is irrelevant, harmless, unowned, safe to edit, or outside the resolved repository. |
+
+The stable path-rule precedence is:
+
+1. `skill-entrypoint`.
+2. `skill-local-support` inside a recognized Skill boundary.
+3. Recognized asset roots: `context-root`, `context-root-legacy`, `lens-root`,
+   and `agent-root`.
+4. Repository support or configuration: `repository-tool` and `config-file`.
+5. Compatible nested rules: `generic-reference`, `generic-example`, and
+   `generic-profile`.
+6. `unknown`.
+
+#### Parent Skill Resolution
+
+`parentResolution` is meaningful for `skill-local-support`. Only `resolved`
+permits Renma to claim one parent Skill, and even then consumers must inspect
+`governance` to learn whether that parent supplies an owner or policy.
+
+| `parentResolution` | Meaning | Consumer behavior |
+| --- | --- | --- |
+| `structural-candidate` | Path classification derived a possible `parentAssetCandidatePath`, but repository evidence has not resolved it. | Do not claim inheritance. Resolve the repository and parent evidence first. |
+| `resolved` | Repository evidence found exactly one parent Skill and exposes it as `parentAssetPath`. | Inheritance may be reported only as supported by the accompanying governance evidence. |
+| `missing` | No parent Skill exists at the structurally implied location. | Do not claim inheritance; treat a related change recommendation as blocked until the layout is reviewed. |
+| `ambiguous` | More than one parent Skill candidate remains plausible; candidates may appear in `parentAssetCandidates`. | Do not choose a parent or claim inheritance; require layout or human resolution. |
+
+For example, these two files have the same semantic role and structural scope,
+but only the first has one resolved parent:
+
+```json
+{
+  "classification": {
+    "kind": "reference",
+    "scope": "skill-local",
+    "matchedRule": "skill-local-support",
+    "parentResolution": "resolved",
+    "parentAssetPath": "skills/foo/SKILL.md"
+  },
+  "governance": {
+    "ownership": {
+      "declaredOwner": null,
+      "effectiveOwner": "docs",
+      "source": "inherited"
+    }
+  }
+}
+```
+
+```json
+{
+  "classification": {
+    "kind": "reference",
+    "scope": "skill-local",
+    "matchedRule": "skill-local-support",
+    "parentResolution": "missing"
+  },
+  "governance": {
+    "ownership": {
+      "declaredOwner": null,
+      "effectiveOwner": null,
+      "source": "unowned"
+    }
+  }
+}
+```
+
+The resolved example may inherit the owner shown by governance evidence. The
+missing example must not inherit merely because its scope remains
+`skill-local`.
+
+#### Reason Codes
+
+`reasonCode` narrows the primary structural result without replacing
+`matchedRule`. Representative groups are:
+
+- Skill boundary evidence: `under-canonical-skill-root`,
+  `under-skill-support-directory`, `unsupported-skill-local-directory`, and
+  `outside-recognized-skill-boundary`.
+- Independent asset roots: `under-recognized-context-root`,
+  `under-legacy-context-root`, `under-recognized-lens-root`, and
+  `under-recognized-agent-root`.
+- Repository support: `repository-tool-not-context` and
+  `recognized-config-file`.
+- Generic or negative boundary evidence: `under-generic-support-directory`,
+  `outside-recognized-context-root`, and
+  `outside-recognized-asset-boundary`.
+
+Some negative reason codes occur inside `competingRules`, where `matched: false`
+records why a nearby interpretation did not apply. Human-readable `reason`
+wording may improve over time. Machine consumers should branch on
+`matchedRule` and `reasonCode`, retain unfamiliar future values, and never infer
+governance from a reason code alone.
+
+#### Governance and Decision Evidence
+
+Governance is separate from classification. `ownership` reports declared and
+effective owners plus whether the source is `declared`, `inherited`, or
+`unowned`. When available, `policySource`, `policyInheritedFrom`, and
+`metadataState` report equivalent provenance for policy and metadata. A
+resolved parent can still be unowned or have missing policy, so classification
+alone is never enough to construct governance.
+
+Commands that make recommendations expose one of these `decisionStatus`
+values:
+
+| `decisionStatus` | Meaning | Consumer behavior |
+| --- | --- | --- |
+| `deterministic` | Renma has enough supported evidence to construct the reported change candidate. | Review and apply only the reported candidate; do not infer additional changes. |
+| `human-confirmation-required` | Renma constructed candidate evidence, but human intent or semantics must be confirmed before application. | Do not apply until the required human confirmation occurs. |
+| `blocked` | Conflicting, incomplete, unsafe, or unresolved evidence prevents a change recommendation. | Hard stop. Do not apply a patch even if another payload field looks candidate-like. |
+| `no-change-recommended` | Renma successfully determined that no edit is recommended. | Treat as a successful no-edit result; do not manufacture a patch. |
+
+`decisionStatus` is the authoritative application gate. The accompanying
+decision `reasonCode` and `summary` explain that outcome; neither changes the
+structural classification.
+
+#### Safe Consumer Rules
+
+1. Do not infer ownership from `kind`.
+2. Do not infer inheritance from `scope: "skill-local"`.
+3. Require `parentResolution: "resolved"` plus governance evidence before
+   claiming inheritance.
+4. Treat `decisionStatus: "blocked"` as a hard stop.
+5. Treat `decisionStatus: "no-change-recommended"` as a successful no-edit
+   result.
+6. Use `matchedRule` and `reasonCode` for machine branching, not the
+   human-readable `reason`.
+7. Preserve forward compatibility with unknown future enum values. Retain the
+   raw value and fail closed rather than guessing its meaning.
+
+Example additive details:
+
+```json
+{
+  "classification": {
+    "kind": "context",
+    "scope": "independent",
+    "matchedRule": "context-root",
+    "reasonCode": "under-recognized-context-root",
+    "recognizedRoot": "contexts",
+    "ignoredNestedSegments": ["references"],
+    "reason": "The file is under the recognized contexts/** root. The nested references/ segment does not change its classification."
+  }
+}
+```
+
+Adding classification evidence does not emit a finding for every file, change
+diagnostic severity, or change scan pass/fail behavior. Existing
+`requires_human_decision` repair constraints remain the mechanism for intent
+that Renma cannot infer.
+
+`suggestedMode: "no-proposal"` with `no-change-recommended` is a successful
+result, especially for ordinary Skill-local support that inherits governance.
+Suggestion consumers should also handle unknown future `suggestedMode` values
+conservatively. These command-contract refinements do not change scan finding
+severity, scan pass/fail thresholds, or Readiness scoring.
+
 Example:
 
 ```json
@@ -109,6 +362,132 @@ edit shapes. `requires_human_decision` marks ambiguity that should not be guesse
 by automation. `risk` highlights security, data-handling, or destructive-action
 concerns.
 
+## Presenting Renma Evidence to a User
+
+Raw Renma JSON is evidence for an LLM or coding agent, not usually the best
+user-facing explanation. The consumer should translate the relevant fields into
+plain language while preserving the boundary between confirmed facts,
+recommendations, and unresolved human intent.
+
+The overall loop is:
+
+```text
+Renma emits deterministic evidence
+-> LLM summarizes the evidence
+-> user supplies missing intent
+-> LLM performs the smallest supported change
+-> Renma verifies the result
+-> LLM summarizes the new state
+```
+
+In practice, an LLM or coding agent should:
+
+1. Read Renma's deterministic evidence.
+2. Summarize the important facts in user-facing language.
+3. Separate confirmed facts from recommendations and unresolved intent.
+4. Ask only for human decisions that Renma cannot determine.
+5. Rerun the relevant Renma command after the user supplies new intent.
+6. Explain how the evidence or recommendation changed.
+7. Repeat until the intended repository state is explicit and Renma verifies
+   it.
+
+A useful summary normally contains:
+
+- **Confirmed repository facts:** paths, declarations, resolved relationships,
+  and other evidence Renma actually observed.
+- **Renma's deterministic interpretation:** the classification, governance,
+  and decision evidence without added assumptions.
+- **Current recommendation:** the smallest change Renma supports, or an
+  explicit successful no-change result.
+- **Unresolved human decisions:** only intent that repository evidence cannot
+  determine.
+- **Next safe verification step:** the relevant structured Renma command, or a
+  statement that no executable action is safe yet.
+
+For example:
+
+```text
+Renma classified this file as a Skill-local Reference.
+
+One parent Skill resolved at skills/foo/SKILL.md, and the effective owner is
+inherited from that Skill.
+
+No independent metadata change is currently recommended.
+
+A human decision is needed only if this knowledge is intended to be reused
+outside this Skill. If so, consider promoting it to contexts/** and then rerun
+Renma.
+```
+
+LLM consumers must follow these guardrails:
+
+- Do not expose raw diagnostics without summarizing their meaning when a
+  user-facing explanation is expected.
+- Do not ask the user to decide facts Renma already resolved.
+- Do not invent an owner, policy, lifecycle, reference, or source-of-truth
+  claim.
+- Do not convert `structural-candidate` into `resolved`.
+- Do not claim inheritance without `parentResolution: "resolved"` and matching
+  governance evidence.
+- Do not present `decisionStatus: "blocked"` as an applicable patch.
+- Do not assume every diagnostic requires an edit.
+- Do not hide unresolved human intent behind an automatic recommendation.
+- Treat `no-change-recommended` as a valid successful outcome.
+- After new user intent is provided, rerun Renma rather than relying on an old
+  result.
+
+### Iterative Example
+
+Initial Renma evidence:
+
+```text
+kind: reference
+scope: skill-local
+parentResolution: resolved
+decisionStatus: no-change-recommended
+```
+
+LLM summary:
+
+```text
+This file is local support for one Skill and already inherits its governance.
+No metadata change is needed. Should this knowledge remain local, or is it
+intended for reuse by other Skills?
+```
+
+User:
+
+```text
+It should be reusable by three Skills.
+```
+
+LLM response:
+
+```text
+That changes the repository-design intent. I will treat promotion to an
+independent Context Asset as the candidate direction, preserve the original
+meaning, and rerun Renma after the placement and references are updated.
+```
+
+After the intended patch, Renma verifies:
+
+```text
+kind: context
+scope: independent
+matchedRule: context-root
+```
+
+LLM summary:
+
+```text
+The knowledge is now an independent Context Asset under contexts/**. Renma
+verified the new classification. Ownership and references should now be
+reviewed as independent governance rather than inherited Skill-local state.
+```
+
+This example is conceptual. Renma does not automatically move files, invent
+references, or decide that local knowledge should be promoted.
+
 ## Review Bundles
 
 `renma scan --json` also includes `reviewBundles`, a deterministic grouping of
@@ -183,8 +562,9 @@ These diagnostics are emitted after files are parsed into catalog entries. For s
 Owner absence is handled as ownership coverage information. Shared assets
 without `owner` are accepted and reported as unowned by `renma ownership`;
 Renma does not invent an owner. Skill-local support is the exception: it uses
-deterministic effective ownership inherited from its nearest owning Skill and
-reports that provenance separately from declared metadata.
+deterministic effective ownership only after repository evidence resolves one
+parent Skill with an effective owner, and reports that inherited provenance
+separately from declared metadata.
 
 | Severity  | Message                                                                                           | Meaning                                                                                                                        | Fix                                                                                                             |
 | --------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
@@ -215,6 +595,7 @@ Context Lens governance diagnostics use stable `code` values in JSON output. `er
 | `CONTEXT-LENS-GOVERNANCE-MEANINGLESS`      | `warning`            | A lens has no purpose, target, focus, expected output, or body guidance.                                      | Add compact governance metadata or reviewed interpretation guidance.                                    |
 | `CONTEXT-LENS-MISSING-REQUIRED-FIELD`      | `error`              | A lens is missing `id`, `owner`, `purpose`, or `applies_to`.                                                  | Add the required field in frontmatter.                                                                  |
 | `CONTEXT-LENS-PATH-NORMALIZATION-MISMATCH` | `warning`            | A path target normalizes to a different repository-relative path.                                             | Use the normalized path shown by the diagnostic.                                                        |
+| `CONTEXT-LENS-TARGET-NOT-CONTEXT`          | `error`              | An `applies_to` target resolves to a cataloged asset whose kind is not `context`.                             | `applies_to` must reference a Context Asset ID or path; Skills, support assets, other Lenses, and repository metadata are not valid Lens targets. |
 | `CONTEXT-LENS-TARGET-NOT-FOUND`            | `error`              | An `applies_to` target does not resolve to a cataloged asset ID or path.                                      | Correct the target, add the missing context asset, or update discovery config.                          |
 | `CONTEXT-LENS-UNPARSEABLE-FRONTMATTER`     | `error`              | A lens frontmatter block starts with `---` but does not close.                                                | Add the closing `---` delimiter or remove malformed frontmatter.                                        |
 | `CONTEXT-LENS-UNSUPPORTED-KIND`            | `warning` or `error` | `type: context_lens` appears under an unsupported artifact kind, or a lens file declares an unsupported type. | Store lens definitions under `lenses/**`, `context/**`, or `contexts/**`, and use `type: context_lens`. |
@@ -347,7 +728,8 @@ examples by asset kind.
 | `QUAL-SKILL-MIXED-RESPONSIBILITY`                | Skill may mix workflow and reusable knowledge.       | A sufficiently large Skill has multiple distinct reusable-knowledge signals.                       | Promote only independently owned shared knowledge; keep Skill-local workflow and detail local.         |
 | `QUAL-SKILL-PROGRESSIVE-DISCLOSURE`              | Progressive disclosure needs review.                 | Reserved 0.18 focused-workflow contract identifier.                                                | Keep read conditions and core workflow in `SKILL.md`; place details by semantic responsibility.        |
 | `QUAL-SKILL-TOKEN-BUDGET`                        | Skill body exceeds an advisory estimate.             | Markdown body exceeds 2,000 or 5,000 estimated tokens.                                             | Review progressive disclosure without splitting or moving content by size alone.                       |
-| `QUAL-SUPPORT-ASSET-TOKEN-BUDGET`                | Support asset exceeds an advisory estimate.          | A context, reference, profile, or example exceeds its token budget.                                | Review coherent scope, structure, read conditions, reference depth, responsibility mixing, and duplication; size alone does not require a split. |
+| `QUAL-INVALID-TOKEN-BUDGET-OVERRIDE`             | Support-asset decision metadata is invalid.           | The decision is malformed, unsafe to represent exactly, ambiguous, incomplete, orphaned, duplicated, or unnecessary while the asset remains within its default. | Correct or remove the declaration. Ask about a meaningful split first; use an override only after the user confirms the asset should remain intentionally long. |
+| `QUAL-SUPPORT-ASSET-TOKEN-BUDGET`                | Support asset exceeds its effective advisory estimate. | A context, reference, profile, or example exceeds its default or valid declared override.          | Ask whether a semantic split preserves coherence and execution order. Split only with user agreement; otherwise record an explicit rationale, never an override added merely to pass diagnostics. |
 | `QUAL-USER-LOCAL-PATHS`                          | User-local path appears in content.                  | Guidance includes machine-specific paths such as home directories.                                 | Replace local paths with repository-relative or configurable paths.                                    |
 | `SEC-DESTRUCTIVE-COMMAND`                        | Destructive command appears.                         | Content includes risky commands such as forced deletion or reset.                                  | Remove it, gate it with explicit safety guidance, or use a safer command.                              |
 | `SEC-ENV-COPY`                                   | Environment copying is suggested.                    | Content copies broad environment or secret-bearing files.                                          | Narrow the copied data and document secret handling.                                                   |

package/docs/metadata-budget.md

@@ -4,11 +4,43 @@ Renma intentionally keeps asset frontmatter small. Frontmatter should work as a
 
 Use frontmatter for concise fields such as `id`, `owner`, `status`, `tags`, `when_to_use`, `when_not_to_use`, and declared context relationships. Put detailed guidance, examples, procedures, policy rationale, and long routing prose in the markdown body or in referenced context assets.
 
+Contexts, references, profiles, and examples also support these top-level
+human-decision fields:
+
+```yaml
+token_budget_override: 6000
+token_budget_rationale: "This is a single ordered workflow and splitting it would break execution order."
+token_budget_reviewed_at: "2026-07-12"
+```
+
+`token_budget_override` must be a positive safe integer greater than the asset
+kind's default content limit, and `token_budget_rationale` must be a non-empty
+string. `token_budget_reviewed_at` is optional and must be a real `YYYY-MM-DD`
+date when present. Invalid metadata does not replace the default limit.
+The three fields form one decision bundle: rationale and review-date fields are
+invalid without an override. Duplicate fields, relevant YAML errors, and an
+override declared while the full file remains within its default limit also
+produce `QUAL-INVALID-TOKEN-BUDGET-OVERRIDE`. Renma selects no value from an
+ambiguous or invalid bundle, and catalog output omits all three normalized
+fields.
+
+These fields record a declared human decision; Renma never inserts them. When
+the default is exceeded, first ask whether the asset can be split along
+meaningful semantic boundaries without harming coherence or execution order.
+Split only after the user agrees. Use an override only when the user confirms
+the asset should remain intentionally long, and never recommend one merely to
+make diagnostics pass.
+
+Renma records and validates this declaration; it cannot prove that a human
+actually reviewed the asset. `token_budget_reviewed_at` is declared provenance,
+not independently verified evidence.
+
 Current metadata budget diagnostics:
 
 | Finding | Meaning | Typical fix |
 | --- | --- | --- |
 | `META-FRONTMATTER-TOO-LARGE` | Frontmatter has grown beyond the compact index budget. | Move long prose, examples, procedures, or rationale into the body or referenced context assets. |
 | `META-LIST-ITEM-TOO-LONG` | A block-list metadata item is too long to serve as concise routing/index metadata. | Keep the list item short and move detailed conditions into body sections. |
+| `QUAL-INVALID-TOKEN-BUDGET-OVERRIDE` | Support-asset token-budget decision metadata is invalid or ambiguous. | Correct or remove it after an explicit user decision; invalid metadata leaves the default content limit active. |
 
 These diagnostics are intentionally advisory. They should help reduce LLM-facing catalog noise and token usage without deleting substantive knowledge.

package/docs/quality-profile.md

@@ -5,7 +5,7 @@ the active profile as `renma-quality@<Renma package version>`, derived from
 `package.json` at build time. The source is `src/quality-profile.ts`. The current
 implementation does not expose quality overrides in `renma.config.json`; fixed
 defaults preserve comparable repository reports. The internal shape is
-versioned so later releases can add reviewed overrides without scattering
+versioned so later releases can add declared overrides without scattering
 constants across rules.
 
 `estimated_tokens` means Renma's deterministic, model-neutral estimate. Latin
@@ -14,6 +14,18 @@ grouped in two-code-point units; other punctuation is grouped in units of up to
 three code points. It is not an exact token count for any model. Skill budgets
 measure Markdown after frontmatter. Content-asset budgets measure the full file.
 
+Contexts, references, profiles, and examples may record a declared human
+decision and effective limit with top-level `token_budget_override` and
+`token_budget_rationale` metadata. The override must be a positive safe integer
+greater than the asset kind's unchanged default. Optional
+`token_budget_reviewed_at` must be a real `YYYY-MM-DD` date. Renma does not add
+these fields automatically. When an asset exceeds its default, an agent should
+first ask whether it can be split along meaningful boundaries without harming
+coherence or execution order, and split only after the user agrees. An override
+is appropriate only when the user confirms the long-form asset is intentionally
+coherent or ordered; it is not a general ignore mechanism. Renma validates the
+declaration but cannot prove that human review occurred.
+
 ## Agent Skills requirements and recommendations
 
 | Field | Value | Unit and trigger | Severity | Source | Rationale and false-positive risk | Diagnostic | Reviewed | Configurable later |
@@ -39,10 +51,10 @@ and `assets/` directories are valid. See the official
 | `descriptionMinChars` | 0 | characters; disabled | none | Renma | Length does not establish selection clarity | `QUAL-SHORT-DESCRIPTION` removed from default behavior | 0.18.0 | possibly |
 | `skillTokenWarn` | 2,000 | `estimated_tokens`; body above | low | Renma | Early progressive-disclosure review; focused workflows may exceed it | `QUAL-SKILL-TOKEN-BUDGET` | 0.18.0 | possibly |
 | `skillTokenStrongWarn` | 5,000 | `estimated_tokens`; body above | medium | Agent Skills recommendation with Renma severity | Stronger review, not a required split | `QUAL-SKILL-TOKEN-BUDGET` | 0.18.0 | possibly |
-| `contentTokenWarn.context` | 4,000 | `estimated_tokens`; full file above | low | Renma | Review coherent scope; size alone is insufficient | `QUAL-SUPPORT-ASSET-TOKEN-BUDGET` | 0.18.0 | possibly |
-| `contentTokenWarn.reference` | 5,000 | same | low | Renma | Detailed local references may legitimately be long | same | 0.18.0 | possibly |
-| `contentTokenWarn.profile` | 2,000 | same | low | Renma | Profiles should remain reviewable overlays | same | 0.18.0 | possibly |
-| `contentTokenWarn.example` | 2,500 | same | low | Renma | Complete examples may legitimately be long | same | 0.18.0 | possibly |
+| `contentTokenWarn.context` | 4,000 | `estimated_tokens`; full file above effective limit | low | Renma | Prefer an agreed semantic split when coherence survives; intentionally coherent or ordered assets may record a declared decision | `QUAL-SUPPORT-ASSET-TOKEN-BUDGET` | 0.18.1 | metadata only after human decision |
+| `contentTokenWarn.reference` | 5,000 | same | low | Renma | Detailed local references may legitimately be long | same | 0.18.1 | same |
+| `contentTokenWarn.profile` | 2,000 | same | low | Renma | Profiles should remain reviewable overlays | same | 0.18.1 | same |
+| `contentTokenWarn.example` | 2,500 | same | low | Renma | Complete examples may legitimately be long | same | 0.18.1 | same |
 | `lowHeadingDensityMinTokens` | 400 | body `estimated_tokens`, with fewer than 2 headings | low | Renma | Long prose can still be intentionally linear | `QUAL-LOW-HEADING-DENSITY` | 0.18.0 | possibly |
 | `lowHeadingDensityMinHeadings` | 2 | headings | low | Renma | Navigation heuristic only | same | 0.18.0 | possibly |