renma 0.17.0 → 0.18.1

package/CHANGELOG.md

@@ -6,6 +6,155 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [Unreleased]
 
+## [0.18.1] - 2026-07-13
+
+### Added
+
+- Added `token_budget_override`, `token_budget_rationale`, and optional
+  `token_budget_reviewed_at` metadata for recording a declared human decision
+  that a support asset should remain intentionally long. Invalid, ambiguous,
+  incomplete, orphaned, or unnecessary decision metadata emits
+  `QUAL-INVALID-TOKEN-BUDGET-OVERRIDE` and never suppresses the default budget.
+  Only Markdown-parser-eligible support assets can declare the bundle, and
+  override limits must be positive safe integers represented exactly.
+- Added the blocking `CONTEXT-LENS-TARGET-NOT-CONTEXT` diagnostic.
+  Context Lens `applies_to` targets must now resolve specifically to Context
+  Assets; Skills, support assets, and other Context Lenses are rejected.
+
+### Changed
+
+- Changed support-asset token guidance to ask for a split-versus-intentionally-
+  long user decision. Semantic splitting remains preferred when it preserves
+  coherence and execution order; a valid declared decision provides an
+  effective limit for intentionally coherent or ordered long-form assets.
+- Clarified Skill, Context Asset, Context Lens, Skill-local support, and
+  external runtime responsibilities across canonical documentation, CLI help,
+  scaffolds, and examples. Context Lens guidance now requires declared Context,
+  rejects persona-only authoring as insufficient, uses canonical Agent Skills
+  relationship metadata, and preserves focused workflows without changing
+  Renma's deterministic runtime boundary.
+
+## [0.18.0] - 2026-07-12
+
+### Added
+
+- Added the internal `renma-quality` profile family. The emitted profile
+  identifier is derived from the Renma package version as
+  `renma-quality@<package version>`. Added canonical threshold documentation
+  with units, provenance, rationale, false-positive risks, and
+  future-configurability status.
+- Added one deterministic Unicode-aware `estimated_tokens` implementation for
+  Skill, content-asset, reuse-candidate, and repeated-context analysis.
+- Added first-class `script` and `asset` artifact kinds under both supported
+  Skill roots, including original-byte hashes, sizes, text/binary
+  classification, Markdown eligibility, and catalog, graph, Trust Graph, and
+  BOM inventory.
+- Added direct, one-index-hop, deep-chain, unreachable, and missing-path static
+  support reachability for references, scripts, assets, profiles, and examples.
+- Added `renma scaffold skill --resources references,scripts,assets`; file mode
+  creates only selected empty directories, while prompt and JSON modes report
+  the selected resource contract without writing files.
+- Added BOM and Trust Graph v2 as the first supported long-term schema
+  contracts. Renma 0.18.0 does not provide a v1 compatibility mode; the
+  earlier experimental v1 surface was removed before broader adoption.
+- Added normalized ownership provenance and static local-resource relationship
+  edges across catalog, graph, readiness, BOM, and Trust Graph output.
+
+### Changed
+
+- Replaced the thin-router model with focused workflow entrypoints. Ordered
+  procedures, completion criteria, and short command examples are valid in
+  `SKILL.md`; progressive disclosure is reviewed by semantic destination.
+- Changed Skill body advisories to low above 2,000 and medium above 5,000
+  estimated tokens. Changed content advisories to Context 4,000, Reference
+  5,000, Profile 2,000, and Example 2,500 estimated tokens.
+- Changed metadata advisories to 48 frontmatter lines, 4,096 frontmatter
+  characters, and 256 characters per prose-like list item, with practical
+  exemptions for IDs, repository paths, and URLs.
+- Changed reusable Context eligibility to 60 lines or 800 estimated tokens plus
+  four reusable signals. Changed shared-reference eligibility to 80 lines or
+  1,200 estimated tokens plus three reusable headings and four reusable
+  phrases. Ordinary workflow headings and constraint words do not qualify.
+- Changed repeated headings to require three files and token shingles to 40
+  estimated tokens in three files. Exact-section, exact-code, and per-category
+  caps retain their established defaults.
+- Changed Readiness to `workflow.skills_focused`, removed the five-point
+  existence penalty for deprecated/archived assets, and reduced subjective
+  workflow advisory weights while preserving blocking graph and diagnostic
+  failures.
+- Deprecated `metadata.renma.when-to-use` and
+  `metadata.renma.when-not-to-use` for new Skill authoring. They remain
+  recognized for governance and migration preservation; portable
+  `description` is the Skill discovery source of truth.
+
+### Fixed
+
+- Stopped overcounting Japanese one character at a time in quality rules and
+  undercounting unspaced Japanese as one token in repeated-context analysis.
+- Stopped decoding images, PDFs, fonts, and other opaque assets as UTF-8
+  Markdown or exposing binary bytes in diagnostic snippets.
+- Stopped non-Markdown text scripts and assets from contributing frontmatter,
+  headings, links, fences, or repeated-context evidence.
+- Fixed nearest-Skill support ownership, nested Skill boundaries, explicit path
+  reachability, extensionless and spaced paths, and oversized-file existence
+  evidence.
+- Prevented script and asset bytes from declaring policy. Skill-local scripts
+  and assets inherit the nearest unambiguous Skill policy; text scripts may be
+  scanned under it, while binary files and ordinary output assets stay opaque.
+- Rejected files reached through leaf or ancestor symbolic links, including
+  Skill-local directory links that point elsewhere inside or outside the
+  repository.
+- Scanned non-Markdown scripts from line 1 even when they begin with `---`, and
+  added explicit local, inherited, effective, and missing-effective policy
+  inventory provenance.
+- Added balanced-parenthesis Markdown destination parsing and single-pass
+  decoding for encoded filename characters.
+- Stopped treating a command, Procedure/Steps/Setup headings, ordered workflow
+  wording, or 450/700-word counts as evidence of a bad Skill.
+- Stopped recommending Context Assets as the default destination for
+  Skill-specific procedures, variants, edge cases, scripts, and output
+  resources.
+- Stopped repeated links to the same specification or source from producing
+  maintenance findings by default.
+
+### Removed
+
+- Removed default emission of `QUAL-SHORT-DESCRIPTION`,
+  `LAYOUT-SKILL-NOT-THIN`, `LAYOUT-SKILL-EXECUTABLE-COMMAND`, and
+  `MAINT-REPEATED-LINK`.
+- Removed the Readiness `layout.skills_thin` contract and the unconditional
+  lifecycle-status penalty.
+
+### Compatibility
+
+- No public quality-threshold configuration was added to
+  `renma.config.json`. The versioned internal profile is shaped for possible
+  later overrides after usage evidence.
+- `ArtifactKind`, catalog entries, graph nodes, Trust Graph asset properties,
+  and Repository Context BOM assets add `script`/`asset` and binary-safety
+  evidence. Consumers that exhaustively match kinds or exact-normalize these
+  schemas must update for 0.18.0.
+- Scaffold file, prompt, and JSON contracts add selected resource directories;
+  existing invocations without `--resources` create no extra directories.
+- Agent Skills specification errors remain separate from Renma advisories:
+  `description` is required, a string, and 1-1,024 characters; 150 characters
+  is not an Agent Skills minimum.
+
+### Migration
+
+- `LAYOUT-SKILL-NOT-THIN` -> `QUAL-SKILL-MIXED-RESPONSIBILITY` when reusable
+  knowledge evidence exists, otherwise no finding.
+- `LAYOUT-SKILL-EXECUTABLE-COMMAND` -> no layout finding; security,
+  unresolved-helper, path-escape, and large-inline-implementation checks remain.
+- `QUAL-SHORT-DESCRIPTION` -> Agent Skills description validity plus
+  `RN-SKILL-DESCRIPTION-MISSING-CAPABILITY`,
+  `RN-SKILL-DESCRIPTION-MISSING-USAGE-BOUNDARY`, and
+  `RN-SKILL-DESCRIPTION-OMITS-SELECTION-BOUNDARY` where applicable.
+- `MAINT-REPEATED-LINK` -> no maintenance finding by default.
+- Readiness `layout.skills_thin` -> `workflow.skills_focused`.
+- Rebaseline exact catalog, graph, Trust Graph, BOM, Readiness, scaffold JSON,
+  and package-content fixtures against the 0.18.0 schemas before release.
+
 ## [0.17.0] - 2026-07-11
 
 ### Added
