@harness-forge/cli 1.2.2 → 1.2.4

package/skills/hforge-analyze/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: hforge-analyze
+description: repository analysis, runtime fact refresh, evidence-backed notes, and decision capture using harness forge surfaces. use when the user asks to analyze the repo, understand what matters next, gather findings, inspect risks, or turn architecture-significant changes into durable decision records.
+---
+
+# HForge Analyze
+
+## Trigger Signals
+
+- the user asks for repo analysis, understanding, onboarding, or a summary of what matters next
+- the repo already has Harness Forge runtime artifacts that should be reused instead of rediscovered
+- there are risks, validation gaps, stale findings, or architecture-significant changes to capture
+- the next safe step depends on understanding repo shape, runtime findings, or decision coverage
+
+## Inspect First
+
+- `AGENTS.md`
+- `.hforge/agent-manifest.json`
+- `.hforge/runtime/index.json`
+- `.hforge/runtime/repo/repo-map.json`
+- `.hforge/runtime/repo/recommendations.json`
+- `.hforge/runtime/repo/instruction-plan.json`
+- `.hforge/runtime/findings/risk-signals.json`
+- `.hforge/runtime/findings/validation-gaps.json`
+- `.hforge/runtime/decisions/index.json`
+
+## Workflow
+
+1. confirm the workspace is initialized with `hforge status --root . --json`
+2. if runtime artifacts are missing, initialize first with `hforge bootstrap --root . --yes`
+3. if runtime artifacts are stale, run `hforge refresh --root . --json`
+4. run `hforge review --root . --json` when runtime health, decision coverage, or stale task artifacts matter
+5. summarize repo shape, dominant implementation surfaces, risks, validation gaps, and next actions using the existing runtime as the primary source of truth
+6. when the analysis reveals architecture-significant work, create or update a durable ASR or ADR under `.hforge/runtime/decisions/`
+
+## References
+
+- `skills/hforge-analyze/references/analysis-order.md`
+- `skills/hforge-analyze/references/output-contract.md`
+- `skills/hforge-analyze/references/decision-promotion.md`

package/skills/hforge-analyze/references/analysis-order.md

@@ -0,0 +1,15 @@
+# Analysis order
+
+Use this order to keep analysis deterministic and low-noise.
+
+1. `hforge status --root . --json`
+2. `.hforge/agent-manifest.json`
+3. `.hforge/runtime/index.json`
+4. `.hforge/runtime/repo/repo-map.json`
+5. `.hforge/runtime/repo/recommendations.json`
+6. `.hforge/runtime/repo/instruction-plan.json`
+7. `.hforge/runtime/findings/risk-signals.json`
+8. `.hforge/runtime/findings/validation-gaps.json`
+9. `.hforge/runtime/decisions/index.json`
+10. `hforge review --root . --json` when runtime health or stale tasks matter
+11. `hforge refresh --root . --json` only when the existing runtime is missing or stale

package/skills/hforge-analyze/references/decision-promotion.md

@@ -0,0 +1,9 @@
+# Decision promotion
+
+Promote a finding into `.hforge/runtime/decisions/` when one or more of these are true:
+- the change affects runtime boundaries, package layout, support posture, or multi-target behavior
+- the choice has meaningful trade-offs and should stay reviewable later
+- the work changes upgrade, migration, validation, or release expectations
+
+Use an ASR when the direction is still being evaluated.
+Use an ADR when the decision is accepted enough to guide future work.

package/skills/hforge-analyze/references/output-contract.md

@@ -0,0 +1,7 @@
+# Output contract
+
+A good `/hforge-analyze` result should include:
+- a short repo-shape summary
+- 3 to 7 high-signal findings, not a raw dump
+- the concrete runtime artifact or command that supports each next step
+- explicit decision candidates when the work is architecture-significant

