renma 0.1.0 → 0.2.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.
package/README.md CHANGED
@@ -1,33 +1,67 @@
1
- # Renma - 練磨
1
+ # Renma
2
2
 
3
- Renma helps teams keep LLM-ready context assets and skills healthy in Git.
3
+ Renma is a Context Asset Repository and health layer for LLM-consumable repository knowledge.
4
4
 
5
- Renma is a Git-native governance and quality layer for shared context repositories. It prepares repositories so Codex, Claude, Cursor, and future agents can consume team-owned expertise correctly. Renma does not choose task context, assemble prompts, inject context, or execute agent workflows; agents and runtimes decide how to use the assets for a task.
5
+ It helps teams keep the skills, instructions, shared context, examples, tool notes, and ownership metadata that agents rely on discoverable, reviewable, and safe to reuse. Instead of letting critical knowledge get copied into many prompts or buried in one-off Markdown files, Renma treats that knowledge as a software asset: named, owned, versioned, linked, and checked in CI.
6
+
7
+ Renma is especially useful when a repository contains agent-facing material such as:
8
+
9
+ - Codex, Claude, Cursor, or other agent skills
10
+ - `AGENTS.md` and repository instructions
11
+ - Shared product, domain, QA, platform, or tool guidance
12
+ - Team-owned context assets that should outlive a single prompt
13
+ - References and examples that agents should be able to cite or inspect
14
+
15
+ Renma is not a Markdown linter and not a prompt-management system. Markdown is the storage format today; the product is the catalog, dependency graph, ownership model, and readiness checks around LLM-era repository knowledge.
16
+
17
+ Use Renma when you need to answer repository-level questions such as:
18
+
19
+ - What LLM-facing knowledge exists in this repo?
20
+ - Which skills, context assets, examples, and tool notes are reusable?
21
+ - Which assets are unowned, stale, orphaned, incomplete, deprecated, or broken?
22
+ - Which product decisions, bug history, testing strategy, or platform guidance should be promoted from one-off prompt text into shared context?
23
+ - What changed in the agent-facing knowledge catalog during this pull request?
24
+
25
+ ## The Layer Model
6
26
 
7
27
  ```text
8
- Skill = LLM-facing entrypoint / routing contract / usage guide
9
- Context = independently owned source-of-truth knowledge asset
28
+ Tools
29
+ Codex, Claude, Cursor, CI, editors, internal CLIs
30
+
31
+ Skills
32
+ LLM-facing entrypoints that route an agent toward a task
33
+
34
+ Context Assets
35
+ Shared domain, product, testing, platform, and tool knowledge
36
+
37
+ Catalog
38
+ Deterministic IDs, ownership, lifecycle state, dependencies, evidence
39
+
40
+ Repository
41
+ Git-reviewed source of truth for agent-consumable knowledge
10
42
  ```
11
43
 
44
+ Tools decide what to do at runtime. Skills tell an agent when and how to use a capability. Context assets hold reusable knowledge. Renma catalogs and validates the layer underneath so tools and agents are not guessing from stale, orphaned, duplicated, or unowned files.
45
+
12
46
  ## Why Renma?
13
47
 
14
- As AI-agent repositories grow, expertise often gets copied into many skills. Testing heuristics, domain risks, tool usage notes, and team-specific contracts drift apart. Ownership becomes unclear, references break, deprecated guidance remains reachable, and new engineers or agents cannot tell which knowledge is authoritative.
48
+ As AI-agent repositories grow, expertise often gets duplicated across skills and prompts. Testing heuristics, domain risks, tool usage notes, product decisions, and team-specific contracts drift apart. Ownership becomes unclear. References break. Deprecated guidance remains reachable. New engineers and agents cannot tell which knowledge is authoritative.
15
49
 
16
- Renma treats context as a software asset:
50
+ Renma gives that material the same operational posture teams expect from source code:
17
51
 
18
- - Reusable
19
- - Owned
20
- - Reviewable
21
- - Versioned
22
- - Composable
23
- - Validated
24
- - Easy to inspect in CI and code review
52
+ - Reusable across skills and agents
53
+ - Owned by a team or maintainer
54
+ - Reviewable in pull requests
55
+ - Versioned in Git
56
+ - Composable through explicit references and dependencies
57
+ - Validated with deterministic checks
58
+ - Easy to inspect locally and in CI
25
59
 