@@ -343,7 +492,9 @@ Tag-only release. No GitHub Release entry was published for this version.
 - Added metadata governance, advisory diagnostics, local path checks, and semantic split suggestions.
 - Added the initial project documentation, architecture notes, package metadata, tests, and license.
 
-[Unreleased]: https://github.com/KazuCocoa/renma/compare/v0.17.0...HEAD
+[Unreleased]: https://github.com/KazuCocoa/renma/compare/v0.18.1...HEAD
+[0.18.1]: https://github.com/KazuCocoa/renma/compare/v0.18.0...v0.18.1
+[0.18.0]: https://github.com/KazuCocoa/renma/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/KazuCocoa/renma/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/KazuCocoa/renma/compare/v0.15.2...v0.16.0
 [0.15.2]: https://github.com/KazuCocoa/renma/compare/v0.15.1...v0.15.2

package/README.md

@@ -125,6 +125,11 @@ scaffold, or ask it to use `renma scaffold skill` as its starting point.
 The [Authoring Guide](docs/authoring-guide.md) is the canonical walkthrough for
 both workflows.
 
+Renma 0.18.x uses focused workflows rather than a thin-router model. See the
+[canonical quality profile](docs/quality-profile.md) for every fixed threshold,
+unit, rationale, provenance, and diagnostic mapping. Quality thresholds are not
+configurable through `renma.config.json` in this release.
+
 ## Install And Quick Start
 
 Run Renma without installing it globally:
@@ -214,6 +219,8 @@ lenses/
 This is an illustrative layout, not a required domain hierarchy. `contexts/`
 is preferred and `context/` remains supported. Skill-local `references/`,
 `assets/`, `scripts/`, `examples/`, and `profiles/` are valid support material.
+Local support without a declared owner inherits effective ownership from its
+nearest owning Skill; reports distinguish inherited ownership from declarations.
 When deterministic evidence shows that knowledge is reusable beyond one Skill,
 promote it to an owned Context Asset rather than moving it based on location
 alone.
@@ -260,12 +267,15 @@ canonical and migration rules.
 - [Authoring Guide](docs/authoring-guide.md)
 - [Agent Skills Compatibility and Migration](docs/agent-skills-compatibility.md)
 - [Diagnostics Reference](docs/diagnostics.md)
+- [Renma Quality Profile](docs/quality-profile.md)
 - [Security Policy Guide](docs/security-policy.md)
 - [Repository Context BOM contract](docs/repository-context-bom.md)
 - [Architecture](architecture.md)
 - [Product Design](design.md)
 - [Current Roadmap](plan.md)
-- [Proposed 0.18.0 Skill Discovery](plan-discovery.md)
+- [Deferred Skill-to-Skill Discovery Design](plan-discovery.md): unassigned
+  exploratory route/index design, separate from implemented repository and
+  support-resource discovery.
 - [Interactive Placeholder Example](examples/interactive-placeholder): minimal
   hands-on clarify-before-act Skill interaction with a local tool.
 - [Example Context Repository](examples/context-repo): richer repository-aware

package/architecture.md

@@ -36,7 +36,7 @@ assemble prompts, or execute workflows. Agents and runtimes decide how to use
 repository assets for a task. Future evidence validation does not make Renma a
 runtime telemetry collector; signal production and collection remain external.
 
-Provenance remains repository-level. A Repository Context BOM is a manifest of declared assets, hashes, owners, lifecycle states, dependencies, security posture, diagnostics, and readiness evidence; it is not a report of actual LLM runtime usage. BOM v1 keeps Git revision identity in the surrounding Git/CI/PR artifact context and keeps any future consumed-context evidence separate from the declared repository manifest contract.
+Provenance remains repository-level. Repository Context BOM v2 is a manifest of declared assets, hashes, owners, lifecycle states, dependencies, security posture, diagnostics, and readiness evidence; it is not a report of actual LLM runtime usage. BOM v2 keeps Git revision identity in the surrounding Git/CI/PR artifact context and keeps any future consumed-context evidence separate from the declared repository manifest contract.
 
 ## Goals
 
@@ -121,12 +121,13 @@ that local support should be promoted.
 
 ### Skill
 