package/skills/hforge-decide/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: hforge-decide
+description: create or update durable asr or adr records for harness forge workspaces. use when an analysis or implementation choice changes runtime behavior, package boundaries, support posture, migration strategy, or any other architecture-significant concern that should remain reviewable after the current session.
+---
+
+# HForge Decide
+
+## Trigger Signals
+
+- an analysis or implementation choice has architecture-significant consequences
+- the repo already has decision records and the new work should link to them
+- multiple credible options exist and the rationale should stay durable
+- a task pack, impact analysis, or review surfaced a decision candidate that should not stay implicit
+
+## Inspect First
+
+- `.hforge/runtime/decisions/index.json`
+- `.hforge/runtime/tasks/`
+- `.hforge/runtime/findings/`
+- `.hforge/runtime/repo/recommendations.json`
+- the most relevant existing ASR or ADR if one already exists
+
+## Workflow
+
+1. frame the decision clearly before writing anything
+2. inspect related task packs, impact analysis, risk signals, and existing decision records
+3. create an ASR when the direction is still being evaluated and an ADR when the decision is accepted enough to guide future work
+4. write the record under `.hforge/runtime/decisions/` with context, decision, consequences, constraints, risks, and follow-up actions
+5. update supersession or related-record links when the new decision changes an earlier one
+
+## Output Contract
+
+- a concise ASR or ADR with explicit status and rationale
+- links to related tasks, impacts, and superseded records
+- follow-up actions or open questions when the work is not fully settled
+
+## Validation Path
+
+- `.hforge/runtime/decisions/index.json`
+- `schemas/runtime/decision-record.schema.json`
+- `schemas/runtime/architecture-significance.schema.json`
+
+## Failure Modes
+
+- the real decision is still too vague to record
+- there is not enough evidence to justify a durable record yet
+- the new record conflicts with an existing one and the supersession path is unclear
+
+## Escalation
+
+- escalate when the decision changes public support or target guarantees
+- escalate when migration or rollback cost is materially different across options
+- escalate when a new record would contradict an existing accepted ADR
+
+## References
+
+- `skills/hforge-decide/references/decision-rubric.md`
+- `skills/hforge-decide/references/output-contract.md`

package/skills/hforge-decide/references/decision-rubric.md

@@ -0,0 +1,18 @@
+# Decision rubric
+
+Create or update a record when the choice affects one or more of these:
+- runtime behavior
+- package or bundle boundaries
+- target support posture
+- migration or rollback strategy
+- validation, release, or maintenance guarantees
+
+Prefer ASR when:
+- exploration is still active
+- the trade-offs are being narrowed
+- the work needs a reviewable candidate before acceptance
+
+Prefer ADR when:
+- the direction is stable enough to guide future work
+- the team needs a durable accepted rationale
+- the decision supersedes an earlier record

package/skills/hforge-decide/references/output-contract.md

@@ -0,0 +1,7 @@
+# Output contract
+
+A good `/hforge-decide` result should include:
+- the record type and why it was chosen
+- the decision statement in one or two lines
+- constraints, risks, and consequences
+- task refs or runtime evidence that justify the record

package/skills/hforge-init/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: hforge-init
+description: initialize harness forge in the current repository, bootstrap the target-aware runtime, and establish the managed surfaces needed for later review, analysis, and decision tracking. use when the repo is not initialized, when runtime files are missing, or when the user asks to set up hforge in a project.
+---
+
+# HForge Init
+
+## Trigger Signals
+
+- the repository is not yet initialized for Harness Forge
+- `.hforge/agent-manifest.json` or `.hforge/runtime/index.json` is missing
+- target runtime files such as `.codex/` or `.claude/` are missing or incomplete
+- the user asks to initialize, bootstrap, or wire Harness Forge into a repo
+
+## Inspect First
+
+- repository root files such as `README.md`, `package.json`, and CI or target config files
+- `AGENTS.md` and `.agents/skills/` when present
+- `.hforge/agent-manifest.json` and `.hforge/runtime/index.json` when present
+- `.codex/` and `.claude/` bridge surfaces when present
+
+## Workflow
+
+1. inspect the current workspace state with `hforge status --root . --json`
+2. if the repo is not initialized or target runtime files are absent, run `hforge bootstrap --root . --yes`
+3. run `hforge refresh --root . --json` after bootstrap so shared runtime summaries are current
+4. inspect `hforge catalog --json` when bundle or profile visibility matters
+5. summarize detected targets, installed surfaces, runtime artifacts, and the recommended next command
+
+## Output Contract
+
+- initialization status and whether bootstrap was needed
+- detected targets and managed runtime surfaces now present
+- runtime artifacts now available under `.hforge/runtime/`
+- the best next command to run, such as `/hforge-analyze` or `/hforge-review`
+
+## Validation Path
+
+- `hforge status --root . --json`
+- `hforge bootstrap --root . --yes`
+- `hforge refresh --root . --json`
+
+## Failure Modes
+
+- the repo is not writable
+- the `hforge` launcher is not available
+- target detection is incomplete or no supported target is installed yet
+
+## Escalation
+
+- escalate when bootstrap cannot write the project-owned runtime
+- escalate when targets are ambiguous and the repo needs explicit operator intent
+- escalate when package installation or shell setup is missing
+
+## References
+
+- `skills/hforge-init/references/bootstrap-order.md`
+- `skills/hforge-init/references/output-contract.md`