26
- The first strong product focus is QA/testing: boundary value analysis, negative testing, regression risk, payment idempotency, duplicate charge prevention, refund edge cases, mobile offline behavior, mobile automation usage, internal test strategy, and known team-specific risks can live as shared context assets instead of being buried inside individual skills.
60
+ For example, a testing organization can keep boundary value analysis, negative testing, regression risk, payment idempotency, duplicate charge prevention, refund edge cases, mobile offline behavior, mobile automation notes, and known team-specific risks as shared context assets instead of burying them inside individual skills.
27
61
 
28
62
  ## Repository Shape
29
63
 
30
- Renma supports skill-local references, profiles, and examples, but the target repository model gives shared context assets first-class space:
64
+ Renma supports existing skill-local references, profiles, and examples. The preferred model is to give reusable knowledge first-class space under `contexts/`:
31
65
 
32
66
  ```text
33
67
  skills/
@@ -35,6 +69,7 @@ skills/
35
69
  test-case-generation.skill.md
36
70
  spec-review.skill.md
37
71
  regression-planning.skill.md
72
+
38
73
  contexts/
39
74
  testing/
40
75
  boundary-value-analysis.md
@@ -45,172 +80,161 @@ contexts/
45
80
  idempotency.md
46
81
  duplicate-charge.md
47
82
  refund-risk.md
48
- mobile/
49
- offline-behavior.md
50
- background-resume.md
83
+ mobile/
84
+ offline-behavior.md
85
+ background-resume.md
51
86
  tools/
52
- mobile/
53
- device-setup.md
54
- helper-guidelines.md
87
+ appium/
88
+ usage-guideline.md
89
+ limitations.md
55
90
  teams/
56
91
  checkout/
57
92
  payment-api-contracts.md
58
93
  known-risk-patterns.md
59
94
  ```
60
95
 
61
- `contexts/` is preferred. `context/` is also scanned for compatibility. Files under either root are cataloged as first-class `context` assets, while skill-local `references/` remain `reference` assets.
62
-
63
- ## What Renma Does
96
+ `contexts/` is preferred. `context/` is also scanned for compatibility. Files under either root are cataloged as first-class `context` assets, while skill-local `references/` remain supported as `reference` assets.
64
97
 
65
- Today Renma is a minimal-dependency TypeScript CLI that scans AI-agent skills, repository instructions, shared context Markdown, profile overlays, references, and examples. It runs deterministic quality, structure, and safety rules, then emits text or JSON reports with file and line evidence. It also emits deterministic catalog, ownership coverage, graph, and agent readiness reports from the same local catalog model.
98
+ ## What Renma Does Today
66
99
 
67
- Renma findings are intended to be actionable repair prompts for humans and LLM
68
- tools such as Codex, Claude, and Cursor. Findings should explain what is wrong,
69
- why it matters, where the evidence is, what a safe repair should preserve, and
70
- how to verify the fix. Renma does not apply large semantic rewrites itself; it
71
- emits structured diagnostics so a human or agent can propose a reviewable patch
72
- and run Renma again.
100
+ Renma is a minimal-dependency TypeScript CLI that scans local repositories and builds a deterministic catalog of agent-consumable assets.
73
101
 
74
- Completed baseline:
102
+ It currently scans:
75
103
 
76
- - Bounded filesystem discovery
77
- - Stable POSIX-style repo-relative paths
78
- - Markdown parsing for headings, links, code fences, metadata, and evidence
79
- - Structural quality checks for skills, shared context assets, and local support files
80
- - Safety checks for risky instructions and literal secrets
81
- - Deterministic catalog output for assets and dependency metadata
82
- - Deterministic ownership coverage reporting for cataloged assets
83
- - Context graph snapshot reporting
84
- - Deterministic agent readiness scoring for static repository health
85
- - Deterministic metadata governance for duplicate asset IDs, unknown declared references, references to deprecated or archived assets, and orphaned shared context assets
86
- - Repository file outline and line-slice inspection helper
87
- - Semantic split prompt helper for oversized context files
88
- - CI-friendly exit behavior with `--fail-on`
89
- - Config loading from `renma.config.json` and `.renma.json`
104
+ - AI-agent skills
105
+ - Repository instructions such as `AGENTS.md`
106
+ - Shared context Markdown under `context/` and `contexts/`
107
+ - Skill profiles, references, and examples
108
+ - Tool guidance and support files
109
+ - README-level repository documentation
90
110
 