-A Skill is an agent-facing entrypoint, routing contract, and usage guide. It
-tells a consuming agent when and how to use a capability, what preflight
-questions matter, which safety and verification steps apply, and which Context
-Assets or Context Lenses are relevant. Renma recognizes Agent Skills-compatible
-syntax as the portable authoring boundary without reducing its internal model
-to the Agent Skills data model.
+A Skill is a focused task or workflow entrypoint. It tells a consuming agent
+when the workflow applies, which inputs and preflight questions matter, what
+ordered instructions and decisions to follow, which safety and verification
+steps apply, what output completes the work, and which Context Assets or
+Context Lenses are relevant. Renma recognizes Agent Skills-compatible syntax as
+the portable authoring boundary without reducing its internal model to the
+Agent Skills data model.
 
 A skill should not be the only source of truth for reusable expert knowledge.
 
@@ -162,11 +163,21 @@ Normalized asset kinds:
 - `profile`
 - `reference`
 - `example`
+- `script`
+- `asset`
 - `agent`
 - `config`
 - `unknown`
 
-Shared Markdown under `contexts/` or `context/` uses the dedicated `context` kind. Skill-local supporting material remains `reference`.
+Shared Markdown under `contexts/` or `context/` uses the dedicated `context`
+kind. Skill-local scripts and assets are first-class inventory. Repository files
+carry original-byte size and hash, text or binary classification, and Markdown
+parser eligibility. Only artifacts explicitly eligible for Markdown parsing
+contribute frontmatter, headings, links, fences, or repeated-context evidence.
+Opaque files are never decoded into diagnostic snippets. Skill-local support
+inherits effective ownership from its nearest owning Skill when it has no local
+owner; catalog, graph, ownership, Readiness, Trust Graph, and BOM retain
+`inherited` provenance instead of presenting that owner as locally declared.
 
 ### Dependency
 
@@ -457,7 +468,7 @@ Consumed-context evidence from external agents, editor integrations, prompt wrap
 
 The scanner, normalized asset model, graph-backed governance, ownership,
 Readiness, repeated-context evidence, semantic diff, security diagnostics,
-Trust Graph, and Repository Context BOM v1 are implemented architecture. New
+Trust Graph v2 and Repository Context BOM v2 are implemented architecture. New
 projections should reuse the shared repository-evidence snapshot and remain
 additive unless a separately versioned contract requires a breaking change.
 
@@ -507,7 +518,7 @@ Baseline now in place:
   references, profiles, and examples.
 - Security diagnostics, security posture summaries, and effective policy
   inventory for agent-facing repository content.
-- Trust Graph evidence and Repository Context BOM v1.
+- Trust Graph v2 evidence and Repository Context BOM v2.
 - CI integration examples and optional LLM-assisted review bundles.
 
 Future work may add imported external evidence after its contract is defined;

package/design.md

@@ -23,7 +23,7 @@ what context an agent should load at task time.
 
 ```mermaid
 flowchart LR
-  Skill["Skill: agent-facing entrypoint, routing contract, usage guide"]
+  Skill["Skill: focused task and workflow"]
   Lens["Context Lens: purpose-oriented interpretation"]
   Asset["Context Asset: independently owned source-of-truth knowledge"]
   Skill -->|may reference| Lens
@@ -31,9 +31,10 @@ flowchart LR
   Lens -->|interprets| Asset
 ```
 
-Skills tell an agent when and how to use a capability. They can reference
-context assets, ask preflight questions, describe safety gates, and define
-verification expectations.
+Skills define a focused task or workflow. They can own activation boundaries,
+inputs, ordered instructions, decisions, constraints, short commands, examples,
+edge cases, verification, output, and completion criteria. They can also declare
+Context Asset and Context Lens relationships.
 
 Context assets hold reusable expertise. They should be maintainable outside a
 single skill, owned by the right team, versioned, reviewed, and reused across
@@ -87,9 +88,9 @@ policy, security profile resolution, allowed data, forbidden inputs, approved
 network and upload destinations, human approval requirements, and high-risk
 findings without enforcing runtime behavior.
 
-Trust Graph v1 is a deterministic interpretation of existing catalog, graph, scan, and security evidence. It exposes stable asset, owner, lifecycle, dependency, security profile, effective policy, and diagnostic evidence, but it does not introduce subjective trust scores or a separate runtime system. `scan` lists concrete problems, `graph` shows structural relationships, `trust-graph` connects trust-relevant evidence, and `readiness` summarizes repository-level preparedness.
+Trust Graph v2 is a deterministic interpretation of existing catalog, graph, scan, and security evidence. It exposes stable asset, owner, lifecycle, dependency, security profile, compositional effective-policy provenance, and diagnostic evidence, but it does not introduce subjective trust scores or a separate runtime system. `scan` lists concrete problems, `graph` shows structural relationships, `trust-graph` connects trust-relevant evidence, and `readiness` summarizes repository-level preparedness.
 
