willow-reconciler 0.2.0__tar.gz

willow_reconciler-0.2.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [rudi193-cmd]

willow_reconciler-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Something does the wrong thing
+labels: bug
+---
+
+## What happened
+
+<!-- The wrong behavior, plainly. -->
+
+## What should have happened
+
+<!-- The right behavior, plainly. -->
+
+## Receipts
+
+<!-- How to reproduce: exact commands, versions, OS. Paste real
+     output, not a paraphrase. If data/privacy is involved, redact
+     values but keep the shape. -->
+
+## Blast radius
+
+<!-- What it breaks, who hits it, any workaround you found. -->

willow_reconciler-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security report
+    url: https://github.com/willow-memory/willow-reconciler/security/advisories/new
+    about: Exploitable findings go here privately — never in a public issue.

willow_reconciler-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Something this tool should do
+labels: enhancement
+---
+
+## Bite
+
+<!-- One sentence — the single outcome you want. -->
+
+## Why
+
+<!-- The gap or friction that makes this worth building. A real
+     scenario beats an abstraction. -->
+
+## Out of scope
+
+<!-- What this deliberately is NOT asking for, if you can see the line. -->

willow_reconciler-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,31 @@
+## Bite
+
+<!-- One sentence — the single outcome this PR delivers.
+     Follow-up to a merged PR? Say so: "Follow-up to #NN (merged)". -->
+
+## What was done
+
+<!-- Bullets, boldest fact first. If two unrelated changes rode this
+     branch, flag them separately so they can be reviewed (or split) cleanly. -->
+
+## Evidence
+
+<!-- Receipts, not claims. Check only what you actually ran, and state the result. -->
+- [ ] Tests: `python -m pytest tests/ -q` → N passed
+- [ ] Gates: `<gate command>` → clean
+- [ ] Driven for real: <!-- what you exercised end-to-end, and what you saw -->
+
+## Idea-Id trailer
+
+<!-- If a commit here lands an idea recorded in a fleet doc, it carries an
+     `Idea-Id: <corpus>-<docslug>-<num>` trailer (add `Idea-Status: partial`
+     if it only partly lands it). See CONVENTION.md. Tick when it applies. -->
+- [ ] Not applicable, or the trailer is present on the landing commit(s).
+
+## Out of scope
+
+<!-- What this deliberately does not do, and where that work lives. -->
+
+## Next bite
+
+<!-- The single next bite this opens, if any. -->

willow_reconciler-0.2.0/.github/workflows/release-please.yml

