Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
{
"name": "brief2ship",
"description": "Search and score existing code before greenfield AI builds, then ship with proof",
"version": "0.6.2",
"version": "0.7.0",
"source": "./",
"author": {
"name": "Michael Costea",
Expand Down
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "brief2ship",
"description": "Repo-first discovery and verified delivery for AI coding agents",
"version": "0.6.2",
"version": "0.7.0",
"author": {
"name": "Michael Costea",
"url": "https://michaelcostea.com/"
Expand Down
15 changes: 14 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,23 @@ jobs:
python-version: ${{ matrix.python }}
cache: pip
- name: Install build tools
run: python -m pip install --upgrade pip build
run: python -m pip install build==1.6.0 ruff==0.16.6 pyright==1.1.411
- name: Critical lint
run: ruff check --select E9,F63,F7,F82 src scripts tests
- name: Type checks
run: pyright
- name: Validate release contract
run: python scripts/validate-release.py
- name: Task-quality benchmark report
run: python scripts/benchmark-discovery.py --output quality-report.json
- name: Build wheel and source archive
run: python -m build
- name: Test extracted source archive
run: >-
python -c "import glob,subprocess,sys;
archives=glob.glob('dist/*.tar.gz');
assert len(archives)==1, archives;
subprocess.check_call([sys.executable,'scripts/check-sdist.py',archives[0]])"
- name: Install built wheel
run: >-
python -c "import glob,subprocess,sys;
Expand All @@ -42,6 +54,7 @@ jobs:
python -m brief2ship --version
brief2ship discover --help
python -c "from brief2ship import DiscoveryConfig, discover; assert DiscoveryConfig and discover"
python scripts/smoke-installed.py

optional-extractor:
name: Optional Trafilatura adapter
Expand Down
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,17 @@
# Changelog

## 0.7.0 - 2026-09-05

- separate discovery health, decision status, and reuse disposition; provider failures, empty retrieval and missing inspections now yield `inconclusive` with CLI exit 5, never a false clean-build recommendation
- decide against the full evaluated set; make `--limit` presentation-only and preserve every evaluated candidate, inspection allocation and selected identity in v2 receipts
- add deterministic core/constraint query planning, bounded GitHub reciprocal-rank fusion, registry core queries and source ranks without model calls or new runtime dependencies
- gate ranking on relevance, use confidence-adjusted decision scores and prefer ready evidence; retain original constraints as unverified checks
- preserve unknown dependency metadata and package/repository evidence scope instead of silently awarding dependency-free credit
- recognize canonical full-text MIT bodies while preserving raw evidence; free-form copyright notices are review-required rather than granted authority through a regex
- add explicit `--summary` JSON output with decision state, source health, counts, score, blockers and receipt paths
- add a synthetic task-quality regression benchmark, pinned lint/type checks, clean installed-wheel smoke and extracted-sdist validation in CI
- document v2 migration and native PowerShell onboarding; update versioned installation routes to v0.7.0 while keeping historical demo evidence pinned

## 0.6.2 - 2026-09-05

- reposition Brief2Ship around its sharpest searchable job: stop AI coding agents rebuilding what already exists
Expand Down
3 changes: 2 additions & 1 deletion MANIFEST.in
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,13 @@ include CONTRIBUTING.md
include CODE_OF_CONDUCT.md
include SECURITY.md
include ROADMAP.md
include pyrightconfig.json
include docs/*.md
recursive-include docs/assets *.gif *.png *.svg *.txt
recursive-include docs/plans *.md
recursive-include skills *.md
recursive-include templates *.md
recursive-include scripts *.py
recursive-include tests *.py
recursive-include tests *.py *.json
recursive-include .github *.md *.yml
recursive-include .claude-plugin *.json
57 changes: 38 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,27 @@ Brief2Ship is a dependency-free Python CLI and portable Agent Skill for **repo-f

![Terminal demo showing Brief2Ship selecting the local repository for reuse after evidence scoring](https://raw.githubusercontent.com/five0nit/brief2ship/v0.6.2/docs/assets/brief2ship-demo.gif)

*Real dogfood receipt: `local/brief2ship`, 70.50/100, inspected, `selective-reuse`. [Read the source transcript](https://github.com/five0nit/brief2ship/blob/v0.6.2/docs/assets/demo-transcript.txt) or [see more decision cases](https://github.com/five0nit/brief2ship/blob/v0.6.2/docs/case-studies.md).*
*Historical v0.6.2 dogfood receipt (not a v0.7.0 result): `local/brief2ship`, 70.50/100, inspected, `selective-reuse`. [Read the source transcript](https://github.com/five0nit/brief2ship/blob/v0.6.2/docs/assets/demo-transcript.txt) or [see more decision cases](https://github.com/five0nit/brief2ship/blob/v0.6.2/docs/case-studies.md).*

## v0.7.0 — reliable reuse decisions

This release adds reliable reuse decisions: explicit `inconclusive` outcomes,
intent-preserving queries, complete evidence receipts, and `--summary` JSON output.
Discovery receipt and scoring contracts are now v2. Read the
[migration and decision guide](docs/code-discovery.md) before updating automation;
exit `5` means insufficient evidence, not permission to build from scratch.
For native Windows setup, see [PowerShell onboarding](docs/windows-powershell.md).

Install **v0.7.0** using the tagged commands below. The demo above is explicitly
pinned to v0.6.2 historical evidence; its result is not a v0.7.0 claim.
PyPI publication remains separate from the GitHub release.

## 30-second quickstart

Run the tagged release without a permanent install:

```bash
uvx --from git+https://github.com/five0nit/brief2ship.git@v0.6.2 \
uvx --from git+https://github.com/five0nit/brief2ship.git@v0.7.0 \
brief2ship discover "local robots-aware web scraper" \
--sources github,pypi,npm,crates,huggingface \
--limit 5 --inspect-top 2 \
Expand All @@ -29,7 +42,7 @@ uvx --from git+https://github.com/five0nit/brief2ship.git@v0.6.2 \
Add a bounded local workspace to the same comparison:

```bash
uvx --from git+https://github.com/five0nit/brief2ship.git@v0.6.2 \
uvx --from git+https://github.com/five0nit/brief2ship.git@v0.7.0 \
brief2ship discover "local robots-aware web scraper" \
--local /path/to/scoped/workspace \
--sources local,github,pypi,npm,crates,huggingface \
Expand All @@ -47,7 +60,8 @@ discovery/
└── worktrees/ # bounded inspection clones when required
```

The result records one explicit disposition:
Conclusive discovery records one explicit disposition (inconclusive runs record
`inconclusive` when evidence cannot support a decision):

- `use-as-library`
- `fork`
Expand Down Expand Up @@ -95,7 +109,7 @@ Brief2Ship inspects manifests, dependency declarations, licenses, tests, CI, doc
### Versioned GitHub release

```bash
uv tool install git+https://github.com/five0nit/brief2ship.git@v0.6.2
uv tool install git+https://github.com/five0nit/brief2ship.git@v0.7.0
brief2ship doctor
```

Expand Down Expand Up @@ -141,13 +155,13 @@ Brief2Ship follows the open [Agent Skills specification](https://agentskills.io/
GitHub CLI 2.90 or newer can install the tagged skill for supported agent hosts:

```bash
gh skill install five0nit/brief2ship brief2ship@v0.6.2
gh skill install five0nit/brief2ship brief2ship@v0.7.0
```

Example host-specific installation:

```bash
gh skill install five0nit/brief2ship brief2ship@v0.6.2 \
gh skill install five0nit/brief2ship brief2ship@v0.7.0 \
--agent claude-code --scope user
```

Expand All @@ -172,7 +186,7 @@ Default profile:

```bash
hermes skills install \
https://raw.githubusercontent.com/five0nit/brief2ship/v0.6.2/skills/brief2ship/SKILL.md \
https://raw.githubusercontent.com/five0nit/brief2ship/v0.7.0/skills/brief2ship/SKILL.md \
--category software-development \
--yes
```
Expand All @@ -182,7 +196,7 @@ Named profile:
```bash
hermes profile create qa --no-alias --no-skills
hermes --profile qa skills install \
https://raw.githubusercontent.com/five0nit/brief2ship/v0.6.2/skills/brief2ship/SKILL.md \
https://raw.githubusercontent.com/five0nit/brief2ship/v0.7.0/skills/brief2ship/SKILL.md \
--category software-development \
--yes
hermes --profile qa skills list
Expand Down Expand Up @@ -252,16 +266,21 @@ See [docs/free-scraping.md](docs/free-scraping.md) and [docs/code-discovery.md](

## Proof and trust

The v0.6.1 compatibility release passed:

- 141 tests on Python 3.11, 3.12, and 3.13;
- seven Linux/Windows GitHub Actions jobs;
- Ruff critical selectors;
- Pyright with 0 errors and 0 warnings;
- clean wheel and extracted-sdist tests;
- live HTTPS positive and hostname-mismatch negative controls.

Current source-checkout evidence is retained at `docs/releases/v0.6.2-discoverability-receipt.md`. Release receipts remain outside built packages so their artifact hashes cannot become self-referential. Historical v0.6.1 evidence remains at `docs/releases/v0.6.1-single-search-skill-receipt.md`.
The v0.7.0 implementation passed local verification:

- 191 tests on Python 3.11, 3.12, and 3.13;
- native Windows validation, with four platform-specific skips;
- 24/24 synthetic decision-regression cases (not real-world accuracy claims);
- Ruff critical selectors and Pyright with 0 errors and 0 warnings;
- clean installed-wheel and extracted-sdist checks;
- independent review and a live five-source discovery probe.

GitHub Actions runs the Linux/Windows matrix and optional Trafilatura adapter on
pull requests and `main`; inspect the CI badge for the current hosted result.
Historical pre-publication evidence is retained at `docs/releases/v0.7.0-local-verification.md`.
Release receipts remain outside built packages so their artifact hashes cannot become self-referential.
Earlier evidence remains at `docs/releases/v0.6.2-discoverability-receipt.md` and
`docs/releases/v0.6.1-single-search-skill-receipt.md`.

## Repository map

Expand Down
22 changes: 16 additions & 6 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,23 @@ Brief2Ship stays deliberately lean. Roadmap items must improve repo-first decisi
- improve first-run examples, error messages, and receipt readability;
- publish small, reproducible decision cases rather than unsupported savings claims.

## Next — v0.7 evidence quality
## v0.7 evidence quality: reliable reuse decisions

- normalize common package-license metadata without weakening hard blockers;
- improve multi-query recall while keeping provider limits deterministic;
- make inspection-budget allocation easier to explain from receipts;
- add fixture-backed examples for local/public deduplication and partial provider failure;
- expose concise summary output without removing the full Markdown/JSON receipt.
- explicit inconclusive decisions for incomplete collection or insufficient evidence;
- display-only limits, complete evaluated/inspection receipts and selected identities;
- bounded core/constraint query planning and relevance/confidence-aware ranking;
- unknown dependency evidence, package/repository scoping and strict full-text MIT normalization;
- concise JSON summary alongside full v2 receipts;
- synthetic task-quality regressions plus automated lint/type/wheel/sdist gates.

Included in v0.7.0. PyPI publication and broader host validation remain separate work.

## Next evidence-quality work

- human-reviewed real-world briefs and provider recall benchmarks, beyond synthetic regression fixtures;
- package-subtree identification for monorepos before claiming package-specific test readiness;
- additional canonical license formats with conservative, fixture-backed normalization;
- better source-budget fairness and explainable query recall without mandatory model calls.

## Later — only with demonstrated demand

Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.6.2
0.7.0
Loading
Loading