-Repository Context BOM v1 is a declared repository evidence snapshot: assets, hashes, owners, lifecycle states, dependencies, security posture, diagnostics, and readiness evidence. Snapshot consistency comes from one in-memory repository snapshot per BOM execution, not output formatting flags. `--omit-generated-at` only removes run-time generation timestamp noise; it does not ignore repository metadata timestamps such as `lastReviewedAt` or `expiresAt`, suppress freshness diagnostics, normalize environment-dependent absolute paths such as `root` or `configPath`, hide file moves, or provide portable byte-for-byte output across runners. The BOM does not claim actual LLM runtime usage. Actual consumed-context evidence remains a future separate artifact or attachment that external agents or wrappers may produce and Renma may later validate against the repository model. See `docs/repository-context-bom.md` for the resolved v1 contract.
+Repository Context BOM v2 is a declared repository evidence snapshot: assets, hashes, owners, lifecycle states, dependencies, security posture, diagnostics, and readiness evidence. Snapshot consistency comes from one in-memory repository snapshot per BOM execution, not output formatting flags. `--omit-generated-at` only removes run-time generation timestamp noise; it does not ignore repository metadata timestamps such as `lastReviewedAt` or `expiresAt`, suppress freshness diagnostics, normalize environment-dependent absolute paths such as `root` or `configPath`, hide file moves, or provide portable byte-for-byte output across runners. The BOM does not claim actual LLM runtime usage. Actual consumed-context evidence remains a future separate artifact or attachment that external agents or wrappers may produce and Renma may later validate against the repository model. See `docs/repository-context-bom.md` for the v2 contract.
 
 Renma findings should be useful not only to humans, but also to LLM coding
 agents. A good Renma diagnostic should explain what is wrong, why it matters for
@@ -104,34 +105,36 @@ Current diagnostics include evidence, `whyItMatters`, remediation, typed repair
 constraints, verification steps, and LLM-facing hints where applicable. These
 fields remain deterministic rule output, not LLM-generated validation.
 
-Example diagnostic shape:
+Example diagnostic shape (selected stable fields from a deterministic fixture;
+input-specific `details` omitted):
 
 ```json
 {
-  "id": "RMA-SKILL-TOO-MONOLITHIC",
-  "severity": "medium",
-  "category": "structure",
-  "title": "Skill mixes reusable knowledge with usage guidance",
+  "id": "QUAL-SKILL-MIXED-RESPONSIBILITY",
+  "severity": "low",
+  "category": "maintenance",
+  "confidence": "medium",
+  "title": "Skill may mix its workflow with reusable knowledge",
   "evidence": {
-    "path": "skills/testing/test-case-generation/SKILL.md",
-    "startLine": 42,
-    "endLine": 78,
-    "snippet": "boundary value analysis"
+    "path": "skills/mobile/SKILL.md",
+    "startLine": 11,
+    "endLine": 11,
+    "snippet": "Detected reusable-knowledge headings: Platform Facts - Known Issues - Domain Rules - Product Policy; Detected reusable-knowledge phrases: known issue"
   },
-  "whyItMatters": "Reusable QA and domain knowledge should be owned, reviewed, and reused as shared context assets instead of being buried in one skill.",
-  "remediation": "Split reusable knowledge into first-class shared context assets and keep the skill as an LLM-facing usage guide.",
+  "whyItMatters": "Reusable setup notes, troubleshooting, platform guidance, testing heuristics, or domain rules are easier to own, review, and reuse when they live in shared context assets instead of only inside one skill.",
+  "remediation": "Review the matched headings and phrases. Promote content to contexts/ only when it needs cross-Skill reuse, independent ownership, lifecycle, or source-of-truth status; otherwise keep Skill-specific detail in SKILL.md or references/.",
   "constraints": [
-    "Do not introduce task context selection.",
-    "Do not create prompt packages.",
-    "Keep the skill as a routing contract / usage guide.",
-    "Each context asset should have id, owner, status, and short scope."
+    "Do not make Renma select runtime context.",
+    "Do not assemble prompt packages.",
+    "Do not automatically rewrite or split skills.",
+    "Preserve SKILL.md as a focused workflow entrypoint.",
+    "Give extracted context assets stable metadata such as id, owner, and status."
   ],
   "verificationSteps": [
     "Run renma scan.",
-    "Run any project-specific validation checks that apply to this repository.",
-    "Ensure the skill no longer mixes reusable domain knowledge with usage guidance."
+    "Confirm the advisory is resolved or intentionally accepted after reusable knowledge is represented as shared context assets."
   ],
-  "llmHint": "Create shared context assets for reusable QA knowledge, update skill metadata, and preserve the skill as a concise usage guide."
+  "llmHint": "Check whether the matched knowledge is used across Skills or needs independent ownership. Use contexts/ only for shared knowledge; keep Skill-local procedures and edge cases in SKILL.md or references/."
 }
 ```
 