package/skills/hforge-init/references/bootstrap-order.md

@@ -0,0 +1,7 @@
+# Bootstrap order
+
+1. Run `hforge status --root . --json` first to avoid bootstrapping blindly.
+2. Prefer `hforge bootstrap --root . --yes` when the repo needs one-pass setup.
+3. Run `hforge refresh --root . --json` immediately after bootstrap so the runtime summary, repo intelligence, and generated indexes are current.
+4. Only inspect `hforge catalog --json` after the workspace exists and targets are known.
+5. If bare `hforge` is unavailable, use the workspace-local launcher under `.hforge/generated/bin/` once the repo is initialized.

package/skills/hforge-init/references/output-contract.md

@@ -0,0 +1,7 @@
+# Output contract
+
+A good `/hforge-init` result should include:
+- whether the repo was already initialized or required bootstrap
+- detected target runtimes
+- the highest-value managed surfaces now available
+- the next recommended command and why it should be run next

package/skills/hforge-refresh/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: hforge-refresh
+description: refresh shared runtime summaries and generated harness forge artifacts after install changes, repo changes, or stale analysis state. use when the runtime is present but outdated, incomplete, or no longer trustworthy.
+---
+
+# HForge Refresh
+
+## Trigger Signals
+
+- runtime summaries are stale after installs or content changes
+- repo-intelligence artifacts no longer match the current repository state
+- the user explicitly asks to refresh the project-owned runtime
+- a later review or analysis should not rely on outdated runtime state
+
+## Inspect First
+
+- `.hforge/runtime/index.json`
+- `.hforge/generated/agent-command-catalog.json`
+- `.hforge/runtime/repo/`
+
+## Workflow
+
+1. run `hforge refresh --root . --json`
+2. follow with `hforge status --root . --json` when install-state confirmation matters
+3. summarize regenerated artifacts, remaining gaps, and the best next action
+
+## Output Contract
+
+- confirmation that refresh ran or why it could not
+- refreshed runtime artifacts and any remaining missing prerequisites
+- the next command to run, usually `/hforge-analyze` or `/hforge-review`
+
+## Validation Path
+
+- `hforge refresh --root . --json`
+- `hforge status --root . --json`
+
+## Failure Modes
+
+- the repo is not initialized
+- required runtime files or launchers are missing
+- refresh cannot reconcile the current install state
+
+## Escalation
+
+- escalate when refresh cannot complete without a fresh bootstrap
+- escalate when runtime summaries regenerate but still disagree with the repo
+
+## References
+
+- `skills/hforge-refresh/references/refresh-order.md`
+- `skills/hforge-refresh/references/output-contract.md`

package/skills/hforge-refresh/references/output-contract.md

@@ -0,0 +1,7 @@
+# Output contract
+
+A good `/hforge-refresh` result should include:
+- whether refresh succeeded
+- which runtime surfaces were regenerated
+- what still looks stale or blocked
+- the next command that should be run now that the runtime is current

package/skills/hforge-refresh/references/refresh-order.md

@@ -0,0 +1,5 @@
+# Refresh order
+
+1. `hforge refresh --root . --json`
+2. `hforge status --root . --json`
+3. inspect `.hforge/runtime/repo/` and `.hforge/generated/agent-command-catalog.json` if follow-up verification is needed

