module-health-rollup
Rolls up test-driven module health: parses the stack pack's coverage and test reports, attributes rows to modules through module-map.yml, and writes .paqad/module-health records with blocked_metrics for signals it could not compute. Use when checks finish, when module-health sync runs with a report, or when the user asks to refresh module health or roll up coverage.
- License 许可
- MIT
- 所属仓库
- Eliyce/paqad-ai
- 最近更新
- 2026-11-13
- Stars
- ★ 8
- Forks
- 0
01 前言 Front Matter
- name
- module-health-rollup
- metadata
- { "cacheable": "false", "model_tier": "medium", "paqad-meta": "skill.meta.yaml", "output_format": "markdown" }
- description
- Rolls up test-driven module health: parses the stack pack's coverage and test reports, attributes rows to modules through module-map.yml, and writes .paqad/module-health records with blocked_metrics for signals it could not compute. Use when checks finish, when module-health sync runs with a report, or when the user asks to refresh module health or roll up coverage.
02 资源文件 8
- 参考文档agents/openai.yaml387 B
- 资产文件assets/templates/rollup-summary.md896 B
- 参考文档references/coverage-formats.md2.4 KB
- 脚本scripts/is-blocked.sh1007 B
- 脚本scripts/list-blocked-metrics.sh1.2 KB
- 脚本scripts/list-unattributed.sh1.0 KB
- 脚本scripts/rollup.sh905 B
- 参考文档skill.meta.yaml822 B
03 SKILL.md 正文
What It Does
Runs the test-driven module-health rollup. For every module declared in module-map.yml, the rollup computes:
| Metric | Source |
|---|---|
coverage_pct |
Coverage report parsed via the pack's coverage_format parser. |
tests_passing |
Test report parsed via the pack's test_report_format parser. |
tests_failing |
Same. |
tests_total |
Same. |
change_velocity |
git log -- <sources> over git_window_days (default 14). |
contract_stability |
public_api_extractor output. Blocked when extractor absent. |
Coverage and test rows are attributed to module slugs by matching each file against module-map.yml's sources: globs. Files that match no module land in the report's unattributed_files list (surfaced to the user as a MM-ADD candidate for the reconciler).
Hard rule: no metric is fabricated or zeroed. When a signal cannot be computed the metric is set to null and the reason recorded in blocked_metrics (e.g. coverage:not_configured, tests:report_missing:<path>, contract_stability:no_public_api_extractor).
Use This When
feature-development.checksfinishes format/test/build and needs to refresh module health.paqad-ai module-health sync --from-report <path>is invoked.- The provider hook at
runtime/hooks/module-health-sync.shfires. - A user prompt asks to "refresh module health" or "roll up coverage".
Inputs
- The active stack pack's
module_healthblock: seereferences/coverage-formats.mdfor the closed format set. Required:source_roots, plus at least one of(coverage_format + coverage_path)or(test_report_format + test_report_path). module-map.yml(read-only) for slug attribution.- Optional
--from-report <path>to bypass the pack's report path (typical in CI).
Procedure
- Resolve the active stack pack and read its
module_healthblock. If the block is absent, hard-fail withblocked: module_health_unknownand surface a Decision Pause packet asking the user to add it to the pack. - Invoke the TS engine via the bundled wrapper:
The wrapper shells out tobash scripts/rollup.sh [project-root] [--from-report <path>]paqad-ai module-health rollup --project-root <root> [--from-report <path>]. Omit--from-reportto run off the declared report paths in the pack. - Parse the resulting
RollupReport. Group findings by module. - For each module, surface any
blocked_metricsentries to the user as informational warnings (not Decision Pause packets: these are config gaps, not choices). - For
unattributed_files, route the user to the module-map reconciler (MM-ADDcandidates).
Output Contract
- Per-module records written to
.paqad/module-health/<slug>.jsonin the schema-v2 shape withblocked_metrics: string[]andevidence.rolluppopulated. - A
## Module Health Rollupmarkdown block listing each module, its tier, and anyblocked_metricsreasons. - A
## Unattributed Coverage Filesblock listing files that landed on no module slug.
Escalate / Stop Conditions
- Hard-fail with
blocked: module_health_unknownwhen the active stack pack does not declare amodule_healthblock. - Stop and route to the module-map reconciler when
unattributed_filesis non-empty: coverage for an undeclared module is aMM-ADDcandidate. - Do not invent
contract_stabilitywhen the pack has nopublic_api_extractor. Recordcontract_stability:no_public_api_extractorinblocked_metricsand continue.
Scripts
Deterministic plumbing: do not re-derive these in the LLM layer.
scripts/rollup.sh [project-root] [--from-report <path>]: invoke the rollup; writes.paqad/module-health/<slug>.jsonper declared module and prints the rollup report JSON.scripts/is-blocked.sh [report.json|-]: exit 1 with the blocked reason on stdout when the whole rollup is blocked (typicallymodule_health_unknown).scripts/list-blocked-metrics.sh [report.json|-]: sorted<slug>: <reason>, <reason>lines for the informational warnings the skill surfaces.scripts/list-unattributed.sh [report.json|-]: sorted file paths for the## Unattributed Coverage Filesblock; these areMM-ADDcandidates for the module-map reconciler.
Assets
assets/templates/rollup-summary.md: markdown template for the## Module Health Rollup+## Unattributed Coverage Filesblocks.
Resources
references/coverage-formats.md: supported formats + the no-fabricated-metrics contract.runtime/base/skills/module-health-rollup/agents/openai.yaml: agent interface metadata.src/module-health/rollup.ts: rollup engine.src/module-health/parsers/: the nine framework-shipped parsers.src/validators/schemas/stack-pack.schema.json: closed enum forcoverage_format/test_report_format.runtime/base/skills/module-map-reconciler/SKILL.md: sibling skill that consumesunattributed_filesasMM-ADDcandidates.- the Decision Pause Contract (in the framework bootstrap): packet semantics.
04 同仓库更多 Skills
sample-skill
Sample bundled skill fixture
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
understand-idea
Chat and Claude Code: Step 1 of the discover journey: clarifies the goal, who benefits, success and constraints into the idea block. Use when the journey directs it to step 1, not directly.
size-work
Chat and Claude Code: Suggest a size for a ticket from comparable finished work, as a labelled suggestion the team still owns. Use it when someone asks "how big is this?", "roughly how much work is ABC-12?", or wants a backlog item sized. It finds the team's sizing scale at first use, picks two to five of the closest finished tickets with links, and gives a size or range with the drivers behind it and a confidence of low, medium or high, lowered and explained when the area's documents are template text. Every result is labelled a suggested size, never a date or a commitment. It writes nothing into the size field unless the user says "set it", and it refuses to overwrite an existing size unless the user asks to replace it. Produces the sizing block of the record.
refine-ticket
Chat and Claude Code: Improve one or more existing tracker tickets without losing the author's intent. Use it when someone wants a ticket read, diagnosed and tidied up ("this ticket is vague", "fix up ABC-12", "split this, it's too big"). It reads each ticket in full and snapshots it with its last-updated time, says what is wrong with evidence, and proposes a field-by-field before and after change set limited to summary, description, labels, parent, links and new child tickets on a split. It writes nothing until an explicit "apply it" bound to that exact change set, re-checks the ticket for conflicting edits just before writing, never replaces rich descriptions with plain text, never deletes or closes a ticket, and reads each ticket back after applying. Produces the existing and changes blocks of the record.