@@ -0,0 +1,64 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Mint a willow-ci installation token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ vars.WILLOW_CI_APP_ID }}
+          private-key: ${{ secrets.WILLOW_CI_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+          token: ${{ steps.app-token.outputs.token }}
+
+      - uses: googleapis/release-please-action@v5
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      - name: Arm auto-merge on the release PR
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          pr=$(gh pr list --repo "$REPO" --state open --json number,headRefName \
+                 --jq '[.[] | select(.headRefName | startswith("release-please--"))]
+                       | first | .number // empty')
+          if [ -z "$pr" ]; then
+            echo "No open release PR — nothing releasable since the last tag."
+            exit 0
+          fi
+          # Arming can fail for reasons that are not this job's fault (most
+          # commonly: the default branch has no required status checks, so
+          # GitHub refuses enablePullRequestAutoMerge). That must not fail the
+          # release-please job — but it must not be silent either. A bare
+          # `|| true` hid exactly this for six releases, during which every
+          # release PR merged immediately and published to PyPI before CI ran.
+          if ! out=$(gh pr merge --auto --merge "$pr" --repo "$REPO" 2>&1); then
+            echo "::warning::could not arm auto-merge on PR #${pr}: ${out}"
+            echo "::warning::the release PR is open and must be merged by hand"
+          else
+            echo "auto-merge armed on PR #${pr}"
+          fi

willow_reconciler-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: Release
+
+# Publishes to PyPI when a version tag is pushed (e.g. `git tag v0.2.0 && git push origin v0.2.0`).
+# release-please (release-please.yml) opens the release PR, bumps the version in
+# pyproject.toml (release-type: python) and CHANGELOG.md, and tags on merge.
+#
+# Auth: Trusted Publishing (OIDC). Register on PyPI as:
+#   project: willow-reconciler
+#   repository: willow-memory/willow-reconciler
+#   workflow: release.yml
+#   environment: pypi
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Assert the tag matches the built version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          built="$(ls dist/willow_reconciler-*.tar.gz | sed -E 's|.*/willow_reconciler-(.+)\.tar\.gz|\1|')"
+          echo "tag=${tag}  built=${built}"
+          if [ "$tag" != "$built" ]; then
+            echo "::error::tag v${tag} builds version ${built} — refusing to publish"
+            exit 1
+          fi
+
+      - name: Check metadata
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

willow_reconciler-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,39 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test-matrix:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[test]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -q
+
+  test:
+    needs: [test-matrix]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Assert every matrix leg actually succeeded
+        if: ${{ needs.test-matrix.result != 'success' }}
+        run: |
+          echo "::error::test-matrix did not succeed (result: ${{ needs.test-matrix.result }})"
+          exit 1
+      - run: echo "all matrix legs green"

willow_reconciler-0.2.0/.github/workflows/trailers.yml

@@ -0,0 +1,41 @@
+name: Trailers
+
+# Guards the join key the classifier trusts most. `reconciler verify` resolves
+# every Idea-Id trailer in this repo's history against docs/ideas.md and exits
+# non-zero on one that names an item the doc does not contain. A dangling
+# trailer is worse than a missing one: rule 2a asserts LANDED from it ahead of
+# every other inferred signal, and nothing else in the rule stack can tell a
+# real id from a plausible-looking dead one.
+#
+# A history with no trailers passes — the convention is prospective by design.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  verify-trailers:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # verify reads the whole history; the default shallow clone would
+          # hide every trailer written before the last commit and pass
+          # vacuously.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: pip install -e .
+
+      - name: Verify Idea-Id trailers resolve
+        # --repo is resolved against the package's own location, not the cwd,
+        # so this works from anywhere: on a runner the checkout sits at
+        # <work>/willow-reconciler/willow-reconciler, whose parent is the
+        # fleet root the sibling lookup expects.
+        run: reconciler verify --repo willow-reconciler --doc docs/ideas.md

willow_reconciler-0.2.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+.venv/

willow_reconciler-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

willow_reconciler-0.2.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Conventional Commits](https://www.conventionalcommits.org/) and this file is
+maintained by [release-please](https://github.com/googleapis/release-please).
+
+## [0.2.0](https://github.com/willow-memory/willow-reconciler/compare/v0.1.0...v0.2.0) (2026-09-11)
+
+
+### Added
+
+* close the write-side loop for the Idea-Id convention ([717c877](https://github.com/willow-memory/willow-reconciler/commit/717c87786a13df54053ef1c2d13d088517059e74))
+* close the write-side loop for the Idea-Id convention ([d01cdb0](https://github.com/willow-memory/willow-reconciler/commit/d01cdb0af18c1032d83d4e9e0a9a270674bfd140))
+
+
+### Fixed
+
+* anchor legend-tag regexes so a mid-prose marker is not a tag ([9c8be17](https://github.com/willow-memory/willow-reconciler/commit/9c8be17416898ebc6c7ff80811e9a127ccd47736))
+* close two false-LANDED paths found by adversarial audit ([46d18bd](https://github.com/willow-memory/willow-reconciler/commit/46d18bd5bbc9b4065ddf11a005cddb8df59f66b5))
+
+## 0.1.0 (2026-09-11)
+
+
+### Added
+
+* Initial Slice 0 idea-to-landing reconciler: reads a fleet doc's numbered
+  items and the target repo's own git history, then reports — deterministically
+  and stdlib-only, with no model call — how many proposed ideas have landed,
+  partially landed, or show no evidence of having started.
+* An honest, non-circular hold-out acceptance test (`reconciler validate`
+  wiring in `validate.py`): the legend tag is stripped from each hand-tagged
+  item before reclassification, so the score measures what the tool can
+  actually recover rather than echoing a tag it just read.
+* The `Idea-Id` commit-trailer convention (see `CONVENTION.md`) that gives the
+  reconciler a durable join key going forward.

willow_reconciler-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Code of Conduct
+
+This organization adopts the [Contributor Covenant, version 2.1][covenant], in full and without
+modification, as the code of conduct for every repository here, including
+willow-memory/willow-reconciler.
+
+The canonical text is at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>.
+
+In short: participate in a way that would not embarrass you if quoted. Assume good faith,
+disagree about the work rather than the person, and accept that maintainers may decline a
+contribution without that being an insult.
+
+## Scope
+
+This applies in every space the organization controls — issues, pull requests, discussions,
+commit messages, and code review across all repositories — and whenever someone is representing
+the project in public.
+
+## Reporting
+
+Report unacceptable behavior to **[@rudi193-cmd](https://github.com/rudi193-cmd)** by opening a
+private report through GitHub's **"Report a vulnerability"** form on this organization's
+[`.github` Security tab][report]. Say plainly that it is a conduct report; it will not be
+treated as a security matter.
+
+[report]: https://github.com/willow-memory/.github/security/advisories/new
+
+If the report concerns that maintainer, contact any other organization owner directly.
+
+## Enforcement
+
+Maintainers may take any action they judge proportionate, including editing or removing
+contributions, and temporary or permanent bans from the organization. The Contributor Covenant's
+enforcement guidelines describe the ladder that is normally followed.
+
+---
+
+[covenant]: https://www.contributor-covenant.org/version/2/1/code_of_conduct/

willow_reconciler-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+This repo (willow-memory/willow-reconciler) shares one working method with the
+rest of the fleet, whether the contributor is a person or an agent.
+
+## The method
+
+- **One bite at a time.** A PR delivers one outcome.
+- **Receipts, not claims.** The PR template asks for Evidence — check
+  only what you actually ran, and state the result.
+- **Verify in a clean environment.** If you touched dependencies, prove
+  the suite in a clean environment before pushing.
+- **Match the house style.** Read the surrounding code first — this is a
+  stdlib-only, deterministic, read-only tool; keep it that way (no runtime
+  dependencies, no model calls).
+
+## Build and test
+
+This package is stdlib-only; the only extra is `test` (pytest):
+
+```sh
+pip install -e ".[test]"
+python -m pytest tests/ -q
+```
+
+Requires Python 3.10+. CI runs the suite across 3.10–3.14 and must be green
+before merge.
+
+## The Idea-Id commit-trailer convention
+
+This repo's own convention: a commit that lands an idea recorded in a fleet doc
+carries an `Idea-Id: <corpus>-<docslug>-<num>` git trailer (add
+`Idea-Status: partial` when a commit only partly lands it). It is the durable
+join key the reconciler reads. Emit it when a commit lands an idea. See
+[CONVENTION.md](CONVENTION.md) for the full rule and what counts as landing
+evidence.
+
+## Practical bits
+
+- PRs use the closeout template (Bite / What was done / Evidence /
+  Out of scope / Next bite).
+- Security findings go through [SECURITY.md](SECURITY.md), not issues.
+
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) and [SUPPORT.md](SUPPORT.md).

willow_reconciler-0.2.0/CONVENTION.md

@@ -0,0 +1,85 @@
+# The Idea-Id trailer convention
+
+Adopted 2026-09-11 (operator ruling: "adopt the trailers going forward").
+Recorded as governance decision `decision-2026-09-11-adopt-idea-id-trailers`;
+proposed to Nestor as draft `11a1744c-6b83-48f5-9fd8-d7a929b5eabf` (seal pending).
+
+## What
+
+A commit that lands an idea recorded in a fleet doc carries a git trailer:
+
+    Idea-Id: <corpus>-<docslug>-<num>
+
+matching the id this reconciler derives for that doc entry
+(e.g. `willow-ideas-042` for the 42nd entry of willow-mcp/docs/ideas.md).
+When a commit only partly lands an idea, add:
+
+    Idea-Status: partial
+
+The default (trailer present, no status) means landed.
+
+## Why it is prospective, not retroactive
+
+willow-reconciler Slice 0 measured, on a held-out split of the *current*
+corpus with tags stripped, a landing-recovery of **0.0**: no durable join
+key was ever written, so deterministic inference recovers nothing, and a
+model-based guess would violate the cheapest-capable rule. The ID's absence
+is itself why "format predicts landing." The fix cannot look backward — it
+starts writing the key now, and this reconciler grows useful as trailers
+accumulate.
+
+## Tooling (you should not be typing these by hand)
+
+    reconciler id --repo <repo> --doc <doc> --num 42      # print the trailer line
+    reconciler id --repo <repo> --doc <doc> --grep "text"  # ... or find it by text
+    reconciler install-hook --repo <repo>                  # write it automatically
+    reconciler verify --repo <repo> --doc <doc>            # check they all resolve
+
+`install-hook` adds a `prepare-commit-msg` hook that derives the trailer from
+a branch name that names an idea number (`idea-42`, `ideas-042`,
+`feature/idea_42-thing`), and a `commit-msg` hook that rejects a malformed
+`Idea-Id` or `Idea-Status` line. Neither hook can invent a link: the first
+fires only when the branch already carries the number, and it never overwrites
+a trailer written by hand.
+
+A commit may carry several `Idea-Id` trailers when it lands several ideas.
+`Idea-Status` is commit-level, so a commit saying `partial` says it about
+every id it names.
+
+## A wrong id is worse than no id
+
+An `Idea-Id` that resolves to nothing is not a harmless typo. Rule 2a asserts
+LANDED from a trailer ahead of every other inferred signal, and nothing else in
+the rule stack can distinguish a real join key from a plausible-looking dead
+one — so a dangling trailer is a silent, permanent, confident wrong answer.
+That is why the id shape is fixed (`willow-ideas-NNN`, three digits), why the
+commit-msg hook rejects anything else, and why `reconciler verify` runs in CI.
+
+## Nothing to backfill on the doc side
+
+The doc-side id is *derived* by `reconciler/ids.py` from the entry's position
+in the doc — it is not stored in the doc. So no edit to ideas.md is required.
+The only new discipline is on the commit side: emit the trailer when a commit
+lands an idea. This sits alongside the `Co-Authored-By` / `Claude-Session`
+trailers the harness already appends, so it is one more line.
+
+## What counts as landing evidence
+
+- The `Idea-Id` trailer on a commit **reachable from the checkout being
+  reconciled** (primary key). Evidence is scoped to `git log HEAD`, not
+  `git log --all`: a trailer on an abandoned or rejected branch is not a
+  landing, and reading it as one was a false LANDED sourced from the ref scope.
+- A commit body that says "PR #N" *and* git shows PR #N merged **as a real
+  merge commit** (two or more parents, with GitHub's own merge subject). A bare
+  `#N`, or an idea-number cross-reference like "former #103", is NOT a PR ref —
+  the reconciler rejects it (see tests/).
+
+Deliberately NOT evidence: a subject ending `(#N)`. That is GitHub's
+squash-merge title shape, but it is also the ordinary conventional-commit habit
+of naming an issue, and the two are indistinguishable from git alone — it
+asserted LANDED for unrelated commits. Repos that squash-merge should rely on
+the trailer, which is the durable key regardless of merge strategy.
+
+A legend tag in the doc is read as a tag only when it LEADS the item text or
+when its dash-introduced clause NAMES its legend keyword (`shipped` / `partial`).
+An ordinary sentence containing an em-dash and a marker is prose, not a tag.