package/skills/hforge-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: hforge-review
+description: runtime health review for harness forge workspaces. use when the user wants drift checks, decision coverage, stale task review, managed-surface integrity, or a clear pass-fail summary of the current runtime state.
+---
+
+# HForge Review
+
+## Trigger Signals
+
+- the user asks whether the current Harness Forge setup is healthy
+- runtime drift, stale task artifacts, or missing managed surfaces are suspected
+- a handoff, release, or package refresh needs a concise review first
+- decision coverage and runtime governance need to be checked before moving on
+
+## Inspect First
+
+- `.hforge/runtime/index.json`
+- `.hforge/runtime/decisions/index.json`
+- `.hforge/runtime/tasks/`
+- `.hforge/generated/agent-command-catalog.json`
+- `.hforge/agent-manifest.json`
+
+## Workflow
+
+1. run `hforge review --root . --json`
+2. if installation drift is suspected, run `hforge doctor --root . --json`
+3. if package-surface integrity is suspected, run `hforge audit --root . --json`
+4. summarize blockers, warnings, stale runtime artifacts, decision gaps, and the best cleanup order
+
+## Output Contract
+
+- runtime health summary with blocker, warning, and cleanup sections
+- decision-coverage and stale-task callouts when relevant
+- the next remediation command to run
+
+## Validation Path
+
+- `hforge review --root . --json`
+- `hforge doctor --root . --json`
+- `hforge audit --root . --json`
+
+## Failure Modes
+
+- the workspace is not initialized
+- review signals are incomplete because runtime summaries are stale
+- doctor or audit cannot read the current install state
+
+## Escalation
+
+- escalate when install drift risks losing managed state
+- escalate when audit shows package-surface mismatches that need a maintainer fix
+- escalate when runtime findings and source-of-truth manifests disagree
+
+## References
+
+- `skills/hforge-review/references/review-order.md`
+- `skills/hforge-review/references/output-contract.md`

package/skills/hforge-review/references/output-contract.md

@@ -0,0 +1,7 @@
+# Output contract
+
+A good `/hforge-review` result should include:
+- whether the runtime is healthy enough to trust
+- what is stale, drifted, or missing
+- what can be fixed by refresh versus what needs a maintainer change
+- the single best next remediation step

package/skills/hforge-review/references/review-order.md

@@ -0,0 +1,7 @@
+# Review order
+
+1. `hforge review --root . --json`
+2. `.hforge/runtime/decisions/index.json`
+3. `.hforge/runtime/tasks/`
+4. `hforge doctor --root . --json` when managed surfaces look incomplete
+5. `hforge audit --root . --json` when package-surface integrity matters

package/skills/token-budget-optimizer/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: token-budget-optimizer
+description: compact context, reuse existing runtime artifacts, and choose the smallest authoritative surface before expanding prompt history. use when the task is growing large, when earlier repo intelligence already exists, or when repeated rescans would waste tokens without adding new evidence.
+---
+
+# Token Budget Optimizer
+
+## Trigger Signals
+
+- the prompt is getting long and earlier repo context is being repeated
+- the repo already has `AGENTS.md`, `.hforge/runtime/`, specs, plans, or review artifacts that can answer the next question
+- the task is investigative or iterative enough that careless re-reading will waste tokens
+- the agent is about to scan broad directory trees before checking existing runtime summaries
+
+## Inspect First
+
+- `.hforge/agent-manifest.json` and `.hforge/generated/agent-command-catalog.json`
+- `.hforge/runtime/index.json`, `.hforge/runtime/repo/repo-map.json`, and `.hforge/runtime/repo/recommendations.json`
+- active guidance bridges such as `AGENTS.md`, `CLAUDE.md`, and `.agents/skills/<skill>/SKILL.md`
+- any existing `spec.md`, `plan.md`, `tasks.md`, review output, or decision record relevant to the current task
+- `skills/token-budget-optimizer/scripts/inspect_token_surfaces.py` when a deterministic token-surface audit would help
+
+## Workflow
+
+1. identify the concrete question the agent must answer next and avoid reading more than that question requires
+2. rank existing surfaces by authority, freshness, and cost, preferring hidden runtime summaries and durable artifacts before broad source scans
+3. reuse prior findings, repo maps, decision records, and task artifacts instead of re-deriving them from scratch
+4. compact the active context into a short working set: current goal, authoritative surfaces, open questions, and the next small evidence step
+5. escalate to deeper reads only when the compacted working set cannot answer the task safely
+
+## Output Contract
+
+- a short context budget summary with the current goal and the smallest authoritative surfaces to keep loaded
+- a reuse plan listing which runtime artifacts, docs, or task artifacts should be trusted instead of reread
+- compaction candidates describing what can be summarized once and then dropped from active context
+- unresolved gaps that still require new evidence or deeper file reads
+
+## Failure Modes
+
+- runtime artifacts are stale, missing, or do not cover the active question
+- the task is genuinely novel and prior summaries are no longer trustworthy
+- the agent mistakes low-cost summaries for high-authority truth and skips required verification
+
+## Escalation
+
+- escalate when the repo has conflicting guidance across `AGENTS.md`, runtime summaries, and product code
+- escalate when token saving would hide a risky detail such as a release gate, migration step, or support constraint
+- escalate when there is no reliable compact surface and the agent must build a new authoritative summary first
+
+## References
+
+- `skills/token-budget-optimizer/references/audit-dimensions.md`
+- `skills/token-budget-optimizer/references/promotion-ladder.md`
+- `skills/token-budget-optimizer/references/scoring-model.md`
+- `skills/token-budget-optimizer/references/report-template.md`
+- `skills/token-budget-optimizer/scripts/inspect_token_surfaces.py`

