renma 0.15.2 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (126) hide show
  1. package/CHANGELOG.md +54 -1
  2. package/README.md +216 -655
  3. package/architecture.md +523 -0
  4. package/design.md +458 -0
  5. package/dist/agent-skills.d.ts +77 -0
  6. package/dist/agent-skills.d.ts.map +1 -0
  7. package/dist/agent-skills.js +468 -0
  8. package/dist/agent-skills.js.map +1 -0
  9. package/dist/catalog.d.ts.map +1 -1
  10. package/dist/catalog.js +38 -5
  11. package/dist/catalog.js.map +1 -1
  12. package/dist/cli-help.d.ts +13 -11
  13. package/dist/cli-help.d.ts.map +1 -1
  14. package/dist/cli-help.js +36 -11
  15. package/dist/cli-help.js.map +1 -1
  16. package/dist/cli.d.ts.map +1 -1
  17. package/dist/cli.js +139 -40
  18. package/dist/cli.js.map +1 -1
  19. package/dist/commands/catalog.d.ts.map +1 -1
  20. package/dist/commands/catalog.js +4 -3
  21. package/dist/commands/catalog.js.map +1 -1
  22. package/dist/commands/graph.d.ts.map +1 -1
  23. package/dist/commands/graph.js +7 -12
  24. package/dist/commands/graph.js.map +1 -1
  25. package/dist/commands/readiness.d.ts.map +1 -1
  26. package/dist/commands/readiness.js +7 -6
  27. package/dist/commands/readiness.js.map +1 -1
  28. package/dist/commands/scaffold.d.ts.map +1 -1
  29. package/dist/commands/scaffold.js +59 -16
  30. package/dist/commands/scaffold.js.map +1 -1
  31. package/dist/commands/suggest-metadata.d.ts +3 -1
  32. package/dist/commands/suggest-metadata.d.ts.map +1 -1
  33. package/dist/commands/suggest-metadata.js +226 -7
  34. package/dist/commands/suggest-metadata.js.map +1 -1
  35. package/dist/commands/suggest-semantic-split.js +3 -3
  36. package/dist/commands/suggest-semantic-split.js.map +1 -1
  37. package/dist/dependency-resolution.d.ts +6 -0
  38. package/dist/dependency-resolution.d.ts.map +1 -0
  39. package/dist/dependency-resolution.js +11 -0
  40. package/dist/dependency-resolution.js.map +1 -0
  41. package/dist/diagnostic-ids.d.ts +29 -0
  42. package/dist/diagnostic-ids.d.ts.map +1 -1
  43. package/dist/diagnostic-ids.js +28 -0
  44. package/dist/diagnostic-ids.js.map +1 -1
  45. package/dist/discovery.d.ts +50 -0
  46. package/dist/discovery.d.ts.map +1 -1
  47. package/dist/discovery.js +183 -25
  48. package/dist/discovery.js.map +1 -1
  49. package/dist/metadata.d.ts +3 -1
  50. package/dist/metadata.d.ts.map +1 -1
  51. package/dist/metadata.js +166 -29
  52. package/dist/metadata.js.map +1 -1
  53. package/dist/model.d.ts +1 -0
  54. package/dist/model.d.ts.map +1 -1
  55. package/dist/report.d.ts.map +1 -1
  56. package/dist/report.js +16 -1
  57. package/dist/report.js.map +1 -1
  58. package/dist/repository-paths.d.ts +13 -0
  59. package/dist/repository-paths.d.ts.map +1 -1
  60. package/dist/repository-paths.js +60 -2
  61. package/dist/repository-paths.js.map +1 -1
  62. package/dist/rules.d.ts.map +1 -1
  63. package/dist/rules.js +97 -107
  64. package/dist/rules.js.map +1 -1
  65. package/dist/scanner.d.ts.map +1 -1
  66. package/dist/scanner.js +3 -1
  67. package/dist/scanner.js.map +1 -1
  68. package/dist/security-diagnostics.d.ts.map +1 -1
  69. package/dist/security-diagnostics.js +98 -35
  70. package/dist/security-diagnostics.js.map +1 -1
  71. package/dist/security-policy-inventory.js +11 -4
  72. package/dist/security-policy-inventory.js.map +1 -1
  73. package/dist/security-policy.d.ts +27 -1
  74. package/dist/security-policy.d.ts.map +1 -1
  75. package/dist/security-policy.js +247 -34
  76. package/dist/security-policy.js.map +1 -1
  77. package/dist/skill-migration.d.ts +30 -0
  78. package/dist/skill-migration.d.ts.map +1 -0
  79. package/dist/skill-migration.js +566 -0
  80. package/dist/skill-migration.js.map +1 -0
  81. package/dist/trust-graph.d.ts.map +1 -1
  82. package/dist/trust-graph.js +7 -11
  83. package/dist/trust-graph.js.map +1 -1
  84. package/dist/types.d.ts +3 -1
  85. package/dist/types.d.ts.map +1 -1
  86. package/dist/yaml-frontmatter.d.ts +26 -0
  87. package/dist/yaml-frontmatter.d.ts.map +1 -0
  88. package/dist/yaml-frontmatter.js +114 -0
  89. package/dist/yaml-frontmatter.js.map +1 -0
  90. package/docs/README.md +55 -0
  91. package/docs/advanced-skill-authoring.md +140 -0
  92. package/docs/agent-skills-compatibility.md +500 -0
  93. package/docs/authoring-guide.md +324 -0
  94. package/docs/context-conflict-diagnostics.md +32 -0
  95. package/docs/context-language-diagnostics.md +99 -0
  96. package/docs/context-lens.md +253 -0
  97. package/docs/context-lifecycle-diagnostics.md +55 -0
  98. package/docs/diagnostics.md +373 -0
  99. package/docs/metadata-budget.md +14 -0
  100. package/docs/repository-context-bom.md +113 -0
  101. package/docs/security-policy.md +338 -0
  102. package/docs/user-manual.md +813 -0
  103. package/examples/context-lens/README.md +101 -0
  104. package/examples/context-lens/contexts/testing/boundary-value-analysis.md +23 -0
  105. package/examples/context-lens/lenses/testing/spec-review-boundary-values.md +29 -0
  106. package/examples/context-lens/lenses/testing/test-design-boundary-values.md +29 -0
  107. package/examples/context-lens/skills/testing/spec-review/SKILL.md +49 -0
  108. package/examples/context-repo/README.md +149 -0
  109. package/examples/context-repo/contexts/domain/payment/idempotency.md +20 -0
  110. package/examples/context-repo/contexts/testing/boundary-value-analysis.md +19 -0
  111. package/examples/context-repo/contexts/testing/negative-testing.md +19 -0
  112. package/examples/context-repo/lenses/testing/spec-review-boundary-values.md +35 -0
  113. package/examples/context-repo/renma.config.json +12 -0
  114. package/examples/context-repo/skills/testing/spec-review/SKILL.md +66 -0
  115. package/examples/context-repo/tools/appium/README.md +14 -0
  116. package/examples/github-actions/renma-ci-report.yml +36 -0
  117. package/examples/interactive-placeholder/README.md +104 -0
  118. package/examples/interactive-placeholder/assets/template.txt +1 -0
  119. package/examples/interactive-placeholder/renma.config.json +6 -0
  120. package/examples/interactive-placeholder/skills/replace-placeholder/SKILL.md +54 -0
  121. package/examples/interactive-placeholder/tools/README.md +48 -0
  122. package/examples/interactive-placeholder/tools/placeholder-demo.mjs +99 -0
  123. package/package.json +11 -1
  124. package/plan-discovery.md +740 -0
  125. package/plan.md +150 -0
  126. package/scripts/verify-package.mjs +97 -0