@@ -139,11 +142,12 @@ Central repair workflow:
 
 1. A single `SKILL.md` contains reusable domain knowledge, tool guidance, and
    QA heuristics.
-2. Renma emits structured findings explaining that the skill is too monolithic
-   and mixes usage guidance with reusable context.
+2. Renma detects reusable-knowledge signals and reports possible mixed
+   responsibility. The finding does not require every matched detail to move.
 3. Codex or Claude reads the diagnostics and proposes a patch that moves
-   reusable knowledge into first-class context assets under `contexts/`, keeps
-   the skill concise, adds metadata, and updates declared context references.
+   knowledge into `contexts/` only when it needs cross-Skill reuse, independent
+   ownership, lifecycle, or source-of-truth status. Skill-specific workflow and
+   detail remain in `SKILL.md` or Skill-local References.
 4. A human reviews the patch.
 5. Renma scans the repository again and confirms the skill/context separation is
    healthier.
@@ -214,11 +218,13 @@ as a compatibility alias. Files under either root are classified as the
 can live under `lenses/`, or context files can opt in with `type: context_lens`.
 
 Skill-local `assets/`, `profiles/`, `references/`, `examples/`, and `scripts/`
-remain supported. They are useful for local routing variants, nearby examples,
-Skill-specific supporting text, fixtures, and helpers. When evidence shows that
-knowledge is reusable across Skills, teams, tools, or agents, it should move
-into `contexts/` as an owned Context Asset. Shared helper implementations may
-move to `tools/**`; location alone does not require either promotion.
+remain supported. They are useful for local workflow variants, nearby examples,
+Skill-specific supporting text, fixtures, and helpers. Profiles represent
+Skill-local overlays or workflow variants; they are not generic global
+personas. When evidence shows that knowledge is reusable across Skills, teams,
+tools, or agents, it should move into `contexts/` as an owned Context Asset.
+Shared helper implementations may move to `tools/**`; location alone does not
+require either promotion.
 
 Renma can also flag large skill-local support files as shared-context candidates when they contain generic source-of-truth structure such as setup, decision logic, troubleshooting, validation, constraints, policy, or procedure guidance. This advisory does not decide semantic reuse itself. It surfaces structurally broad support files and asks the calling LLM or human to inspect the repository for similar concepts, overlapping guidance, and reuse opportunities before making a reviewable patch.
 
@@ -228,17 +234,29 @@ Shared context assets should be organized by semantic scope, not migration state
 
 Renma normalizes scanned files into asset kinds:
 
-- `skill`: LLM-facing entrypoint, routing contract, and usage guide
+- `skill`: focused task or workflow with activation boundaries, instructions,
+  verification, output, and completion criteria
 - `context`: shared source-of-truth knowledge asset under `contexts/` or
   `context/`
 - `context_lens`: purpose-oriented interpretation layer over context assets
 - `profile`: skill-local overlay or variant
 - `reference`: skill-local supporting material
 - `example`: skill-local example or fixture text
+- `script`: Skill-local deterministic executable implementation
+- `asset`: Skill-local template, image, data, font, PDF, or output resource
 - `agent`: repository or agent instruction file
 - `config`: Renma configuration
 - `unknown`: scanned file that does not match a known kind
 
+Catalog, graph, Trust Graph, and BOM output include script and asset inventory.
+Each cataloged asset records original-byte size and hash, text/binary
+classification, and Markdown-parser eligibility. Binary assets remain opaque;
+Renma does not decode them as UTF-8 or expose their bytes in snippets.
+Non-Markdown text remains available to dedicated path and security analysis but
+cannot declare catalog metadata or contribute Markdown structure. Skill-local
+support without a local owner inherits effective ownership from the nearest
+Skill, with inherited provenance exposed in normalized reports.
+
 The dedicated `context` kind is central to the product model. It lets catalog,
 graph, and validation output distinguish reusable team-owned knowledge from
 skill-local reference material.