91
- Near-term direction:
111
+ It produces:
92
112
 
93
- - Agent readiness report
94
- - Repeated context and duplicate knowledge discovery
95
- - Semantic diff for context changes
96
- - Optional LLM-assisted repository evaluation bundles
97
- - Optional external signal import
113
+ - File and line-level diagnostics
114
+ - Catalog reports with deterministic asset IDs
115
+ - Ownership coverage reports
116
+ - Dependency graph reports
117
+ - Agent readiness reports
118
+ - JSON output for CI and downstream tooling
119
+ - Text output designed to become actionable repair prompts for humans or agents
98
120
 
99
- See [architecture.md](./architecture.md) and [plan.md](./plan.md) for the current design direction.
121
+ Findings are meant to explain what is wrong, why it matters, where the evidence is, what to preserve while fixing it, and how to verify the repair. Renma does not apply large semantic rewrites itself; it emits structured diagnostics so a human or coding agent can propose a reviewable patch and run Renma again.
100
122
 
101
- ## Requirements
123
+ ### Repeated context diagnostics
102
124
 
103
- - Node.js 22.17 or newer
104
- - npm
125
+ `renma scan` reports deterministic repeated-context candidates across discovered skills, agents, profiles, references, examples, and shared context assets. These findings are evidence for consolidation, not automatic source-of-truth decisions:
105
126
 
