Skip to content

v2.0.0 release polish — resolve all 16 open tickets (#377-#392) #393

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ar27111994 wants to merge 15 commits into from
Closed

v2.0.0 release polish — resolve all 16 open tickets (#377-#392) #393

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
5fa857d
fix: move shipped [Unreleased] CHANGELOG entries to [2.0.0] (#379)
ar27111994 Jul 30, 2026
f7097bc
feat: ARD URL quality validation + assorted doc fixes (#380, #384-#387)
ar27111994 Jul 30, 2026
b140240
docs: add MSYS path guidance, discover/ README, CLI cheat sheet (#381…
ar27111994 Jul 30, 2026
4861fff
fix: subcommand --help now shows subcommand-specific help (#383)
ar27111994 Jul 30, 2026
a4c3ee3
test: close coverage gaps in validate-ard-urls (#380)
ar27111994 Jul 30, 2026
61637ce
feat: discover full per-source progress + adapter dev guide (#382, #392)
ar27111994 Jul 30, 2026
014586c
fix: close remaining coverage gaps for 100%
ar27111994 Jul 30, 2026
10bd1ff
fix: remove c8 ignore, add ard-registry dispatch test
ar27111994 Jul 30, 2026
9e2fc5f
fix: add Set<string> type annotation
ar27111994 Jul 30, 2026
2e4f035
fix: update cli-help test for subcommand-specific help behavior
ar27111994 Jul 30, 2026
2636907
fix: remove unused eslint-disable comment
ar27111994 Jul 30, 2026
eef294c
test: add --help tests for quarantine, rebuild, workspace, wire, setup
ar27111994 Jul 30, 2026
6e9be58
test: add --no-sync flag test and all domain --help coverage
ar27111994 Jul 30, 2026
4f0e6b2
fix: remove exitCode from --no-sync test
ar27111994 Jul 30, 2026
3def437
test: add stderr progress assertion for source sync (#382)
ar27111994 Jul 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1,598 changes: 799 additions & 799 deletions .well-known/ai-catalog.json
View file
Open in desktop

Large diffs are not rendered by default.

34 changes: 14 additions & 20 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.

## [Unreleased]

## [2.0.0] - 2026-06-09

### Breaking Changes

- **Demand-scan file ordering changed** — binary files are now deprioritised below source files in demand-scan ordering (previously binary and source files were interleaved lexicographically). Tools or tests that assert a fixed scan order or specific truncation behaviour may need to be updated (#280).
- **`.worktrees/` directories excluded from all scans** — file discovery, demand detection, and source-sync traversal now skip `.worktrees/` subdirectories. Workspaces that deliberately stored assets inside `.worktrees/` will no longer have them picked up (#277).
- **Packagist registry enforces a hard 500-entry cap** — Packagist source-sync stops at 500 entries per source. Operators who previously indexed full high-volume Packagist namespaces will observe a reduced catalog for those sources (#286).
- **`source-health` dormant/never-synced `reason` field is now always populated** — previously the `reason` field on dormant and never-synced entries was an empty string; it now carries a descriptive message. Code that matched on empty-string reason will need to update its checks (#281).

### Fixed

- **ard-export Prettier compliance** — `discover ard-export` now formats `.well-known/ai-catalog.json` with Prettier inline, so the output passes `npm run format:check` immediately after generation (#348)
Expand All @@ -21,26 +30,6 @@ All notable changes to this project will be documented in this file.

### Added

- **`--quiet` / `--summary` flags for `discover full`** — `--quiet` suppresses expected "none survived selection" warnings; `--summary` prints aggregate breakdown by reason instead of per-source counts (#352)
- **`SelectionReport.acceptanceRate`** — computed as `selectedCount / inputCount` (rounded to 4 decimal places); 0 when inputCount is 0. Backfilled for pre-v2.0.0 reports (#353)
- **`SourceSyncStatus` extended** — new `"stale"` variant for sources using fallback data after transient fetch failures

### Changed

- **Activation budget lookup** — replaced sequential `if` branches in `getActivationBudget` with a `Map<ActivationHost, number>` lookup (#356 item 1)
- **Rejection sample size constant** — extracted inline `SAMPLE_SIZE = 20` to file-level `REJECTION_SAMPLE_SIZE` for consistency (#356 item 6)

## [2.0.0] - 2026-06-09

### Breaking Changes

- **Demand-scan file ordering changed** — binary files are now deprioritised below source files in demand-scan ordering (previously binary and source files were interleaved lexicographically). Tools or tests that assert a fixed scan order or specific truncation behaviour may need to be updated (#280).
- **`.worktrees/` directories excluded from all scans** — file discovery, demand detection, and source-sync traversal now skip `.worktrees/` subdirectories. Workspaces that deliberately stored assets inside `.worktrees/` will no longer have them picked up (#277).
- **Packagist registry enforces a hard 500-entry cap** — Packagist source-sync stops at 500 entries per source. Operators who previously indexed full high-volume Packagist namespaces will observe a reduced catalog for those sources (#286).
- **`source-health` dormant/never-synced `reason` field is now always populated** — previously the `reason` field on dormant and never-synced entries was an empty string; it now carries a descriptive message. Code that matched on empty-string reason will need to update its checks (#281).

### Added

- `wire opencode --preview` now prints a structured wire-plan summary to stdout before any file is written, listing linked-asset paths count, resolved MCP server identifiers, native-config operations, and contextual notes so operators can review changes before committing (#284)
- `WirePlanManifest.npmInstallSummary` field documenting the expected OpenCode plugin npm-install footprint (package.json path, declared dependency count, estimated installed-package count derived from lockfile entries or a fallback estimate) so tooling can distinguish OpenCode-managed npm artefacts from reference-pack files wired by agent-harness (#282)
- `SelectionReport.rejectionSummary` (`Record<string, number>`) tallying catalog rejections by reason, and `SelectionReport.sampleRejected` (stratified up-to-20 `{assetId, reason}` entries guaranteeing at least one sample per distinct rejection reason) surfacing demand-relevance and duplicate-rejection signals for diagnostics (#285)
Expand Down Expand Up @@ -78,6 +67,9 @@ All notable changes to this project will be documented in this file.
- Comprehensive catalog breadth documentation — new `docs/guides/CATALOG-BREADTH.md` guide with two-phase offline index workflow, production configuration table, source coverage breakdown, scheduled CI workflow template, and catalog size projections; README updated with "Building a comprehensive catalog" section
- VS Code Marketplace popularity sweep default raised from 10 to 50 pages (2,500 extensions by install count, configurable via `AGENT_HARNESS_VSCODE_MARKETPLACE_POPULARITY_SWEEP_PAGES`) for offline index builds
- Fixed skills-sh registry source — sitemap URL updated to `www.skills.sh` (308 redirect) and leaf predicate expanded to match `sitemap-(skills|agents|misc|owners)` patterns (#336)
- **`--quiet` / `--summary` flags for `discover full`** — `--quiet` suppresses expected "none survived selection" warnings; `--summary` prints aggregate breakdown by reason instead of per-source counts (#352)
- **`SelectionReport.acceptanceRate`** — computed as `selectedCount / inputCount` (rounded to 4 decimal places); 0 when inputCount is 0. Backfilled for pre-v2.0.0 reports (#353)
- **`SourceSyncStatus` extended** — new `"stale"` variant for sources using fallback data after transient fetch failures

### Changed

Expand All @@ -88,6 +80,8 @@ All notable changes to this project will be documented in this file.
- recommendation policy maps now recognize the newly emitted demand/stack terms so detection, policy quality, and recommendation validation stay aligned
- `source-sync.ts` (1,916 lines) decomposed into 16 focused sub-modules under `src/domains/discovery/source-sync/` — shared types, state I/O, fetching, HTML engines, references, reporting, orchestrator, and 9 per-registry adapters — with `source-sync.ts` retained as a thin re-export barrel so all existing import paths are unchanged for #270
- `no-magic-numbers` ESLint rule expanded to `activate.ts`, `official-index-harvester.ts`, and `demand-signals.ts`; 11 new named constants extracted (`COPILOT_PROFILE_ID_MAX_LENGTH`, `COPILOT_VSCODE_ACTIVATION_BUDGET`, `OPENCODE_ACTIVATION_BUDGET`, `DEFAULT_ACTIVATION_BUDGET`, `FOCUSED_ACTIVATION_BUCKET_MAX_SIZE`, `COPILOT_FALLBACK_SKILL_POOL_LIMIT`, `COPILOT_PROFILE_ID_ASSET_SEGMENT_COUNT`, `OFFICIAL_FIRST_PARTY_SOURCE_PRIORITY`, `NON_FIRST_PARTY_SOURCE_PRIORITY`, `MAX_DEPENDENCY_SIGNALS_PER_FILE`, `TEXT_SIGNAL_READ_LIMIT`) for #271
- **Activation budget lookup** — replaced sequential `if` branches in `getActivationBudget` with a `Map<ActivationHost, number>` lookup (#356 item 1)
- **Rejection sample size constant** — extracted inline `SAMPLE_SIZE = 20` to file-level `REJECTION_SAMPLE_SIZE` for consistency (#356 item 6)

### Fixed

Expand Down
30 changes: 18 additions & 12 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,15 +215,21 @@ check — never compare raw strings with `startsWith()`.

### Key directories

| Path | Purpose |
| ------------------------ | --------------------------------------- |
| `src/` | TypeScript source |
| `src/domains/discovery/` | Harvesting, catalog, demand signals |
| `src/host-adapters/` | Per-host wire and extension installers |
| `src/recommend/` | Selection scoring and report generation |
| `src/mirror/` | Artifact download and provenance |
| `src/install/` | Staged install lifecycle |
| `src/activate.ts` | Runtime root swap and rollback |
| `discover/` | Source config, policy, and seed JSON |
| `docs/` | Guides, reference, playbooks |
| `plans/` | Advisor implementation plans |
| Path | Purpose |
| ------------------------ | -------------------------------------- |
| `src/` | TypeScript source |
| `src/domains/discovery/` | Harvesting, catalog, demand signals |
| `src/host-adapters/` | Per-host wire and extension installers |

### Adding a new host adapter

See the [Adapter Development Guide](docs/guides/ADAPTER-DEVELOPMENT.md) for a
step-by-step walkthrough covering registration, lifecycle wiring, capability
matrix, native config generation, and testing — with a worked Windsurf example.
| `src/recommend/` | Selection scoring and report generation |
| `src/mirror/` | Artifact download and provenance |
| `src/install/` | Staged install lifecycle |
| `src/activate.ts` | Runtime root swap and rollback |
| `discover/` | Source config, policy, and seed JSON |
| `docs/` | Guides, reference, playbooks |
| `plans/` | Advisor implementation plans |
Comment on lines +218 to +235
Comment on lines +224 to +235

@qodo-code-review qodo-code-review Bot Jul 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Informational

5. Contributing table broken 🐞 Bug ⚙ Maintainability

The Key directories Markdown table in CONTRIBUTING.md is interrupted by a new heading/paragraph,
leaving subsequent rows outside the table and breaking rendering. This degrades the readability of
contributor documentation.
Agent Prompt 
### Issue description
In `CONTRIBUTING.md`, the `### Adding a new host adapter` section was inserted mid-way through the `Key directories` table, so the remaining rows no longer render as table rows.

### Issue Context
Markdown tables must be contiguous (header + separator + rows without interruption).

### Fix Focus Areas
- CONTRIBUTING.md[216-235]

### Suggested fix
- Move the `### Adding a new host adapter` section below the completed table, or
- Reformat so the table is complete (all directory rows included) before starting the new heading.
- Ensure the remaining rows keep consistent `| col | col |` formatting and alignment markers.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Comment on lines +224 to +235

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Keep the directory map table contiguous.

The “Adding a new host adapter” heading and prose interrupt the table, so the rows at Lines 229-235 no longer render as table rows. Move those rows above the heading, or close the table before the prose and create a separate table.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CONTRIBUTING.md` around lines 224 - 235, Keep the directory map table
contiguous by moving the rows for src/recommend, src/mirror, src/install,
src/activate.ts, discover, docs, and plans above the “Adding a new host adapter”
heading, or explicitly close the table and start a separate table after the
prose.

17 changes: 17 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,7 @@ The core model is deliberately boring in the best way: one command surface, a ho
- [v1 to v2 upgrade guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/V1-TO-V2-UPGRADE.md)
- [Scheduled maintenance workflow](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/MAINTENANCE-WORKFLOW.md)
- [Release process](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/RELEASE-PROCESS.md)
- [CLI cheat sheet](https://github.com/ar27111994/agent-harness/blob/main/docs/cheatsheet.md) — quick reference for common workflows

## What this project does

Expand Down Expand Up @@ -282,6 +283,14 @@ npm install
npm run build
```

> **Windows git-bash (MSYS) users:** Use native Windows paths when invoking the CLI.
> MSYS path translation (`/c/Projects/...` → `C:\c\Projects\...`) can produce a
> doubled drive letter (`C:\c\...`). Use `"C:\Projects\agent-harness\dist\cli.js"`
> or `node "$(cygpath -w /c/Projects/agent-harness/dist/cli.js)"`. For persistent
> use, add the project to your `PATH` via native Windows syntax or use
> `npx @ar27111994/agent-harness` from the npm global install. See
> [Troubleshooting](docs/guides/TROUBLESHOOTING.md) for more Windows-specific guidance.

### Optional local environment

Runtime configuration is centralized in `src/config/runtime.ts`. `.env.example` documents supported variables. The CLI automatically loads a `.env` file from the current working directory before dispatching commands, without overriding variables that are already exported by your shell. Use `--no-dotenv` for hermetic CI/smoke runs.
Expand Down Expand Up @@ -1368,6 +1377,10 @@ AGENT_HARNESS_INSTALL_BATCH_SIZE=250
AGENT_HARNESS_SCAN_MAX_DEPTH=14
AGENT_HARNESS_SCAN_MAX_FILES=20000
AGENT_HARNESS_SCAN_MAX_BYTES=50000000
AGENT_HARNESS_MAX_ENTRIES_PER_SOURCE=200
AGENT_HARNESS_SETUP_DOCTOR_HOST_TIMEOUT_MS=5000
AGENT_HARNESS_DISCOVERY_INDEX_MAX_AGE_DAYS=7
AGENT_HARNESS_SOURCE_SYNC_MAX_PAGES_FOR_INDEX_BUILD=500
```

The runtime config exposes diagnostics as a boolean flag at `diagnostics.debugEnabled`; there is no full log-level hierarchy today. The current `AGENT_HARNESS_DEBUG` env var maps directly to `diagnostics.debugEnabled`, so diagnostics can be controlled either through that env var or by reading the resolved runtime config object.
Expand Down Expand Up @@ -1502,11 +1515,15 @@ agent-harness/
├── docs/
│ ├── demo/
│ ├── guides/
│ │ ├── CATALOG-BREADTH.md
│ │ ├── HARNESS-MAINTENANCE-GUIDE.md
│ │ ├── LOGGING-STRATEGY.md
│ │ ├── MAINTENANCE-WORKFLOW.md
│ │ ├── RELEASE-PROCESS.md
│ │ ├── SAFE-DEFAULTS.md
│ │ ├── SEMANTIC-SCORING.md
│ │ ├── SOURCE-PACK-SEEDER.md
│ │ ├── TROUBLESHOOTING.md
Comment on lines +1518 to +1526

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add the new adapter guide to the repository tree.

docs/guides/ADAPTER-DEVELOPMENT.md exists but is missing from this directory listing, making the documented repository structure stale.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 1518 - 1526, Add docs/guides/ADAPTER-DEVELOPMENT.md
to the repository tree listing in README.md, alongside the other entries under
docs/guides, so the documented structure includes the existing adapter guide.

│ │ ├── TRUST-CENTER.md
│ │ ├── V1-TO-V2-UPGRADE.md
│ │ └── V2-CONTRACT.md
Expand Down
58 changes: 58 additions & 0 deletions discover/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Discover Directory

The `discover/` directory contains the static configuration, schema definitions,
source registrations, and editable policy files that drive the agent-harness
discovery pipeline. It is **not** the runtime output directory — generated
catalogs, reports, and indices live under `discover/output/`.

## Directory Overview

| Path | Purpose |
| ------------------------------ | -------------------------------------------------------------------- |
| `sources.json` | Configured discovery sources (registries, repos, marketplaces, docs) |
| `selections.json` | Whitelist/blacklist rules for catalog selection filtering |
| `pipeline.json` | Pipeline stage configuration (enable/disable stages, thresholds) |
| `official-skills-indexes.json` | Known official skills index URLs (first-party verified) |
| `official-upstreams.json` | Known official upstream repository URLs |
| `schema/` | JSON Schema definitions for catalog entries, sources, and selections |
| `seeds/` | Seed data for bootstrapping new catalog entries |
| `source-packs/` | Community and official source pack registrations |
| `recommendation-policy/` | Per-host recommendation scoring and filtering policies |
| `output/` | Runtime-generated catalogs, reports, and indices (gitignored) |

## Source Packs

Source packs in `source-packs/` are grouped into community and official JSON
files. Each entry describes a GitHub repository, organization, or curated list
that should be harvested for agent assets.

### Adding a New Source Pack

1. Identify the target: GitHub username/org, repository URL, or curated list.
2. Choose the appropriate file: `source-packs/community.json` for community
packs, `source-packs/official.json` for verified first-party packs.
3. Add an entry with these required fields:
- `id`: unique identifier (e.g., `"username-project-name"`)
- `authorityTier`: `"official-first-party"`, `"trusted-community"`, or
`"unverified-community"`
- `sourcePriority`: integer (1–100, higher = preferred)
- `endpoints`: object with at least a `repo` URL
- `tags`: array of descriptive tags
Comment on lines +34 to +40

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Document all required source-pack fields.

The checklist omits assetKinds, which is required for source-pack entries according to the v2.0.0 release contract. Add it to prevent contributors from creating invalid pack definitions.

Proposed documentation update 
    - `endpoints`: object with at least a `repo` URL
+   - `assetKinds`: array of supported asset kinds
    - `tags`: array of descriptive tags
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
3. Add an entry with these required fields:
- `id`: unique identifier (e.g., `"username-project-name"`)
- `authorityTier`: `"official-first-party"`, `"trusted-community"`, or
`"unverified-community"`
- `sourcePriority`: integer (1–100, higher = preferred)
- `endpoints`: object with at least a `repo` URL
- `tags`: array of descriptive tags
3. Add an entry with these required fields:
- `id`: unique identifier (e.g., `"username-project-name"`)
- `authorityTier`: `"official-first-party"`, `"trusted-community"`, or
`"unverified-community"`
- `sourcePriority`: integer (1–100, higher = preferred)
- `endpoints`: object with at least a `repo` URL
- `assetKinds`: array of supported asset kinds
- `tags`: array of descriptive tags
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@discover/README.md` around lines 34 - 40, Add the required assetKinds field
to the source-pack entry checklist in the documentation, alongside the existing
required fields, and describe it as an array of asset kinds consistent with the
v2.0.0 contract.

4. Run `discover sync` to harvest the new source.
5. Verify entries appear in `discover/output/catalog.assets.jsonl`.

## Schema Files

JSON Schema files in `schema/` document the expected shape of catalog entries,
source definitions, and selection rules. These are referenced by the manifest
validation pipeline and by external tooling that consumes agent-harness output.

## Related Documentation

- [Catalog Breadth Guide](../docs/guides/CATALOG-BREADTH.md) — building
comprehensive catalogs
- [Semantic Scoring Guide](../docs/guides/SEMANTIC-SCORING.md) — how
recommendations are ranked
- [Source Pack Seeder Guide](../docs/guides/SOURCE-PACK-SEEDER.md) —
programmatic source pack registration
- [Contributing Guide](../CONTRIBUTING.md) — contributing to agent-harness
Loading