package/dist/agent-skills.d.ts

@@ -2,7 +2,7 @@ import { type AgentSkillDiagnosticId } from "./diagnostic-ids.js";
 import type { ParsedDocument } from "./types.js";
 import { type ParsedYamlFrontmatter } from "./yaml-frontmatter.js";
 export declare const AGENT_SKILLS_SPECIFICATION = "https://agentskills.io/specification";
-export declare const AGENT_SKILLS_VALIDATION_PROFILE = "agentskills.io/specification@2026-07-11";
+export declare const AGENT_SKILLS_VALIDATION_PROFILE = "agentskills.io/specification@2026-07-12";
 export declare const AGENT_SKILLS_TOP_LEVEL_FIELDS: readonly ["name", "description", "license", "compatibility", "metadata", "allowed-tools"];
 export declare const LEGACY_RENMA_SKILL_FIELDS: readonly ["id", "title", "version", "owner", "status", "purpose", "last_reviewed_at", "review_cycle", "expires_at", "tags", "when_to_use", "when_not_to_use", "requires_context", "optional_context", "requires_lens", "optional_lens", "conflicts", "superseded_by", "allowed_data", "network_allowed", "external_upload_allowed", "secrets_allowed", "requires_human_approval", "forbidden_inputs", "approved_network_destinations", "approved_upload_destinations", "security_profile"];
 export type AgentSkillFormat = "agent-skills" | "renma-legacy" | "hybrid" | "unknown";

package/dist/agent-skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-skills.d.ts","sourceRoot":"","sources":["../src/agent-skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-skills.d.ts","sourceRoot":"","sources":["../src/agent-skills.ts"],"names":[],"mappings":"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"}

package/dist/agent-skills.js

@@ -1,9 +1,11 @@
 import path from "node:path";
+import { logicalSkillDirectory } from "./discovery.js";
 import { AGENT_SKILL_DIAGNOSTIC_IDS as IDS, } from "./diagnostic-ids.js";
 import { classifyRepositorySkillEntrypointPath } from "./discovery.js";
 import { parseAgentSkillFrontmatter, } from "./yaml-frontmatter.js";
+import { DEFAULT_QUALITY_PROFILE } from "./quality-profile.js";
 export const AGENT_SKILLS_SPECIFICATION = "https://agentskills.io/specification";