106
- Install:
107
-
108
- ```bash
109
- npm install
110
- npm run build
127
+ ```text
128
+ LLM proposes. Renma verifies. Human approves.
111
129
  ```
112
130
 
113
- After building, run the CLI directly:
131
+ The MVP rule IDs are:
114
132
 
115
- ```bash
116
- node dist/index.js scan .
117
- ```
133
+ - `MAINT-REPEATED-SECTION` for repeated normalized section hashes.
134
+ - `MAINT-REPEATED-HEADING` for repeated non-generic headings.
135
+ - `MAINT-REPEATED-CODE-BLOCK` for repeated substantial code fences.
136
+ - `MAINT-REPEATED-LINK` for repeated repository context link targets.
137
+ - `MAINT-REPEATED-CONTEXT-PATTERN` for repeated token shingles.
118
138
 
119
- When installed as a package, the binary name is:
139
+ Renma normalizes whitespace and only reports cross-file candidates with stable parser evidence. Remediation text asks maintainers to preserve ownership boundaries, procedural detail, and human approval while consolidating owned knowledge.
120
140
 
121
- ```bash
122
- renma scan .
123
- ```
141
+ ## How Renma differs from adjacent tools
124
142
 
125
- ## Usage
143
+ Prompt-management and eval tools focus on prompts, traces, and model outputs.
126
144
 
127
- ```bash
128
- renma scan [path] [options]
129
- renma catalog [path] [options]
130
- renma graph [path] [options]
131
- renma ownership [path] [options]
132
- renma readiness [path] [options]
133
- renma inspect <file> [options]
134
- renma suggest-semantic-split <file> [options]
135
- ```
145
+ Renma focuses one layer lower: the reusable context assets and skills that prompts, agents, and tools depend on.
136
146
 
137
- Readiness output also includes a compact workflow readiness summary that groups workflow-level checks, counts pass/warn/fail states, and reports a deterministic workflow readiness percentage.
147
+ Knowledge-management tools help humans organize notes and documents.
138
148
 
139
- `renma readiness` emits a static, deterministic agent-readiness report with a score, level, summary metrics, checks, and diagnostics. It exits 0 only when the level is `ready`; `needs_attention` and `not_ready` exit 1 for CI use. It does not call LLMs, choose runtime context, assemble prompts, or repair files.
149
+ Renma focuses on machine-consumable repository knowledge that can be owned, referenced, validated, and reused in AI workflows.
140
150
 
141
- ### Agent readiness v1
151
+ Software catalogs track services, libraries, ownership, and lifecycle.
142
152
 
143
- Agent readiness v1 is a deterministic static report for checking whether skill workflow entrypoints are safe and understandable enough for human or agent consumption. It does not decide runtime context selection, assemble prompts, call an LLM, or repair files.
153
+ Renma applies a similar catalog model to context assets.
144
154
 
145
- The v1 workflow checks cover:
155
+ ## First-Time Use
146
156
 
147
- - required context closure
148
- - optional context health
149
- - routing and usage clarity
150
- - required inputs / prerequisites
151
- - completion criteria / definition of done
157
+ Try Renma against the current repository:
152
158
 
153
- The report also includes a workflow readiness summary that counts workflow pass/warn/fail states and reports a deterministic workflow readiness percentage.
159
+ ```bash
160
+ npx renma scan .
161
+ npx renma catalog . --format json
162
+ npx renma graph . --format mermaid
163
+ npx renma readiness .
164
+ npx renma diff . --from main --to HEAD --format markdown
165
+ ```
154
166
 
155
- A ready report is intentionally compact enough to paste into a PR description, for example: level, score, workflow readiness, graph resolution, ownership coverage, diagnostics, and layout status.
167
+ The first command does not require you to design a knowledge architecture up front. It scans the repository, builds a local catalog, and reports obvious health issues such as broken links, unclear ownership, risky instructions, weak structure, and context that may be hard for agents to trust.
156
168
 
157
- Dogfooding against the `appium/skills` branch `refine2` produced a ready v1 report with all workflow checks passing, all graph edges resolved, all assets owned, no diagnostics, and passing layout checks. The example confirmed that the Markdown recap is useful for PR reviews without changing Renma's deterministic static boundaries.
169
+ If you are developing Renma from source:
158
170
 
159
- The JSON and Markdown reports expose `summary.workflow` counts, graph resolution, ownership coverage, diagnostics, and layout status. They do not perform runtime context selection, assemble prompt packages, call an LLM, auto-repair files, score repairability, or plan per-skill patches.
171
+ ```bash
172
+ npm install
173
+ npm run build
174
+ node dist/index.js scan .
175
+ ```
160
176
 
161
- Workflow context closure checks that each skill entrypoint's declared required context references resolve to usable, non-deprecated, non-archived assets.
177
+ Then inspect the catalog and graph:
162
178
 
163
- Workflow optional-context checks warn when declared optional context references are unresolved, deprecated, or archived, without deciding whether optional context should be loaded at runtime.
179
+ ```bash
180
+ node dist/index.js catalog . --format json
181
+ node dist/index.js graph . --format mermaid
182
+ node dist/index.js readiness .
183
+ node dist/index.js diff . --from main --to HEAD --format markdown
184
+ ```
164
185
 
165
- Workflow clarity warns when skill entrypoints lack deterministic routing, preflight, examples, verification, or other static guidance needed for responsible agent use.
186
+ Semantic diff compares deterministic catalog, graph, readiness, and finding
187
+ snapshots across Git refs. It does not interpret arbitrary prose semantics,
188
+ assemble prompts, choose context, call an LLM, repair files, or check out or
189
+ mutate the working tree.
166
190
 
167
- Workflow required-input checks warn when skill entrypoints do not document the inputs, prerequisites, or permissions agents need before starting.
191
+ A practical first pass is:
168
192
 
169
- Workflow completion-criteria checks warn when skill entrypoints do not state the final output, evidence, report contents, patch expectations, or stop condition needed to complete the workflow.
193
+ 1. Run `scan` to find broken links, weak structure, risky instructions, missing lifecycle metadata, and other repairable issues.
194
+ 2. Run `catalog` to see which skills, context assets, references, examples, and support files Renma discovered.
195
+ 3. Run `ownership` to find assets without clear ownership.
196
+ 4. Run `graph` to inspect dependencies and discover orphaned or overly coupled knowledge.
197
+ 5. Run `readiness` to summarize whether the repository is healthy enough for agent use.
170
198
 
171
- `renma inspect` is a repository inspection helper for outlines and exact line slices; it does not choose task context or assemble prompts.
199
+ Renma does not require an LLM for this loop. Its core analysis is deterministic so the same repository state produces stable evidence in local development, CI, and code review.
172
200
 
173
- Options:
201
+ ## CLI Commands
174
202
 
175
- ```text
176
- -c, --config <path> Read JSON config from path
177
- --fail-on <level> Exit 1 when findings meet severity: low, medium, high, critical
178
- --format <format> scan: text or json; catalog/ownership: json or markdown; graph: json, markdown, or mermaid; suggest: prompt or json
179
- --include-owned ownership: include owned asset details
180
- --json Shortcut for --format json
181
- --view <view> graph: summary, workflow, or full
182
- --lines <range> inspect: exact line range, e.g. L10-L42
183
- --max-source-bytes <n>
184
- suggest-semantic-split: source file byte budget
185
- --max-context-bytes <n>
186
- suggest-semantic-split: nearby context byte budget
187
- -h, --help Show help
188
- -v, --version Show version
203
+ ```bash
204
+ renma scan <path>
205
+ renma catalog <path>
206
+ renma ownership <path>
207
+ renma graph <path>
208
+ renma readiness <path>
209
+ renma diff <path> --from <ref> --to <ref>
210
+ renma ci-report <path> --from <ref> --to <ref>
211
+ renma inspect <path> <asset-or-file>
212
+ renma suggest-semantic-split <file>
189
213
  ```
