sherparc 0.8.1__tar.gz

sherparc-0.8.1/LICENSE

@@ -0,0 +1,161 @@
+Sherpa — Copyright (c) 2026 Andrei Chirila
+
+Required Notice: Copyright Andrei Chirila (https://github.com/sherparc/Sherpa)
+
+Sherpa is licensed under the PolyForm Small Business License 1.0.0 or the
+PolyForm Noncommercial License 1.0.0, at your option
+(SPDX: PolyForm-Small-Business-1.0.0 OR PolyForm-Noncommercial-1.0.0).
+Both texts follow below, unchanged. In short: free for personal use, for
+noncommercial organisations, and for companies with fewer than 100 people and
+under USD 1M revenue; a company above those limits needs a commercial licence
+— a.chirila87@gmail.com. Reasoning: docs/adr/0051-public-release-polyform-small-business-or-noncommercial.md.
+
+Output exception (an additional permission granted by the licensor): files
+that Sherpa generates in your repository — plans, state files, owner docs,
+agent and skill definitions, and any other output of `sherpa plan` or
+`sherpa apply` — belong to you. They carry no obligation under either licence,
+regardless of how you obtained Sherpa.
+
+================================================================================
+
+# PolyForm Small Business License 1.0.0
+
+<https://polyformproject.org/licenses/small-business/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## Small Business
+
+Use of the software for the benefit of your company is use for a permitted purpose if your company has fewer than 100 total individuals working as employees and independent contractors, and less than 1,000,000 USD (2019) total revenue in the prior tax year.  Adjust this revenue threshold for inflation according to the United States Bureau of Labor Statistics' consumer price index for all urban consumers, U.S. city average, for all items, not seasonally adjusted, with 1982–1984=100 reference base.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.
+
+================================================================================
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

sherparc-0.8.1/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: sherparc
+Version: 0.8.1
+Summary: Generic AI-harness generator: scan the codebase, plan owner docs, agents and skills, create them after approval.
+License-Expression: PolyForm-Small-Business-1.0.0 OR PolyForm-Noncommercial-1.0.0
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: jsonschema>=4; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file

sherparc-0.8.1/README.md

@@ -0,0 +1,289 @@
+<div align="center">
+
+# Sherpa
+
+<img src="assets/sherpa-mark.png" width="132" alt="Sherpa">
+
+**Your repository grows. Your AI agents lose the plot.**
+
+Sherpa analyses your codebase deterministically (like CodeScene) and plans the knowledge architecture for AI assistants from it (like Terraform): owner docs, specialised agents, skills, librarians, evals. You review the plan — Sherpa sets it up after your approval.
+
+Sherpa reads your git history and gives a reason for every proposal — and for every no. It writes into the repository you already have, for the runtimes you already use: Claude Code natively, every `AGENTS.md` reader (Codex, Cursor, Copilot, Gemini CLI, OpenCode, Hermes) through one neutral core, one thin adapter per host on the roadmap.
+
+[![CI](https://github.com/sherparc/Sherpa/actions/workflows/ci.yml/badge.svg)](https://github.com/sherparc/Sherpa/actions/workflows/ci.yml)
+![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
+![Status: scan, plan, apply, adopt, doctor live](https://img.shields.io/badge/status-scan%20%2B%20plan%20%2B%20apply%20%2B%20adopt%20%2B%20doctor%20live-brightgreen)
+[![Release](https://img.shields.io/github/v/release/sherparc/Sherpa?include_prereleases&label=release)](https://github.com/sherparc/Sherpa/releases)
+
+</div>
+
+---
+
+<a href="assets/demo.svg"><img src="assets/demo.svg" alt="sherpa plan on the Sherpa repository itself: five proposals, three reasoned no's, every line with its evidence" width="100%"></a>
+
+`sherpa plan .` on this repository — the real output, rendered as an SVG by [scripts/render-demo.py](scripts/render-demo.py) and refreshed with every release. An agent for the whole package was proposed, rejected by hand, and the rejection is kept (`[reject]`); two small modules get a reasoned no with the knob that would change it.
+
+## From repo to AI harness in 60 seconds
+
+Live today — real output on a test repo with five Python modules, Django migrations and a test suite
+(`active_repo` in [tests/test_plan.py](tests/test_plan.py), frozen as a [golden](tests/goldens/active-console.txt)):
+
+```console
+$ sherpa plan .
+harness-plan.yaml — 6 proposals, 4 reasoned no's
+  + outcome     shop                          mandatory: no harness without an outcome signal (ADR-0008) ✓
+  + owner-doc   pay                           24 commits/90d, 1 dependents ✓ · 40 files ✓
+  + owner-doc   core                          1 commits/90d, 2 dependents ✓ · 3 files ✓
+  + agent       pay                           rank 1/4 churn ✓ · 24 commits/90d ✓ · 40 files ✓ · 2 authors ✓
+  + test-infra  suite                         26 commits/90d vs. 24 (pay) ✓
+  + skill       regenerate-django-migrations  svc/pay/pay/migrations · 6 generated files, 1 configs ✓
+  - owner-doc   web                           1 commits/90d, 0 dependents ✓ · 3 files ✗
+  - owner-doc   old                           0 commits/90d, 0 dependents ✗ · 2 files ✗
+  - librarian   pay                           rank 1/4 momentum ✓ · 24 commits/30d, 24/90d ✗
+  - librarian   core                          rank 2/4 momentum ✓ · 1 commits/30d, 1/90d ✗
+  1 dormant units without owner doc (0 commits/90d, 0 dependents): old — the first commit turns them into a proposal; each is listed above as a no.
+  1 small units without owner doc (< 5 files, 0 dependents): web — listed above as no's; owner_doc_min_files in sherpa.toml [plan] moves the floor, a dependent overrides it.
+  not listed, out of reach: 2 units for agent (rank > 1 and < 20 commits/90d), 1 for librarian (rank > 2 and below both floors).
+→ .sherpa/harness-plan.yaml
+```
+
+Every line can be recomputed: the rank from the ranking in the plan header, the floors from `sherpa.toml [plan]`.
+The migrations directory gets no agent but a skill with source, config and command — **generated code is
+regenerated, not explained.** Dormant modules and everything out of reach show up in the notes; nothing disappears
+silently.
+
+Then `sherpa apply` — dry run first, like `terraform plan` (golden [active-apply-console.txt](tests/goldens/active-apply-console.txt)):
+
+```console
+$ sherpa apply .
+targets: claude, agents-md · home: .agents
+sherpa apply — plan origin/main@5db69c4ddd: 10 entries, 5 selected → 18 files
+  + .agents/docs/modules/core.md                          owner-doc core                new
+  + .agents/docs/modules/pay.md                           owner-doc pay                 new
+  + .agents/docs/modules/suite.md                         test-infra suite              new
+  + .agents/scripts/sherpa-check.py                       harness                       new
+  + .agents/skills/regenerate-django-migrations/SKILL.md  skill regenerate-django-migrations  new
+  + .claude/agents/pay.md                                 agent pay                     new
+  + .claude/hooks/sherpa-outcome.py                       harness                       new
+  + .claude/settings.json                                 harness                       new
+  + .claude/skills/regenerate-django-migrations/SKILL.md  skill regenerate-django-migrations  new
+  + .sherpa/telemetry/.gitignore                          harness                       new
+  + AGENTS.md                                             harness                       new
+  + CLAUDE.md                                             harness                       new
+  + svc/core/AGENTS.md                                    owner-doc core                new
+  + svc/core/CLAUDE.md                                    owner-doc core                new
+  + svc/pay/AGENTS.md                                     owner-doc pay                 new
+  + svc/pay/CLAUDE.md                                     owner-doc pay                 new
+  + tests/suite/AGENTS.md                                 test-infra suite              new
+  + tests/suite/CLAUDE.md                                 test-infra suite              new
+18 to add, 0 to change, 0 unchanged, 0 skipped.
+apply? [y/N] y
+check: 0 FAIL, 0 WARN
+18 files written · harness_rev c38498363846 → .sherpa/state.json
+```
+
+The owner doc under `.agents/` gets a facts block from the scanner (path, LOC, commits, authors, dependencies,
+dependents, tests, hotspots — [golden](tests/goldens/active-owner-doc-pay.md)); every module gets a nested
+`AGENTS.md` with its facts ([golden](tests/goldens/active-agents-md-pay.md)) — the file Codex, Cursor, Gemini CLI
+and Copilot load when they work there — and a `CLAUDE.md` that imports it; the Claude agent gets a knowledge
+manifest that points at the owner doc ([golden](tests/goldens/active-agent-pay.md)); the migrations directory
+gets its skill; the outcome hook labels every Claude Code execution with the harness version from day one. Run it again: eighteen `=`, `nothing to do.`
+Sherpa owns only the marked blocks — write anything else into those files, it stays.
+
+Already have a harness? `sherpa adopt` takes it into the state without changing a byte — like `terraform import`
+(golden [active-adopt-console.txt](tests/goldens/active-adopt-console.txt)):
+
+```console
+$ sherpa adopt .
+sherpa adopt — home .claude · targets claude: 7 harness files
+  a .claude/agents/ops.md           agent    no unit matches
+  a .claude/agents/pay-expert.md    agent    → agent pay (mentions svc/pay 170×)
+  a .claude/docs/modules/pay.md     doc      at sherpa's path, yours — covers the entry
+  ? .claude/notes.txt               unknown  yours
+  · CLAUDE.md                       root     no sherpa markers — `apply` appends its block (ADR-0016)
+gaps:
+  - .claude/agents/pay-expert.md: 175 lines, no knowledge manifest — rotation candidate, facts belong in an owner doc
+  - .claude/docs/modules/legacy.md: no unit matches by name or path mentions — moved, renamed or not a module doc
+state: 6 adopted, 0 rebuilt, 0 kept, 0 dropped · harness_rev 592b1a201d0c → .sherpa/state.json · 2 plan entries covered → .sherpa/harness-plan.yaml
+```
+
+The next `sherpa plan` shows `[covered by .claude/agents/pay-expert.md]` on the agent entry and `apply` creates
+nothing there ([golden](tests/goldens/active-plan-covered-console.txt)). The same command rebuilds a lost or torn
+`.sherpa/state.json` from the files — same `harness_rev` as `apply` wrote (ADR-0017).
+
+- `sherpa scan` 🟢 **Live** — deterministic codebase model (git churn, hotspots, modules, dependencies, generators)
+- `sherpa plan` 🟢 **Live** — proposals and reasoned no's with evidence as YAML; decisions survive a re-plan or come from the command line (`--accept agent:pay`)
+- `sherpa apply` 🟢 **Live** — dry run first, managed blocks, state file, outcome hook, checker with rollback; targets `claude` and `agents-md` from one neutral core
+- `sherpa status` · `sherpa check` 🟢 **Live** — drift per file and block, structural rules, outcome labels per harness version
+- `sherpa adopt` 🟢 **Live** — take an existing harness into the state without changing a byte; files that already fill a plan entry cover it, and a nested `AGENTS.md` at a unit's own path is its owner doc (no skeleton next to it); a lost state is rebuilt from the files
+- `sherpa doctor` · `sherpa self-update` 🟢 **Live** — every prerequisite with a fix; the next release via the installer that owns this copy; a daily hint that never blocks
+
+Documentation: [docs/index.md](docs/index.md) — [getting started](docs/getting-started.md), one reference page per command ([scan](docs/commands/scan.md), [plan](docs/commands/plan.md), [apply](docs/commands/apply.md), [adopt](docs/commands/adopt.md), [status](docs/commands/status.md), [check](docs/commands/check.md), [doctor](docs/commands/doctor.md), [self-update](docs/commands/self-update.md)), [configuration](docs/reference/configuration.md); milestones: [docs/plan.md](docs/plan.md).
+
+## Quick start
+
+One line, no clone — the wheel `sherparc` is on [PyPI](https://pypi.org/project/sherparc/) and attached to every [release](https://github.com/sherparc/Sherpa/releases); `sherpa self-update` fetches the next one:
+
+```bash
+uv tool install sherparc                                         # or: pipx install sherparc; from the repository: …install git+https://github.com/sherparc/Sherpa.git
+sherpa doctor                                                    # Python, git, origin, trunk, runtime, layout, nested repositories, install, update — with a fix each
+sherpa plan /path/to/repo                                        # scans when needed → .sherpa/harness-plan.yaml
+sherpa apply /path/to/repo                                       # dry run, then asks → .claude/**, .sherpa/state.json
+sherpa adopt /path/to/repo                                       # an existing harness enters the state, not a byte changes
+sherpa status /path/to/repo                                      # drift, checks, outcome labels
+sherpa check /path/to/repo                                       # the structural rules alone (also as a deployed copy, no sherpa needed)
+sherpa apply /path/to/repo --remove                              # the uninstall: takes back what sherpa wrote and nobody changed
+sherpa scan /path/to/repo --out -                                # model only, JSON to stdout
+```
+
+For development, the classic way:
+
+```bash
+git clone git@github.com:sherparc/Sherpa.git && cd Sherpa
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+```
+
+Optional `sherpa.toml` in the target repo:
+
+```toml
+[scan]
+trunk = "origin/develop"      # otherwise: origin/HEAD, then main/master/dev/develop/trunk
+hotspots = 20
+generated = ["gen/**"]        # own generator family, extends the built-in ones
+
+[plan]
+agent_top = 0.25              # top quartile by commits/90d …
+agent_min_commits_90d = 20    # … and floors; all values in docs/reference/configuration.md
+```
+
+## What the scanner measures
+
+- **T0 git** — trunk detection, commits/authors in 90- and 30-day windows, LOC per file, hotspots (`commits_90d × loc`, generated files excluded), directory churn.
+- **T1 modules** — from manifests for .NET (`.csproj`), Python (`pyproject.toml`), Node (`package.json`), Go (`go.mod`), Rust (`Cargo.toml`), Java (`pom.xml`, Gradle); in-repo dependencies in both directions, test modules and `tested_by`, module churn, conventions (languages, CI, containers).
+- **Change coupling** — which modules change together (Tornhill's temporal coupling), measured only on commits below a size cap so squash-merge trunks stay honest; one row in every facts block: `changes together with: core (15 of 24 commits, 62 %)`. Sub-directories per module make a single-package repository a plan with units too.
+- **Generator families** — EF/Django/Alembic migrations, protobuf, OpenAPI, GraphQL codegen, ResX, `go generate`, snapshots, bundles, lockfiles: per family output, sources, config, central place and regeneration command — by path only, in 30 ms for 15k files.
+- **T2 language adapters** (M3b) — anchors and patterns per language; T0/T1 work without them.
+
+All fields are described in the JSON schema: [codebase-model.schema.json](src/sherpa/schemas/codebase-model.schema.json). Details, decisions and interpretation: [docs/concepts/scan.md](docs/concepts/scan.md).
+
+## What the planner decides
+
+Thresholds are **relative with an absolute floor** — top quartile *and* at least 20 commits, 30 files, 2 authors
+for an agent; top 2 by momentum *and* a floor for a librarian. A five-person repo gets an agent, a fifty-module
+repo does not get thirty. Every no names what is missing and when it flips. Modules and directories without a
+module (`infrastructure/`, `pipelines/`) rank on equal terms; test infrastructure is measured against the most
+active business module. Rules, format and configuration: [docs/concepts/harness-plan.md](docs/concepts/harness-plan.md).
+
+### Determinism guarantees
+
+- Always against `origin/<trunk>`, never against the checked-out `HEAD` (local branches are invisible).
+- `as_of` = committer date of the trunk rev → same rev, same model, byte-identical (tested).
+- Sorted JSON output, no merge commits in the time windows, no LLM calls in the scanner.
+
+## Why Sherpa
+
+Why not just write a few `.md` files for Claude or Copilot?
+
+- **No more guessing.** Sherpa builds on hard data — commits, authors, LOC, churn — not on gut feeling. Every proposal carries its evidence, every no its reason.
+- **Infrastructure as code for knowledge.** `plan` → approval → `apply`, like Terraform. You see every file before it exists; Sherpa owns only marked blocks inside the files, the rest is yours and stays yours.
+- **Does not wreck your repo.** Sherpa never overwrites what exists — it creates, appends and merges, and rewrites only its own unchanged bytes. Deterministic against `origin/trunk`, local branches invisible, idempotent with a state file, a checker that rolls back a bad write.
+- **Measures itself.** Every `apply` installs the outcome hook first: each Claude Code execution gets a label (`success`, `failed`, `unknown`) stamped with the harness version. A harness change has a number to answer to.
+- **Grows with you.** Librarians keep owner docs current, evals come from the dependency graph, and the outcome shows which harness parts really help — nothing on the market does that.
+
+Where the patterns come from:
+
+| Proven on the market | What Sherpa takes from it |
+|---|---|
+| Terraform `plan` / `apply` / `import` / state | proposal before change, approval, idempotency, `adopt` for existing harnesses |
+| CodeScene / Tornhill hotspots | churn × complexity instead of gut feeling; relative thresholds with an absolute floor |
+| Backstage catalog / scaffolder | modules as a catalogue, templates seeded once |
+| `AGENTS.md` / Agent Skills (Codex, Cursor, Gemini CLI, Copilot, …) | proximity loading — the closest file wins — filled with measured facts and kept current instead of hand-written |
+| Ansible `blockinfile` | managed blocks inside co-authored files instead of all-or-nothing ownership |
+| Renovate | librarians as bots with scope and cadence |
+| `brew doctor` | `sherpa doctor` for onboarding |
+
+## Architecture
+
+```mermaid
+flowchart LR
+    R[(repo · origin/trunk)] -->|git, manifests| S[sherpa scan]
+    S --> M[codebase-model.json]
+    M --> P[sherpa plan]
+    P --> Y[harness-plan.yaml<br/>proposals + reasoned no's<br/>--accept / --reject]
+    Y -->|approval| A[sherpa apply]
+    A --> H["{home}/** owner docs · skills · checker<br/>(home = .agents or .claude)"]
+    A --> T["adapters per target<br/>claude: .claude/agents · hooks · CLAUDE.md<br/>agents-md: AGENTS.md root + nested<br/>planned, thin on agents-md: hermes · codex · opencode · copilot · cursor · gemini"]
+    A --> ST[.sherpa/state.json · harness_rev]
+    T -->|outcome hook| O[.sherpa/telemetry/outcomes.ndjson]
+    ST --> Q[sherpa status]
+    O --> Q
+    H --> C[sherpa check<br/>rollback on a new FAIL]
+    T --> C
+    H -.->|existing| AD[sherpa adopt] -.-> ST
+    P -. planned, M6-lite: comments only .-> L[LLM provider<br/>OpenAI-compatible · Anthropic]
+```
+
+- Python 3.12, stdlib-first, one runtime dependency (PyYAML for the plan).
+- Scanner, planner and applier are deterministic today; no LLM call anywhere in the shipped pipeline.
+- Planned (M6-lite): LLMs only in `plan` stage 2, enriching comments, never the entries themselves.
+- Planned (M6-lite): a provider layer without LangChain — local vLLM/Ollama/OpenRouter via the OpenAI API plus Anthropic natively.
+
+## Roadmap
+
+| Milestone | Content | Status |
+|---|---|---|
+| M0 | skeleton, ADRs, the plan | ✅ |
+| M1 | scanner T0 for every language: trunk, churn, hotspots, file tree, generated files, JSON schema | ✅ |
+| M1a | scanner T1: modules from manifests (6 ecosystems), in-repo deps, `tested_by`, churn per module | ✅ |
+| M2 | `plan` stage 1: units, rank + floor, generator families → skills, reasoned no's, decision keeping | ✅ |
+| M3a | `apply`: dry run, managed blocks, state, outcome hook, checker with rollback; `status`, `check` | ✅ |
+| M3t | target layer: neutral core under `.agents`/`.claude`, adapters `claude` and `agents-md`, nested proximity files | ✅ |
+| M3c | `adopt`: existing harnesses taken over unchanged, covered entries, rebuildable state | ✅ |
+| M2b | distribution: release wheel per tag, `doctor`, `self-update` (API with a token, `git ls-remote` without), daily hint | ✅ |
+| M3d | retro fruit: stamp without rev, sub-units for single-manifest repos, change coupling with a size cap, `plan --accept/--reject`, capped root index | ✅ |
+| M3e | review fruit: `status` names a stale plan, `status --json` and `doctor --json`, manifest tie-break by language share, coupling without the root catch-all, sub-units for a dominant root module, proximity-file budgets in the checker | ✅ |
+| M3f | write safety: `apply` compares every file with the preview's read before writing, never writes through a symlink, writes each file whole or not at all and rolls back on a write error; `adopt` treats a differing base file as yours, takes a stale plan and rebuilds a torn state without a dead end; a dry run never refuses (two homes → assumes `.agents` and says so) and names a target directory that is a repository of its own | ✅ |
+| M3i | the manager sees what exists and takes back what is sherpa's: refuses on a nested repository (`doctor` says it first), a hand-written `covered:` is kept like a decision, the checker fails only in sherpa's own files; `apply` removes a rejected entry's files when they are still sherpa's and `apply --remove` uninstalls — a clean repository is clean again | ✅ |
+| M3j | owner docs where the team already writes them: a nested `AGENTS.md` at a unit's own path covers its owner-doc entry — `plan` sets it from the file, `adopt` reports it, `apply` writes the facts block into the team's file and no skeleton next to it (first slice, ADR-0049) | ✅ |
+| M2c | public release: the licence flipped to PolyForm Small Business or Noncommercial (ADR-0051) ✅ · the contribution path — DCO checked on every pull request, code of conduct, security policy, templates (ADR-0052) ✅ · the wheel on PyPI as `sherparc` through trusted publishing, `self-update` and `doctor` read the index first (ADR-0053, ADR-0054) ✅ · the demo card at the top of this README, Sherpa on itself ✅ · still to do: a changelog, then the announcement | ⏳ |
+| M3h | `hermes` target: Hermes Agent reads the harness (`AGENTS.md` chain, `.agents/skills`), outcome hook for both runtimes, `doctor` checks for trust and hook wiring | ⏳ |
+| M3k | host adapters `codex`, `opencode`, `copilot`, `cursor`, `gemini` — thin on top of `agents-md` like `hermes`: `doctor` names the host, its native rule file only where `AGENTS.md` cannot carry it, the outcome hook where the host has hooks | ⏳ |
+| M5 | outcome evaluation: `status` shows labels per `harness_rev` with `n` and the share of `unknown`; a comparison between revisions from 30 labelled executions each | ⏳ |
+| M7a | runtime plugins: Sherpa installable inside Claude Code (plugin) and Hermes (bundle) — `/sherpa-plan` with per-entry approval, `/sherpa-apply`, `/sherpa-status`; thin, the CLI does the work | ⏳ |
+| M6-lite | provider layer: thin, framework-free — bring your own key, local models via the OpenAI API, Anthropic natively | ⏳ |
+| M4 | auto-evals from the dependency graph, `status` with a baseline | ⏳ |
+| M6 | `plan` stage 2: LLM enrichment on top of the provider layer | ⏳ |
+| M3b | language adapters `dotnet` + `python` (T2: anchors, patterns) | ⏳ |
+| M7 | librarians, multi-repo | ⏳ |
+
+Order from here: M3j's second slice → M3h → M3k → M5 → M7a → M6-lite → M4 → M6 → M3b → M7 (plan §7.3, §9, §9.1, §10, §13).
+
+Complete with reasoning: [docs/plan.md](docs/plan.md) · every decision as an ADR: [docs/adr/](docs/adr/README.md)
+
+## Related
+
+| Project | What it is | Where Sherpa differs |
+|---|---|---|
+| [metaharness](https://github.com/ruvnet/metaharness) | a factory: scaffolds a new, branded agent-harness package (own `npx` CLI, MCP server, signed releases) from a static read of manifests, for ten hosts | Sherpa writes into the repository you have, from its git history, with a reason for every entry and every no, and keeps it current — `adopt`, `status`, outcome labels per harness version |
+| Claude Code `/init`, auto-memory · Hermes Agent's self-written skills | the runtimes' own way to grow a harness: LLM prose, per person, unreviewed | facts from `git log`, deterministic, reviewed in the PR like code, per team and repository; runtime-neutral (plan §9) |
+
+## License
+
+[PolyForm Small Business 1.0.0](LICENSE) or [PolyForm Noncommercial 1.0.0](LICENSE), at your option: free for personal use, for noncommercial organisations and for companies under 100 people and USD 1M revenue; larger companies need a commercial licence. Everything Sherpa generates in your repo is yours, no strings attached. Reasoning in [ADR-0051](docs/adr/0051-public-release-polyform-small-business-or-noncommercial.md).
+
+## Development
+
+```bash
+.venv/bin/pytest -q --cov=sherpa       # 439 tests, ~97 % coverage, gate in CI: 90 %
+.venv/bin/ruff check . && .venv/bin/ruff format --check .
+```
+
+CI runs with Python 3.12 and 3.13: Linux on every pull request, Linux and Windows on `main`, macOS weekly; a manual run covers all three. Test repos are built programmatically (no corpus in the repo). The repository carries its own harness — `sherpa status .` must be clean before a commit — and an architect agent under [.claude/agents/](.claude/agents/architect.md). Working rules for humans and agents: [CLAUDE.md](CLAUDE.md).
+
+`main` changes only through pull requests with squash merge, every commit signed off (DCO). Once per clone, enable the hooks — the guard that refuses direct pushes to `main` and the one that adds the sign-off:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+Contributions: [CONTRIBUTING.md](CONTRIBUTING.md) · security reports: [SECURITY.md](SECURITY.md) · conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

sherparc-0.8.1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sherparc"  # the PyPI name: "sherpa" is taken, the org name is one word (ADR-0054); import package and CLI stay "sherpa"
+version = "0.8.1"
+description = "Generic AI-harness generator: scan the codebase, plan owner docs, agents and skills, create them after approval."
+license = "PolyForm-Small-Business-1.0.0 OR PolyForm-Noncommercial-1.0.0"  # ADR-0051: free for individuals, noncommercial organisations and small companies
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["pyyaml>=6"]  # the only runtime dependency (ADR-0005)
+
+[project.scripts]
+sherpa = "sherpa.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5", "jsonschema>=4", "ruff>=0.6"]  # jsonschema: the reference the stdlib validator is tested against (ADR-0042), never a runtime dependency
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sherpa = ["schemas/*.json", "apply/assets/*.py"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E501"]   # fixture literals (manifest contents) are deliberately long

sherparc-0.8.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sherparc-0.8.1/src/sherpa/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.8.1"