package/design.md ADDED
@@ -0,0 +1,458 @@
1
+ # Renma Product Design
2
+
3
+ Renma is a Git-native context repository and deterministic governance CLI for
4
+ repositories that hold LLM-facing knowledge.
5
+
6
+ Current product surface includes `scan`, `catalog`, `ownership`, `graph`,
7
+ focused graph views, `trust-graph`, `readiness`, Repository Context BOM reports,
8
+ repeated-context diagnostics, semantic diff, `ci-report`, `inspect`, `scaffold`,
9
+ `suggest-metadata`, `suggest-semantic-split`, Agent Skills validation, and
10
+ security diagnostics for agent-facing operational instructions.
11
+
12
+ Focused graph views are inspection tools; they do not choose, inject, or load runtime context for an agent.
13
+
14
+ Renma prepares deterministic repository evidence. Agents operate outside Renma
15
+ and decide how to consume repository assets according to their own runtime
16
+ behavior.
17
+
18
+ Renma helps teams keep shared knowledge discoverable, owned, validated,
19
+ reviewable, and reusable in Git. It is not an agent runtime and does not decide
20
+ what context an agent should load at task time.
21
+
22
+ ## Core Distinction
23
+
24
+ ```mermaid
25
+ flowchart LR
26
+ Skill["Skill: agent-facing entrypoint, routing contract, usage guide"]
27
+ Lens["Context Lens: purpose-oriented interpretation"]
28
+ Asset["Context Asset: independently owned source-of-truth knowledge"]
29
+ Skill -->|may reference| Lens
30
+ Skill -->|may reference directly| Asset
31
+ Lens -->|interprets| Asset
32
+ ```
33
+
34
+ Skills tell an agent when and how to use a capability. They can reference
35
+ context assets, ask preflight questions, describe safety gates, and define
36
+ verification expectations.
37
+
38
+ Context assets hold reusable expertise. They should be maintainable outside a
39
+ single skill, owned by the right team, versioned, reviewed, and reused across
40
+ skills, agents, tools, and future agent runtimes.
41
+
42
+ Context Lenses describe how one or more Context Assets should be interpreted for
43
+ a purpose. They are repository governance metadata, not runtime lens selection
44
+ or prompt assembly.
45
+
46
+ These arrows are declared repository relationships, not a runtime loading
47
+ pipeline. Renma validates them but does not select a Lens, choose task-specific
48
+ Context, or inject either asset into an agent session.
49
+
50
+ ## Product Boundary
51
+
52
+ Renma owns repository quality and governance:
53
+
54
+ - Asset discovery and classification
55
+ - Owner, status, lifecycle, and metadata checks
56
+ - Broken reference and dependency checks
57
+ - Catalog and graph snapshots
58
+ - Orphaned, deprecated, archived, conflicting, and missing asset diagnostics
59
+ - Deterministic evidence for repeated or duplicated knowledge
60
+ - Deterministic readiness reports for repository maintainers
61
+
62
+ Renma does not own runtime behavior:
63
+
64
+ - No skill selection for a user task
65
+ - No prompt construction or context bundling
66
+ - No context injection into an agent
67
+ - No task-specific context choice service
68
+ - No tool execution on behalf of an agent
69
+ - No provider gateway or agent coordination layer
70
+ - No telemetry collection responsibility
71
+
72
+ Any future import of external signals from CI, IDE wrappers, agent plugins, or
73
+ other integrations must treat those signals as separately produced offline
74
+ review evidence. Renma itself is not telemetry-responsible.
75
+
76
+ ## LLM-Actionable Diagnostics
77
+
78
+ Security diagnostics focus on conservative operational-instruction risks,
79
+ policy metadata, security profile resolution, approved network and upload
80
+ destination checks, and explicit human approval guards. They remain
81
+ deterministic repository checks, not runtime enforcement.
82
+
83
+ Security diagnostics are deterministic review guardrails for LLM-facing operational instructions. They flag patterns such as unpinned remote shell execution, unpinned dependency installs, privileged commands without nearby guardrails, predictable temporary paths, and credential-like command arguments; they do not replace SAST, secret scanning, dependency scanning, or human security review.
84
+
85
+ Security posture summaries in Readiness and CI reports describe effective
86
+ policy, security profile resolution, allowed data, forbidden inputs, approved
87
+ network and upload destinations, human approval requirements, and high-risk
88
+ findings without enforcing runtime behavior.
89
+
90
+ 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.
91
+
92
+ 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.
93
+
94
+ Renma findings should be useful not only to humans, but also to LLM coding
95
+ agents. A good Renma diagnostic should explain what is wrong, why it matters for
96
+ repository governance, where the evidence is, what direction a safe fix should
97
+ take, what constraints must be preserved, and how to verify the fix.
98
+
99
+ Renma should not apply large semantic rewrites by itself. It should produce
100
+ structured diagnostics that can be pasted into Codex, Claude, Cursor, or another
101
+ agent to guide a reviewable repository patch.
102
+
103
+ Current diagnostics include evidence, `whyItMatters`, remediation, typed repair
104
+ constraints, verification steps, and LLM-facing hints where applicable. These
105
+ fields remain deterministic rule output, not LLM-generated validation.
106
+
107
+ Example diagnostic shape:
108
+
109
+ ```json
110
+ {
111
+ "id": "RMA-SKILL-TOO-MONOLITHIC",
112
+ "severity": "medium",
113
+ "category": "structure",
114
+ "title": "Skill mixes reusable knowledge with usage guidance",
115
+ "evidence": {
116
+ "path": "skills/testing/test-case-generation/SKILL.md",
117
+ "startLine": 42,
118
+ "endLine": 78,
119
+ "snippet": "boundary value analysis"
120
+ },
121
+ "whyItMatters": "Reusable QA and domain knowledge should be owned, reviewed, and reused as shared context assets instead of being buried in one skill.",
122
+ "remediation": "Split reusable knowledge into first-class shared context assets and keep the skill as an LLM-facing usage guide.",
123
+ "constraints": [
124
+ "Do not introduce task context selection.",
125
+ "Do not create prompt packages.",
126
+ "Keep the skill as a routing contract / usage guide.",
127
+ "Each context asset should have id, owner, status, and short scope."
128
+ ],
129
+ "verificationSteps": [
130
+ "Run renma scan.",
131
+ "Run any project-specific validation checks that apply to this repository.",
132
+ "Ensure the skill no longer mixes reusable domain knowledge with usage guidance."
133
+ ],
134
+ "llmHint": "Create shared context assets for reusable QA knowledge, update skill metadata, and preserve the skill as a concise usage guide."
135
+ }
136
+ ```
137
+
138
+ Central repair workflow:
139
+
140
+ 1. A single `SKILL.md` contains reusable domain knowledge, tool guidance, and
141
+ QA heuristics.
142
+ 2. Renma emits structured findings explaining that the skill is too monolithic
143
+ and mixes usage guidance with reusable context.
144
+ 3. Codex or Claude reads the diagnostics and proposes a patch that moves
145
+ reusable knowledge into first-class context assets under `contexts/`, keeps
146
+ the skill concise, adds metadata, and updates declared context references.
147
+ 4. A human reviews the patch.
148
+ 5. Renma scans the repository again and confirms the skill/context separation is
149
+ healthier.
150
+
151
+ Optional LLM-assisted evaluation is advisory and outside core validation. See
152
+ `architecture.md` section `Optional LLM Evaluation Boundary` for the rule:
153
+ `scan`, catalog construction, and deterministic rule evaluation do not call an
154
+ LLM; optional helpers may prepare review bundles or suggestions for a human or
155
+ calling agent to apply.
156
+
157
+ ## Repository Model
158
+
159
+ An illustrative repository shape gives shared Context Assets first-class space:
160
+
161
+ ```text
162
+ skills/
163
+ testing/
164
+ test-case-generation/
165
+ SKILL.md
166
+ spec-review/
167
+ SKILL.md
168
+ regression-planning/
169
+ SKILL.md
170
+
171
+ contexts/
172
+ testing/
173
+ boundary-value-analysis.md
174
+ negative-testing.md
175
+ regression-risk.md
176
+ domain/
177
+ payment/
178
+ idempotency.md
179
+ duplicate-charge.md
180
+ refund-risk.md
181
+ mobile/
182
+ offline-behavior.md
183
+ background-resume.md
184
+ tools/
185
+ appium/
186
+ usage-guideline.md
187
+ limitations.md
188
+ teams/
189
+ checkout/
190
+ payment-api-contracts.md
191
+ known-risk-patterns.md
192
+
193
+ lenses/
194
+ testing/
195
+ spec-review-boundary-values.md
196
+
197
+ metadata/
198
+ graph/
199
+ catalog/
200
+ ```
201
+
202
+ This is not a required layout for every repository asset. A repository may
203
+ organize Context Assets, Context Lenses, policies, references, evidence, and
204
+ other knowledge by domain, product, team, workflow, or a combination of those
205
+ dimensions. Canonical Skill entrypoints in 0.16.0 remain under
206
+ `skills/**/SKILL.md` and `.agents/skills/**/SKILL.md`; arbitrary Skill roots and
207
+ domain-local `*/skills/**/SKILL.md` layouts are not implemented. Renma's broader
208
+ model means repository knowledge need not be embedded inside those Skill
209
+ directories.
210
+
211
+ `contexts/` is preferred for shared context assets. `context/` remains supported
212
+ as a compatibility alias. Files under either root are classified as the
213
+ `context` artifact kind, not as `reference`. Experimental `context_lens` assets
214
+ can live under `lenses/`, or context files can opt in with `type: context_lens`.
215
+
216
+ Skill-local `assets/`, `profiles/`, `references/`, `examples/`, and `scripts/`
217
+ remain supported. They are useful for local routing variants, nearby examples,
218
+ Skill-specific supporting text, fixtures, and helpers. When evidence shows that
219
+ knowledge is reusable across Skills, teams, tools, or agents, it should move
220
+ into `contexts/` as an owned Context Asset. Shared helper implementations may
221
+ move to `tools/**`; location alone does not require either promotion.
222
+
223
+ 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.
224
+
225
+ Shared context assets should be organized by semantic scope, not migration state. Folders such as `contexts/promoted/` or `contexts/generated/` can be useful temporary staging concepts, but final context assets should live under meaning-oriented paths such as `contexts/tools/...`, `contexts/domain/...`, `contexts/testing/...`, `contexts/teams/...`, `contexts/policies/...`, or `contexts/platform/...`.
226
+
227
+ ## Artifact Kinds
228
+
229
+ Renma normalizes scanned files into asset kinds:
230
+
231
+ - `skill`: LLM-facing entrypoint, routing contract, and usage guide
232
+ - `context`: shared source-of-truth knowledge asset under `contexts/` or
233
+ `context/`
234
+ - `context_lens`: purpose-oriented interpretation layer over context assets
235
+ - `profile`: skill-local overlay or variant
236
+ - `reference`: skill-local supporting material
237
+ - `example`: skill-local example or fixture text
238
+ - `agent`: repository or agent instruction file
239
+ - `config`: Renma configuration
240
+ - `unknown`: scanned file that does not match a known kind
241
+
242
+ The dedicated `context` kind is central to the product model. It lets catalog,
243
+ graph, and validation output distinguish reusable team-owned knowledge from
244
+ skill-local reference material.
245
+
246
+ ## Context Asset Metadata
247
+
248
+ Context assets should use small, reviewable metadata blocks:
249
+
250
+ ```yaml
251
+ ---
252
+ id: context.testing.boundary-value-analysis-v2
253
+ title: Boundary Value Analysis
254
+ owner: qa-platform
255
+ status: stable
256
+ version: 1.0.0
257
+ tags:
258
+ - testing
259
+ - qa
260
+ when_to_use:
261
+ - Designing tests around numeric, date, quantity, or limit boundaries
262
+ when_not_to_use:
263
+ - Exploratory testing notes that do not depend on boundaries
264
+ requires_context:
265
+ - testing.negative-testing
266
+ optional_context:
267
+ - context.domain.payment.duplicate-charge
268
+ conflicts:
269
+ - context.testing.boundary-value-analysis-v1
270
+ superseded_by:
271
+ - context.testing.boundary-value-analysis-v3
272
+ ---
273
+ ```
274
+
275
+ The current parser supports YAML-style block lists for selected deterministic metadata fields. Supported block-list fields are `tags`, `when_to_use`, `when_not_to_use`, `requires_context`, `optional_context`, `conflicts`, and `superseded_by`; arbitrary nested maps are not metadata.
276
+
277
+ Initial status values:
278
+
279
+ - `experimental`
280
+ - `stable`
281
+ - `deprecated`
282
+ - `archived`
283
+
284
+ `status` describes lifecycle only. It should not be used for replacement,
285
+ delegation, migration provenance, or canonical-source relationships. For
286
+ example, a skill-local reference replaced by a shared context asset should use a
287
+ valid lifecycle status such as `deprecated`, plus a separate relationship field
288
+ such as `superseded_by: contexts/tools/example/setup.md` when the repository
289
+ needs to preserve that link. Renma may catalog `superseded_by` as a static
290
+ reference relationship, but it should not treat values such as `active` or
291
+ `delegated` as valid lifecycle statuses.
292
+
293
+ When reusable knowledge is promoted from a skill-local support file into
294
+ `contexts/`, the original `skills/*/references/` file may remain temporarily as
295
+ a compatibility shim. Renma can warn when a skill still routes readers through a
296
+ deprecated or superseded local support asset instead of referencing the
297
+ canonical shared context directly.
298
+
299
+ Renma can also warn when other repository assets continue to reference a
300
+ deprecated or superseded support file instead of the canonical shared context.
301
+ This broader advisory helps remove hidden indirection after context promotion
302
+ while preserving compatibility shims when they are intentionally needed.
303
+
304
+ Renma starts deterministic validation for fields it actually uses: duplicate IDs,
305
+ invalid statuses, missing owner or ID on published shared context, unknown
306
+ declared references, dependencies on deprecated or archived assets, and orphaned
307
+ first-class shared context assets. Declared references resolve by exact asset ID
308
+ or repository-relative path, with a leading `./` normalized away. Renma does not
309
+ use fuzzy matching, semantic search, LLM inference, or runtime context selection
310
+ for these checks.
311
+
312
+ ## Dependency Model
313
+
314
+ Dependencies are typed relationships between assets:
315
+
316
+ - `requires`: the target asset is needed for the source asset to be complete
317
+ - `optional`: useful context that is not always required
318
+ - `applies_to`: context asset interpreted by a context lens
319
+ - `conflicts`: assets that should not both be active without human review
320
+ - `extends`: overlay or profile relationship
321
+ - `references`: declared static relationship from a skill or support asset toward a context asset or local file
322
+ - `covered_by`: evaluation or evidence coverage relationship
323
+
324
+ Edges should carry source evidence: path, range when available, declaration
325
+ form, and enough snippet text for review.
326
+
327
+ The graph is repository evidence. It must not become a task-specific context selector.
328
+
329
+ ## Core Workflow
330
+
331
+ Renma should keep the deterministic path boring and reliable:
332
+
333
+ 1. Load configuration from defaults, config files, and CLI flags.
334
+ 2. Discover bounded repository files with stable POSIX-style paths.
335
+ 3. Classify artifacts into normalized kinds, including first-class `context`.
336
+ 4. Parse Markdown, frontmatter, headings, links, code fences, and metadata.
337
+ 5. Build catalog entries with IDs, kind, source path, content hash, owner,
338
+ status, tags, declared dependencies, dependents, and diagnostics.
339
+ 6. Build graph snapshots from declared references and dependency metadata.
340
+ 7. Run deterministic rules over parsed files and graph evidence.
341
+ 8. Emit the command's documented text, JSON, Markdown, or Mermaid projection
342
+ for Git review and CI.
343
+
344
+ Optional LLM assistance may help with semantic split suggestions, duplicate
345
+ labeling, or review summaries. LLM output is advisory. Deterministic evidence is
346
+ the authority.
347
+
348
+ ## Rules
349
+
350
+ Implemented deterministic rules focus on repository health:
351
+
352
+ - Missing context asset ID
353
+ - Missing owner on shared context assets
354
+ - Invalid lifecycle status
355
+ - Duplicate asset IDs
356
+ - Unknown declared references
357
+ - Declared dependency on deprecated or archived context
358
+ - Orphaned shared context asset
359
+ - Superseded local support asset reference advisories
360
+ - Oversized skill entrypoint
361
+ - Skill may contain reusable context worth extracting
362
+ - Oversized context or skill-local support file
363
+ - Missing skill routing guidance
364
+ - Missing negative routing guidance
365
+ - Missing preflight or verification guidance
366
+ - Unused skill-local profile, reference, or example
367
+ - Literal secret-like values
368
+ - Destructive commands without nearby confirmation or recovery guidance
369
+ - Risky remote defaults
370
+ - Broad environment copying into subprocesses
371
+ - Hardcoded user-local paths in reusable guidance
372
+
373
+ Current reporting includes deterministic Readiness output, ownership coverage,
374
+ graph snapshots, repeated-context diagnostics, semantic diff, Trust Graph,
375
+ Repository Context BOM, security posture summaries, CI reports, and optional
376
+ LLM-friendly review bundles. These are repository projections and evidence, not
377
+ runtime selection or execution services.
378
+
379
+ Passing Renma checks does not prove a workflow is safe. It means the repository
380
+ met the deterministic governance checks that were enabled.
381
+
382
+ ## QA And Testing Focus
383
+
384
+ QA/testing is the first strong product focus because teams often ask agents to
385
+ generate tests while the real expertise lives in scattered documents or senior
386
+ engineers' heads.
387
+
388
+ Good context assets in this domain include:
389
+
390
+ - Boundary value analysis
391
+ - Negative testing heuristics
392
+ - Regression risk models
393
+ - Payment idempotency and duplicate-charge risk
394
+ - Refund edge cases
395
+ - Mobile offline and background-resume behavior
396
+ - Appium usage limits
397
+ - Team-specific test strategy
398
+ - Known checkout or payment contract risks
399
+
400
+ Skills can reference those assets for tasks such as test-case generation, spec
401
+ review, regression planning, or release readiness. The context assets remain
402
+ the source of truth.
403
+
404
+ ## Catalog Output
405
+
406
+ `renma catalog` should provide deterministic inventory:
407
+
408
+ - ID
409
+ - Kind
410
+ - Source path
411
+ - Content hash
412
+ - Owner
413
+ - Status
414
+ - Tags
415
+ - Declared dependencies
416
+ - Dependents
417
+ - Diagnostics
418
+
419
+ Catalog output should be stable across filesystems and Node versions so diffs
420
+ are useful in pull requests.
421
+
422
+ ## Repository Health Readiness
423
+
424
+ Readiness v1 is a deterministic static repository-health report for maintainers:
425
+
426
+ ```bash
427
+ renma readiness [path] [--format json|markdown]
428
+ ```
429
+
430
+ It answers repository-level questions:
431
+
432
+ - Are shared context assets identifiable and owned?
433
+ - Are lifecycle states explicit?
434
+ - Are skills clear entrypoints rather than overloaded knowledge dumps?
435
+ - Are dependency declarations resolvable?
436
+ - Are deprecated or archived assets still reachable?
437
+ - Are important context assets orphaned?
438
+ - Is repeated knowledge visible enough for maintainers to consolidate it?
439
+ - Which changed assets affect which skills or teams?
440
+
441
+ Readiness is about preparing the repository for agents. It is not a guarantee
442
+ about any particular agent run.
443
+
444
+ The Markdown report is intentionally compact for PR review: level, score, workflow readiness, graph resolution, ownership coverage, diagnostics, and layout status. The JSON report exposes the same deterministic facts for CI.
445
+
446
+ Readiness does not call an LLM, select runtime context, assemble prompts, auto-repair files, perform cross-document semantic consistency analysis, score repairability, or plan per-skill patches.
447
+
448
+ ## Implementation Principles
449
+
450
+ - Prefer deterministic analysis over hidden inference.
451
+ - Keep the CLI minimal-dependency and Git-friendly.
452
+ - Keep repository paths stable and portable.
453
+ - Parse structured metadata instead of relying on ad hoc text matching where
454
+ reasonable.
455
+ - Preserve human ownership and review.
456
+ - Treat existing documents as changeable product design, not sacred API.
457
+ - Make shared context first-class before adding external signal features.
458
+ - Design for gradual adoption in repositories that already have skill debt.
@@ -0,0 +1,77 @@
1
+ import { type AgentSkillDiagnosticId } from "./diagnostic-ids.js";
2
+ import type { ParsedDocument } from "./types.js";
3
+ import { type ParsedYamlFrontmatter } from "./yaml-frontmatter.js";
4
+ export declare const AGENT_SKILLS_SPECIFICATION = "https://agentskills.io/specification";
5
+ export declare const AGENT_SKILLS_VALIDATION_PROFILE = "agentskills.io/specification@2026-07-11";
6
+ export declare const AGENT_SKILLS_TOP_LEVEL_FIELDS: readonly ["name", "description", "license", "compatibility", "metadata", "allowed-tools"];
7
+ 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"];
8
+ export type AgentSkillFormat = "agent-skills" | "renma-legacy" | "hybrid" | "unknown";
9
+ export interface AgentSkillValidationIssue {
10
+ code: AgentSkillDiagnosticId;
11
+ severity: "error" | "warning";
12
+ category: "specification" | "renma-authoring";
13
+ path: string;
14
+ startLine: number;
15
+ endLine: number;
16
+ message: string;
17
+ field?: string;
18
+ details?: Record<string, unknown>;
19
+ }
20
+ export interface AgentSkillValidationResult {
21
+ path: string;
22
+ format: AgentSkillFormat;
23
+ valid: boolean;
24
+ name?: string;
25
+ description?: string;
26
+ migrationRecommended: boolean;
27
+ migrationDirection?: "legacy-to-agent-skills";
28
+ migrationCommand?: AgentSkillMigrationCommand;
29
+ legacyFields: string[];
30
+ canonicalRenmaFields: string[];
31
+ errorCount: number;
32
+ warningCount: number;
33
+ issues: AgentSkillValidationIssue[];
34
+ }
35
+ export interface AgentSkillInspection {
36
+ frontmatter: ParsedYamlFrontmatter;
37
+ validation: AgentSkillValidationResult;
38
+ }
39
+ export interface AgentSkillMigrationCommand {
40
+ command: "renma";
41
+ args: ["suggest-metadata", string];
42
+ display: string;
43
+ }
44
+ export interface AgentSkillsValidationSummary {
45
+ specification: string;
46
+ profile: string;
47
+ totalSkillCount: number;
48
+ validSkillCount: number;
49
+ invalidSkillCount: number;
50
+ canonicalSkillCount: number;
51
+ legacySkillCount: number;
52
+ hybridSkillCount: number;
53
+ warningCount: number;
54
+ results: AgentSkillValidationResult[];
55
+ }
56
+ export interface AgentSkillNameValidation {
57
+ normalized: string | undefined;
58
+ problems: string[];
59
+ }
60
+ /** Validate every discovered Skill using one locally versioned Agent Skills profile. */
61
+ export declare function validateAgentSkills(documents: ParsedDocument[]): AgentSkillsValidationSummary;
62
+ /** Validate one discovered Skill without changing any operational metadata reader. */
63
+ export declare function validateAgentSkill(document: ParsedDocument): AgentSkillValidationResult;
64
+ /** Parse and validate a Skill once for canonical operational consumers. */
65
+ export declare function inspectAgentSkill(document: ParsedDocument): AgentSkillInspection;
66
+ /** Resolve the YAML description value used by Skill quality rules. */
67
+ export declare function resolvedAgentSkillDescription(document: ParsedDocument): string | undefined;
68
+ /** Normalize and validate an Agent Skills YAML name field. */
69
+ export declare function normalizeAgentSkillNameField(value: unknown): AgentSkillNameValidation;
70
+ /** Normalize and validate a Skill directory name without changing filesystem identity. */
71
+ export declare function normalizeAgentSkillDirectoryName(value: unknown): AgentSkillNameValidation;
72
+ /** Backward-compatible name for validating an Agent Skills YAML name field. */
73
+ export declare function validateAgentSkillName(value: unknown): AgentSkillNameValidation;
74
+ export declare function legacyRenmaMetadataKey(field: string): string | undefined;
75
+ /** Return all Markdown line numbers occupied by backtick or tilde fences. */
76
+ export declare function agentSkillFenceLines(lines: string[], bodyStartLine: number): Set<number>;
77
+ //# sourceMappingURL=agent-skills.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-skills.d.ts","sourceRoot":"","sources":["../src/agent-skills.ts"],"names":[],"mappings":"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"}