190
214
 
191
- Examples:
215
+ Common examples:
192
216
 
193
217
  ```bash
194
218
  renma scan .
195
- renma scan ./my-repo --json
196
- renma scan . --fail-on medium
197
- renma scan . --config ./renma.config.json
198
- renma catalog . --format markdown
199
- renma catalog . --json
200
- renma graph . --format markdown
219
+ renma scan . --format json
220
+ renma scan . --fail-on high
221
+ renma catalog . --format json
222
+ renma ownership . --include-owned
201
223
  renma graph . --format mermaid
202
- renma graph . --format mermaid --view workflow
203
- renma graph . --json
204
- renma ownership . --format markdown
205
- renma ownership . --json
206
- renma ownership . --json --include-owned
207
- renma readiness . --format markdown
208
- renma readiness . --json
209
- renma inspect contexts/testing/boundary-value-analysis.md --format json
210
- renma inspect contexts/testing/boundary-value-analysis.md --lines L40-L90 --format text
211
- renma suggest-semantic-split contexts/testing/boundary-value-analysis.md
224
+ renma readiness .
225
+ renma diff . --from main --to HEAD --format markdown
226
+ renma ci-report . --from main --to HEAD --format markdown
227
+ renma inspect . contexts/testing/boundary-value-analysis.md
212
228
  ```
213
229
 
230
+ Use JSON output when Renma is part of CI or another tool. Use markdown output for PR-review artifacts. Use text output when a person or coding agent needs a concise repair list.
231
+
232
+ `ci-report` exit behavior:
233
+
234
+ - PASS/WARN: exit 0
235
+ - FAIL: exit 1
236
+ - command, runtime, or config error: exit 2
237
+
214
238
  ## What Gets Scanned
215
239
 
216
240
  By default, Renma looks for:
@@ -225,19 +249,11 @@ contexts/**/*.md
225
249
  tools/**/*
226
250
  ```
227
251
 
228
- It skips `node_modules`, `dist`, and `.git`, ignores symbolic links, enforces a maximum file size, and reports paths in stable POSIX-style form.
252
+ Renma also understands skill-local support directories such as `profiles/`, `references/`, and `examples/`. Shared knowledge that is reused across skills should usually move into `contexts/` so it can have its own owner, lifecycle, dependencies, and review history.
229
253
 
230
254
  ## Configuration
231
255
 
232
- Renma automatically looks for `renma.config.json`, then `.renma.json`.
233
-
234
- Configuration is applied in this order:
235
-
236
- 1. Defaults
237
- 2. Config file
238
- 3. CLI flags
239
-
240
- Example:
256
+ Add `renma.config.json` at the repository root to tune discovery and CI behavior:
241
257
 
242
258
  ```json
243
259
  {
@@ -248,7 +264,11 @@ Example:
248
264
  "AGENTS.md",
249
265
  "contexts/**/*.md"
250
266
  ],