-export const AGENT_SKILLS_VALIDATION_PROFILE = "agentskills.io/specification@2026-07-11";
+export const AGENT_SKILLS_VALIDATION_PROFILE = "agentskills.io/specification@2026-07-12";
 export const AGENT_SKILLS_TOP_LEVEL_FIELDS = [
     "name",
     "description",
@@ -43,9 +45,10 @@ export const LEGACY_RENMA_SKILL_FIELDS = [
 ];
 const ALLOWED_TOP_LEVEL_FIELDS = new Set(AGENT_SKILLS_TOP_LEVEL_FIELDS);
 const LEGACY_FIELDS = new Set(LEGACY_RENMA_SKILL_FIELDS);
-const MAX_NAME_LENGTH = 64;
-const MAX_DESCRIPTION_LENGTH = 1024;
-const MAX_COMPATIBILITY_LENGTH = 500;
+const AGENT_SKILLS_LIMITS = DEFAULT_QUALITY_PROFILE.agentSkills;
+const MAX_NAME_LENGTH = AGENT_SKILLS_LIMITS.nameMaxChars;
+const MAX_DESCRIPTION_LENGTH = AGENT_SKILLS_LIMITS.descriptionMaxChars;
+const MAX_COMPATIBILITY_LENGTH = AGENT_SKILLS_LIMITS.compatibilityMaxChars;
 /** Validate every discovered Skill using one locally versioned Agent Skills profile. */
 export function validateAgentSkills(documents) {
     const results = documents
@@ -231,10 +234,16 @@ function validateName(document, frontmatter, issues) {
     if (nameValidation.problems.length > 0) {
         issues.push(createIssue(document, IDS.AS_INVALID_NAME, "error", "specification", `Invalid Agent Skills name "${rawName}": ${nameValidation.problems.join("; ")}.`, field?.startLine ?? 1, "name"));
     }
-    const parent = path.posix.basename(path.posix.dirname(document.artifact.path));
-    const parentValidation = normalizeAgentSkillDirectoryName(parent);
-    if (nameValidation.normalized !== undefined &&
-        parentValidation.normalized !== nameValidation.normalized) {
+    const logicalDirectory = logicalSkillDirectory(document.artifact.path);
+    const parent = logicalDirectory
+        ? path.posix.basename(logicalDirectory)
+        : undefined;
+    const parentValidation = parent
+        ? normalizeAgentSkillDirectoryName(parent)
+        : undefined;
+    if (parent !== undefined &&
+        nameValidation.normalized !== undefined &&
+        parentValidation?.normalized !== nameValidation.normalized) {
         issues.push({
             ...createIssue(document, IDS.AS_NAME_DIRECTORY_MISMATCH, "error", "specification", `Agent Skills name "${rawName}" must match parent directory "${parent}".`, field?.startLine ?? 1, "name"),
             details: { name: rawName, parentDirectory: parent },
@@ -294,6 +303,9 @@ function authoringIssues(document, frontmatter, description) {
     const issues = [];
     const bodyLines = collectBodyLines(document, frontmatter);
     const descriptionLine = firstField(frontmatter, "description")?.startLine ?? 1;
+    if (!descriptionCapabilityPattern().test(description)) {
+        issues.push(createIssue(document, IDS.RN_DESCRIPTION_MISSING_CAPABILITY, "warning", "renma-authoring", "Description should state what the skill does, not only that it should be used.", descriptionLine, "description"));
+    }
     if (!usageBoundaryPattern().test(description)) {
         issues.push(createIssue(document, IDS.RN_DESCRIPTION_MISSING_USAGE_BOUNDARY, "warning", "renma-authoring", "Description should state when the agent should use this skill.", descriptionLine, "description"));
     }
@@ -447,6 +459,14 @@ function characterLength(value) {
 function usageBoundaryPattern() {
     return /\b(?:use(?: this skill)? (?:when|for|to)|when (?:a|an|the|you|reviewing|working|handling))\b/i;
 }
+/**
+ * Conservative English capability evidence for the Agent Skills "what" clause.
+ * Non-ASCII descriptions are accepted because Renma cannot reliably infer
+ * capability semantics across languages with a deterministic word list.
+ */
+function descriptionCapabilityPattern() {
+    return /[^\p{ASCII}]|\b(?:address(?:es|ing)?|analy[sz](?:e|es|ing)|analysis|automat(?:e|es|ing|ion)|build(?:s|ing)?|calculat(?:e|es|ing|ion)|compar(?:e|es|ing|ison)|configur(?:e|es|ing|ation)|convert(?:s|ing)?|creat(?:e|es|ing|ion)|debug(?:s|ging)?|deploy(?:s|ing|ment)?|design(?:s|ing)?|diagnos(?:e|es|ing|is)|document(?:s|ing|ation)?|edit(?:s|ing)?|evaluat(?:e|es|ing|ion)|extract(?:s|ing|ion)?|find(?:s|ing)?|fix(?:es|ing)?|generat(?:e|es|ing|ion)|guid(?:e|es|ing|ance)|implement(?:s|ing|ation)?|inspect(?:s|ing|ion)?|install(?:s|ing|ation)?|manage(?:s|ment|ing)?|migrat(?:e|es|ing|ion)|monitor(?:s|ing)?|organiz(?:e|es|ing|ation)|plan(?:s|ning)?|prepar(?:e|es|ing|ation)|produc(?:e|es|ing|tion)|publish(?:es|ing)?|read(?:s|ing)?|releas(?:e|es|ing)|render(?:s|ing)?|review(?:s|ing)?|rout(?:e|es|ing)|scaffold(?:s|ing)?|search(?:es|ing)?|summari[sz](?:e|es|ing|ation)|test(?:s|ing)?|transform(?:s|ing|ation)?|triag(?:e|es|ing)|updat(?:e|es|ing)|validat(?:e|es|ing|ion)|verif(?:y|ies|ying|ication)|writ(?:e|es|ing))\b/iu;
+}
 function explicitSelectionBoundaryPattern() {
     return /\b(?:do not use (?:this|the) skill|do not select (?:this|the) skill|use another skill|when not to use (?:this|the) skill)\b/i;
 }