package/skills/token-budget-optimizer/references/audit-dimensions.md

@@ -0,0 +1,37 @@
+# Token Surface Audit Dimensions
+
+Use these dimensions when deciding whether a surface deserves active context.
+
+## Authority
+
+- highest: generated or maintained runtime truth such as `.hforge/agent-manifest.json`, `.hforge/generated/agent-command-catalog.json`, and current runtime indexes
+- medium: maintained docs and active skill contracts
+- lower: old notes, ad-hoc chat summaries, or broad source scans without task focus
+
+## Freshness
+
+- prefer artifacts regenerated after the latest repo changes
+- downgrade summaries that predate major install, refresh, or architecture changes
+- if freshness is unclear, verify with `status`, `refresh`, or a targeted file read
+
+## Reuse value
+
+- high when the surface already answers the current question directly
+- medium when the surface narrows the search space meaningfully
+- low when the surface only restates generic repo facts or marketing prose
+
+## Token cost
+
+- very low: compact JSON summaries, short skill wrappers, direct command catalogs
+- medium: short markdown guides and specific reference docs
+- high: large source trees, broad recursive scans, or entire repo reviews with no focus
+
+## Risk of omission
+
+- high risk means the surface guards support claims, release gates, migrations, security rules, or architecture decisions
+- low risk means the surface is descriptive but not safety-critical
+
+## Recommended decision rule
+
+Keep in active context only the smallest set of high-authority, sufficiently
+fresh surfaces that answer the current question without hiding a known risk.

package/skills/token-budget-optimizer/references/promotion-ladder.md

@@ -0,0 +1,44 @@
+# Context Promotion Ladder
+
+Use this ladder to decide what belongs in active prompt context.
+
+## Level 1: Discovery only
+
+- wrappers in `.agents/skills/`
+- short command docs
+- repo root guidance bridges
+
+Use these to choose the next canonical surface quickly.
+
+## Level 2: Canonical operating surfaces
+
+- `.hforge/agent-manifest.json`
+- `.hforge/generated/agent-command-catalog.json`
+- canonical skill contracts under `.hforge/library/skills/`
+- runtime indexes and repo summaries
+
+Prefer these before reading broad product code.
+
+## Level 3: Task-bound artifacts
+
+- spec, plan, and task documents
+- task-runtime artifacts
+- decision records
+- review summaries and validation outputs
+
+Promote these when the work is already scoped and historical context matters.
+
+## Level 4: Focused code evidence
+
+- only the files needed to resolve an active question
+- only the specific function, module, schema, or config block that matters
+
+Do not jump here until the earlier levels stop being enough.
+
+## Level 5: Broad exploratory scans
+
+- full repo walks
+- many-file comparisons
+- recursive investigation sessions
+
+Use these only when lower-cost surfaces cannot answer the question safely.

package/skills/token-budget-optimizer/references/report-template.md