251
- "exclude": ["node_modules", "dist", ".git"],
267
+ "exclude": [
268
+ "node_modules",
269
+ "dist",
270
+ ".git"
271
+ ],
252
272
  "max_file_size_bytes": 524288,
253
273
  "max_depth": 16,
254
274
  "concurrency": 16,
@@ -258,93 +278,103 @@ Example:
258
278
  }
259
279
  ```
260
280
 
261
- Supported fields:
281
+ ## Asset Metadata
262
282
 
263
- - `fail_on`: `low`, `medium`, `high`, or `critical`
264
- - `format`: `text` or `json`
265
- - `globs`: array of glob patterns
266
- - `exclude`: array of path segment names to skip
267
- - `max_file_size_bytes`: positive integer
268
- - `max_depth`: positive integer
269
- - `concurrency`: positive integer
270
- - `layout`: optional strict layout policy configuration
271
- - `tool_namespace`: optional namespace for suggested `contexts/tools/<namespace>/...` and `tools/<namespace>/...` paths
272
- - `workflow_aliases`: map of skill directory names to canonical workflow directory names
283
+ Renma works best when reusable assets declare lightweight metadata in front matter:
273
284
 
274
- Invalid config fields exit with code `2`.
285
+ ```markdown
286
+ ---
287
+ id: context.testing.boundary-value-analysis
288
+ kind: context
289
+ owner: qa-platform
290
+ status: active
291
+ depends_on:
292
+ - context.testing.negative-testing
293
+ ---
275
294
 
276
- ## Layout Policy
295
+ # Boundary Value Analysis
296
+ ```
277
297
 
278
- Strict layout diagnostics are generic by default. Renma suggests context assets under `contexts/<workflow>/...` and helper assets under `tools/<workflow>/...` unless a repository config adds a tool namespace.
298
+ Useful metadata includes:
279
299
 
280
- - `layout.tool_namespace` is optional. When set, it controls the namespace used in suggested `contexts/tools/<namespace>/<workflow>/...` and `tools/<namespace>/<workflow>/...` paths. When omitted, Renma suggests `contexts/<workflow>/...` and `tools/<workflow>/...` paths.
281
- - `layout.workflow_aliases` maps skill directory names to canonical workflow directory names.
300
+ - `id`: Stable catalog ID
301
+ - `kind`: `skill`, `context`, `reference`, `example`, `profile`, or support type
302
+ - `owner`: Team, person, or group responsible for the asset
303
+ - `status`: Lifecycle state such as `active`, `draft`, `deprecated`, or `archived`
304
+ - `depends_on`: Other catalog IDs this asset relies on
282
305
 
283
- Example:
306
+ Renma can infer some information from paths and headings, but explicit metadata makes ownership and dependency reports much more valuable.
284
307
 
285
- ```json
286
- {
287
- "layout": {
288
- "tool_namespace": "mobile",
289
- "workflow_aliases": {
290
- "device-setup": "real-device"
291
- }
292
- }
293
- }
308
+ ## CI Example
309
+
310
+ For PR review artifacts, see [`examples/github-actions/renma-ci-report.yml`](examples/github-actions/renma-ci-report.yml).
311
+
312
+ ```yaml
313
+ name: renma
314
+
315
+ on:
316
+ pull_request:
317
+ push:
318
+ branches:
319
+ - main
320
+
321
+ jobs:
322
+ renma:
323
+ runs-on: ubuntu-latest
324
+ steps:
325
+ - uses: actions/checkout@v4
326
+ - uses: actions/setup-node@v4
327
+ with:
328
+ node-version: 22
329
+ - run: npx renma scan . --fail-on high --format json
294
330
  ```
295
331
 
296
- ## Exit Codes
332
+ ## Design Philosophy
333
+
334
+ Renma has an opinionated design.
335
+
336
+ It is built around the idea that reusable LLM context should be treated like a software asset: owned, versioned, referenced, reviewed, and checked for readiness.
337
+
338
+ This means Renma favors structured, Git-friendly context repositories over ad hoc prompt snippets or untracked notes.
297
339
 
298
- - `0`: Scan completed and no findings met the failure threshold
299
- - `1`: Scan completed and at least one finding met `fail_on`
300
- - `2`: CLI usage error, invalid config, or unreadable required input
340
+ ## Design Boundaries
301
341
 