@@ -0,0 +1,25 @@
+# Token Budget Report Template
+
+## Current goal
+
+- What question must be answered next?
+
+## Keep loaded
+
+- Which 3-6 surfaces are authoritative enough to stay in active context?
+
+## Reuse instead of reread
+
+- Which runtime artifacts, prior summaries, or task docs already cover the needed context?
+
+## Compact and drop
+
+- Which broad notes, repeated chat summaries, or low-authority reads can be collapsed into one sentence and removed from active context?
+
+## New evidence still required
+
+- Which focused files or commands still need to be read or run?
+
+## Risk notes
+
+- What important detail would be dangerous to over-compress?

package/skills/token-budget-optimizer/references/scoring-model.md

@@ -0,0 +1,43 @@
+# Token Budget Scoring Model
+
+Use a simple score to compare candidate context surfaces.
+
+## Formula
+
+`score = authority + freshness + reuseValue - tokenCost - ambiguityPenalty`
+
+Each dimension can be scored from `0` to `3`.
+
+## Guidance
+
+- authority:
+  - `3` canonical machine-readable runtime truth
+  - `2` maintained human-readable canonical docs
+  - `1` narrow ad-hoc notes or inferred summaries
+  - `0` stale or untrusted context
+- freshness:
+  - `3` generated or edited after the relevant change
+  - `2` likely current but not recently verified
+  - `1` possibly stale
+  - `0` known stale
+- reuseValue:
+  - `3` directly answers the next question
+  - `2` sharply narrows what must be read next
+  - `1` weakly helpful
+  - `0` mostly decorative
+- tokenCost:
+  - `3` large or diffuse
+  - `2` moderate
+  - `1` small
+  - `0` tiny
+- ambiguityPenalty:
+  - `3` likely to mislead without verification
+  - `2` needs careful cross-checking
+  - `1` low ambiguity
+  - `0` explicit and stable
+
+## Usage rule
+
+Prefer the smallest set of surfaces with the highest positive score, then
+validate any high-risk claim with one focused evidence read instead of a broad
+context expansion.

package/skills/token-budget-optimizer/scripts/inspect_token_surfaces.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Inspect likely high-value context surfaces for token-efficient agent work."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+SURFACES = [
+    ("AGENTS.md", "guidance", 3, 3, 3, 1),
+    ("CLAUDE.md", "guidance", 3, 3, 2, 1),
+    (".hforge/agent-manifest.json", "runtime", 3, 3, 3, 1),
+    (".hforge/generated/agent-command-catalog.json", "runtime", 3, 3, 3, 1),
+    (".hforge/runtime/index.json", "runtime", 3, 3, 2, 1),
+    (".hforge/runtime/repo/repo-map.json", "runtime", 3, 2, 3, 1),
+    (".hforge/runtime/repo/recommendations.json", "runtime", 3, 2, 3, 1),
+    (".hforge/runtime/repo/instruction-plan.json", "runtime", 3, 2, 2, 1),
+    ("README.md", "docs", 2, 2, 1, 2),
+    (".specify/spec.md", "workflow", 2, 2, 3, 2),
+    (".specify/plan.md", "workflow", 2, 2, 3, 2),
+    (".specify/tasks.md", "workflow", 2, 2, 3, 2),
+]
+
+
+def score(authority: int, freshness: int, reuse_value: int, token_cost: int) -> int:
+    return authority + freshness + reuse_value - token_cost
+
+
+def main() -> int:
+    root = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd().resolve()
+    found = []
+    missing = []
+
+    for relative_path, category, authority, freshness, reuse_value, token_cost in SURFACES:
+        absolute_path = root / relative_path
+        entry = {
+            "path": relative_path,
+            "category": category,
+            "score": score(authority, freshness, reuse_value, token_cost),
+            "authority": authority,
+            "freshness": freshness,
+            "reuseValue": reuse_value,
+            "tokenCost": token_cost,
+        }
+        if absolute_path.exists():
+            entry["sizeBytes"] = absolute_path.stat().st_size
+            found.append(entry)
+        else:
+            missing.append(entry)
+
+    found.sort(key=lambda item: (-item["score"], item["path"]))
+    missing.sort(key=lambda item: (-item["score"], item["path"]))
+
+    result = {
+        "workspaceRoot": str(root),
+        "recommendedKeepLoaded": found[:6],
+        "recommendedFallbackReads": found[6:10],
+        "missingButUseful": missing[:6],
+    }
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())