302
- ## Checks
342
+ Renma intentionally stays below the agent runtime layer.
303
343
 
304
- Current rules include:
344
+ Renma does:
305
345
 
306
- - Missing skill description, examples, preflight, verification, negative routing, or explicit routing clarity
307
- - Short frontmatter descriptions
308
- - Oversized `SKILL.md` entrypoints
309
- - Metadata governance findings surfaced through `scan`, including invalid lifecycle status values, missing shared context `id` or `owner`, duplicate asset IDs, unknown declared references, declared references to deprecated or archived assets, and orphaned shared context assets
310
- - Oversized shared context assets or local support files in `contexts/`, `context/`, `profiles/`, `references/`, and `examples/`
311
- - Unreachable skill-local profiles, references, and examples
312
- - Profile overlays missing base skill declaration
313
- - Skills that still route through deprecated or superseded local support assets after reusable knowledge has moved to canonical shared context assets
314
- - Non-skill assets that still reference deprecated or superseded support files instead of canonical shared context assets
315
- - Advisory reusable-context candidates in `SKILL.md` files with enough size and diverse setup, troubleshooting, platform, testing, risk, or domain-rule signals
316
- - Advisory shared-context candidates in large `contexts/**/*.md` assets with generic source-of-truth headings and reusable guidance phrases
317
- - Advisory shared-context assets under process-state folders such as `contexts/promoted/`, `contexts/generated/`, or `contexts/drafts/` that should become semantic final paths
318
- - Literal secret-like values
319
- - Private key material
320
- - Destructive commands without nearby confirmation or recovery context
321
- - Risky remote defaults
322
- - Broad environment copying into subprocesses
323
- - Hardcoded user-local paths
346
+ - Catalog LLM-consumable repository assets
347
+ - Validate links, structure, lifecycle state, safety signals, and ownership
348
+ - Emit deterministic reports with file and line evidence
349
+ - Help humans and agents repair knowledge repositories through reviewable patches
324
350
 
325
- Declared reference validation resolves exact asset IDs and repository-relative paths, including paths with a leading `./` normalized away. It does not perform fuzzy matching, semantic lookup, runtime context selection, or prompt assembly.
351
+ Renma does not:
326
352
 
327
- Static checks are evidence. Passing a scan does not prove a repository or agent workflow is safe.
353
+ - Choose task-specific context for a live agent session
354
+ - Assemble prompts
355
+ - Inject context into model calls
356
+ - Execute agent workflows
357
+ - Act as a provider gateway
358
+ - Replace product, QA, platform, or documentation ownership
359
+
360
+ This boundary keeps Renma useful as repository infrastructure. Agent tools can consume its reports, but the catalog remains grounded in Git, code review, and deterministic checks.
328
361
 
329
362
  ## Development
330
363
 
331
364
  ```bash
365
+ npm install
332
366
  npm run build
333
- npm run typecheck
334
367
  npm test
335
368
  ```
336
369
 
337
- The package build emits the CLI to `dist/index.js`. Tests compile to `dist-test/`.
338
-
339
- ## Inspirations
340
-
341
- Renma is inspired by:
370
+ Run the local CLI after building:
342
371
 
343
- - [Waza](https://github.com/microsoft/waza), especially skill eval coverage, task-based regression checks, and readiness-oriented validation.
344
- - [SkillSpector](https://github.com/NVIDIA/skillspector), especially deterministic security scanning, risk-oriented findings, SARIF/reporting direction, and analyzer-style rule organization.
345
-
346
- Renma is an independent implementation focused on lightweight deterministic governance checks for AI-agent skill and context repositories.
372
+ ```bash
373
+ node dist/index.js scan .
374
+ ```
347
375
 
348
- ## License
376
+ ## Related Docs
349
377
 
350
- MIT. See [LICENSE](./LICENSE).
378
+ - [architecture.md](architecture.md) for the deeper system model
379
+ - [design.md](design.md) for product and rule-design notes
380
+ - [plan.md](plan.md) for current implementation direction
package/dist/cli.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA2BA,wBAAsB,IAAI,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6ExE"}
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAgCA,wBAAsB,IAAI,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyFxE"}