agsync 0.1.0__tar.gz

agsync-0.1.0/.github/ISSUE_TEMPLATE/rule-proposal.md

@@ -0,0 +1,17 @@
+---
+name: Rule proposal
+about: Propose a new integrity check
+labels: rule
+---
+
+**What silently breaks today?**
+Describe the failure as it appeared in a real repo, not in the abstract.
+
+**Why can't a human catch it by reading?**
+The best rules catch things that look fine to a careful reader.
+
+**Minimal failing example**
+The smallest memory files that reproduce it.
+
+**Proposed severity**
+`error` (the memory is now wrong) or `warn` (the memory is fragile).

agsync-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: pytest -q
+
+  scaffold:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e .
+      # A rule that fires on a structure agsync generated itself is a false
+      # positive by definition, so `init` output must always lint clean. This
+      # repository does not carry its own ledger to check instead: that is
+      # generated output, not source.
+      - run: agsync init "$RUNNER_TEMP/scaffold"
+      - run: agsync check "$RUNNER_TEMP/scaffold" --format github

agsync-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,78 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # The tag names the release; pyproject names what actually gets uploaded.
+      # Nothing else ties them together, so a tag cut against the wrong commit
+      # publishes a version the tag does not describe — and PyPI never lets that
+      # version be replaced. Fails in seconds, in parallel with the suite.
+      - name: Tag must match the packaged version
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          packaged=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')
+          echo "tag=$TAG packaged=$packaged"
+          if [ "$TAG" != "$packaged" ] && [ "$TAG" != "v$packaged" ]; then
+            echo "::error::release tag $TAG does not match pyproject version $packaged"
+            exit 1
+          fi
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The ends of the supported range from pyproject's requires-python.
+        # A release that breaks on either end should never reach PyPI.
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: pytest -q
+
+  build:
+    needs: [test, version]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Trusted Publishing: PyPI mints a short-lived token from this job's OIDC
+    # identity, which is why no API token appears anywhere in this file. The
+    # identity PyPI checks is (repository, workflow filename, environment), so
+    # renaming this file or the environment breaks publishing until the
+    # trusted publisher on PyPI is updated to match.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

agsync-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+
+# This repository's own agent memory. It is `agsync init` output kept locally:
+# generated files do not belong in the repository that generates them. Paths are
+# root-anchored so the deliberately-broken fixtures under tests/ stay tracked.
+/AGENTS.md
+/.agsync.toml
+/memory/
+/tasks/

agsync-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,6 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+Report unacceptable behavior by opening a confidential issue or contacting the
+maintainer directly. Reports are handled privately.

agsync-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+```bash
+git clone https://github.com/gabrielft-me/agsync
+cd agsync
+pip install -e ".[dev]"
+pytest -q
+```
+
+No dependencies in the runtime package. Ever. This runs inside git hooks on
+other people's machines, and a virtualenv surprise there is a broken commit for
+someone who never asked for our opinions about packaging.
+
+## Before you start
+
+[docs/design.md](docs/design.md) explains why the architecture is the way it is
+— why the parser normalizes instead of demanding, why severity is configuration,
+why fingerprints hash structured fields, why replay clones instead of checking
+out, and why intent is never inferred from a diff. Worth reading if a change
+starts to feel like it is fighting the codebase.
+
+## Adding a rule
+
+A rule is one function. Start here — it's the easiest contribution and the most
+valuable one.
+
+1. Write it in `src/agsync/rules/` (decisions, tasks, or links):
+
+```python
+@rule("no-undated-decisions", ERROR, "One line: what silently breaks.")
+def no_undated_decisions(memory):
+    for decision in memory.decisions.values():
+        if "date" not in decision.fields:
+            yield Finding("no-undated-decisions", decision.path,
+                          decision.line, f"{decision.id} has no date")
+```
+
+2. Add the failing case to `tests/fixtures/decayed/` and a test asserting the
+   rule fires with a useful message.
+3. Add a row to the rules table in `README.md`.
+
+### What makes a good rule
+
+- **It catches something invisible to a careful reader.** A duplicate `D-021`
+  fifty lines apart is the archetype.
+- **It has zero false positives on a healthy repo.** Run it against
+  `agsync init` output; that must stay clean.
+- **The message says what broke and why it matters**, not just which check
+  failed. Compare: `"duplicate ID"` versus `"D-021 is redefined here (first
+  defined at line 7); 9 reference(s) are now ambiguous"`.
+- **Default to `warn` if it encodes a style opinion**, `error` only if the
+  memory is now factually wrong.
+
+## Parser changes
+
+The parser normalizes; it never demands. If a real repo uses a format we don't
+read, that's a parser bug, not a user error. Add the shape to
+`tests/fixtures/` and make the parser absorb it.
+
+Never make a rule reach into raw markdown. If a rule needs something the model
+doesn't carry, add the field to the model. The reasoning is in
+[docs/design.md](docs/design.md).
+
+## Style
+
+`ruff check src tests` must pass. Comments explain *why*, not *what* — the code
+already says what.

agsync-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Fagundes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agsync-0.1.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.5
+Name: agsync
+Version: 0.1.0
+Summary: ESLint for your agents' memory — catch decision-log rot before it reaches a new session.
+Project-URL: Homepage, https://github.com/gabrielft-me/agsync
+Project-URL: Issues, https://github.com/gabrielft-me/agsync/issues
+Author: Gabriel Fagundes
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents-md,ai-agents,decision-log,git-hooks,linter,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agsync
+
+**ESLint for your agents' memory — because the decision log your AI agents write is already lying to them.**
+
+[![CI](https://github.com/gabrielft-me/agsync/actions/workflows/ci.yml/badge.svg)](https://github.com/gabrielft-me/agsync/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agsync.svg)](https://pypi.org/project/agsync/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+```console
+$ agsync check
+AGENTS.md
+     6  error   protocol-files-exist  boot protocol requires 'memory/goal.md', which does not
+                                      exist — this step is unsatisfiable and every session skips it
+memory/decisions.md
+    11  error   unique-decision-ids   D-021 is redefined here (first defined at line 7);
+                                      7 reference(s) to D-021 are now ambiguous
+    88  error   relations-resolve     D-027 supersedes D-019, which is not defined
+tasks/25-search-indexing.md
+     3  warn    status-not-qualified  status is qualified with free text ('(all tiers except the
+                                      edge cache)'); keep the status machine-readable
+tasks/README.md
+     -  error   index-matches-files   task 26 exists (tasks/26-webhook-retries.md) but is absent
+                                      from the index — invisible to anyone reading it
+    14  error   index-matches-files   task 25: index says 'todo', file says 'done'
+
+27 decisions, 26 tasks, 25 index rows
+9 error(s), 4 warning(s)
+```
+
+---
+
+## The problem
+
+You gave your agents a memory. `AGENTS.md` with a boot protocol, a numbered
+decision log, a task queue. Every session starts by reading it. It is the only
+thing standing between a new agent and a cold start.
+
+**Nothing checks that it is true.**
+
+Markdown never fails. A decision ID reused for a second, unrelated decision. A
+boot step pointing at a file nobody ever wrote. A status of `done (stub)`. An
+index row that disagrees with the task file it names. Every one of these parses,
+renders, and reviews perfectly well, and every one is read as ground truth by the
+next agent that boots.
+
+Four things make the decay invisible, and they compound:
+
+- **The reference graph is prose.** `D-021` is a bare token, not a link. Nothing
+  resolves it, so nothing notices when a second entry claims the same ID and
+  every existing reference to it silently becomes ambiguous.
+- **Contradictions live in separate files.** The index says `todo`, the task file
+  says `done`. The protocol says "read this", and the file was never created. No
+  single diff contains both halves, so no review can catch it.
+- **Every writer has a partial view.** Each session is a different agent, and
+  each edit is locally reasonable. Rot is what locally reasonable edits add up to
+  when nothing holds the whole.
+- **A false memory looks exactly like a true one.** No crash, no red test. The
+  agent reads a confident, well-formatted, wrong statement and acts on it.
+
+The failure is not hypothetical and it is not slow. A repo written by several
+agents over a couple of days will already contain several of these.
+
+> A memory system whose integrity depends on being maintained by hand degrades
+> at exactly the speed you use it.
+
+The design is not the problem — `AGENTS.md` plus a decision log is the right
+shape. The problem is that nothing enforces it.
+
+## The fix is not a smarter agent
+
+Agents self-report badly. They tell you what they *intended* to do, not what
+they did, and every harness writes in a different dialect. "Be more careful" does
+not survive a new agent joining.
+
+`git push` is a choke point nobody can skip. Put the validation there.
+
+## Install
+
+```bash
+uvx agsync check          # try it, no install
+pipx install agsync       # keep it
+pip install agsync
+```
+
+Python 3.11+. **Zero dependencies** — the whole thing is stdlib, so it runs in a
+git hook without a virtualenv surprise.
+
+## Use
+
+```bash
+agsync check                    # lint the repo
+agsync check --warn-only        # first run: see everything, fail nothing
+agsync check --baseline         # accept today's mess, fail on new mess
+agsync check --no-baseline      # what an agent runs at boot: everything, unsuppressed
+agsync check --format github    # inline annotations on the PR diff
+agsync check --format json      # for your own tooling
+agsync replay <repo>            # how many past pushes the gate would have stopped
+agsync rules                    # what it checks and why
+agsync init                     # scaffold a memory structure from scratch
+agsync install-hooks            # gate commits locally
+```
+
+### Adopting an existing repo
+
+Do not turn everything on at once — a linter that rejects most of your pushes on
+day one gets uninstalled on day one.
+
+```bash
+agsync check --warn-only    # 1. look at the damage
+agsync check --baseline     # 2. freeze it; new violations now fail
+```
+
+The baseline records a fingerprint per violation that survives line shifts, so
+unrelated edits above a known problem don't resurrect it as "new". Delete
+entries from `.agsync-baseline.json` as you fix them.
+
+**The baseline governs the gate, and never the reader.** It records what should
+stop a push — a decision about your rollout, not a statement about what is true.
+An agent about to act on this memory needs the whole picture, including the parts
+you chose not to block, so the boot protocol runs:
+
+```bash
+agsync check --no-baseline
+```
+
+Suppressing a finding is how you keep working. Believing it was suppressed
+because it was fixed is how a new session acts on something false.
+
+### Replay: how bad is it already?
+
+`agsync replay` runs the same check engine at every commit in a repository's
+history and counts the pushes the gate would have stopped. Point it at a repo
+that has been running on hand-maintained memory for a while, and it will tell you
+when each violation started and how long it has been sitting there.
+
+```console
+$ agsync replay . --ref main --first-seen
+sha      date        errors  rules
+3ad9e51  2026-03-02       0  —
+...
+b7e2d13  2026-03-14       4  index-matches-files, links-resolve, unique-decision-ids
+
+18 of 42 pushes would have been rejected
+
+rule                  first failed         survived
+protocol-files-exist  9f1c0a4 2026-03-04   31 commits, 9 days (still failing at HEAD)
+unique-decision-ids   c40b8f2 2026-03-09   14 commits, 4 days (still failing at HEAD)
+index-matches-files   c40b8f2 2026-03-09   14 commits, 4 days (still failing at HEAD)
+```
+
+The second table is the uncomfortable one. A broken boot step usually dates from
+the commit that introduced the protocol and is usually still broken at HEAD,
+because nothing has ever checked it.
+
+Replay clones the target to a temp directory and moves HEAD only inside that
+clone, so it cannot leave your repository detached at an old commit. It takes a
+path or a clone URL, exits 0 unless the run itself fails — it reports on history,
+it does not gate it — and ignores any baseline, because the question is what the
+rules would have caught, not what someone had already told the gate to overlook.
+
+One caveat worth stating out loud: replay judges old commits by today's rules.
+The claim is "these would be rejected now", not "these were rejected then".
+
+## Rules
+
+| Rule | Default | Catches |
+|---|---|---|
+| `unique-decision-ids` | error | Two ledger entries sharing an ID, making every reference ambiguous |
+| `decision-refs-resolve` | error | A `D-xxx` cited anywhere that the ledger never defines |
+| `relations-resolve` | error | `(supersedes D-019)` where `D-019` doesn't exist |
+| `no-self-reference` | error | A decision superseding itself |
+| `decision-has-date` | error | An entry with no date, so the ledger can't be ordered |
+| `protocol-files-exist` | error | A boot instruction pointing at a file that isn't there |
+| `links-resolve` | error | Any relative markdown link with no target |
+| `status-in-enum` | error | A status outside `todo/in-progress/done/superseded` |
+| `status-not-qualified` | warn | `done (stub)` — not machine-readable |
+| `index-matches-files` | error | Index and task files disagreeing, or a task missing entirely |
+| `task-refs-resolve` | error | A dependency on a task that doesn't exist |
+| `no-dependency-cycles` | error | Tasks that can never be executed in any order |
+| `blocked-task-not-done` | warn | A task marked done while its dependency is still open |
+| `no-orphan-memory-files` | warn | A memory file nothing references, so no agent reads it |
+
+## Configuration
+
+`.agsync.toml`. Severity is configuration; rule logic is not.
+
+```toml
+exclude = ["archive/"]
+
+[rules]
+status-not-qualified = "warn"
+decision-has-date = "off"
+```
+
+Also readable from `[tool.agsync]` in `pyproject.toml`.
+
+## CI
+
+```yaml
+- uses: gabrielft-me/agsync@v1
+```
+
+Or directly:
+
+```yaml
+- run: pipx install agsync && agsync check --format github
+```
+
+Findings render inline on the pull request diff. Pair it with branch protection
+and the memory can't rot through a merge.
+
+## How it works
+
+**Normalize, don't demand.** Real memory repos are written by several agents over
+weeks and the format drifts: field sets vary between entries, values wrap across
+lines, index tables use different column orders in the same file. The parser
+absorbs all of it into a graph. Rules only ever see the graph.
+
+**Rules are tiny and isolated.** Each is a function taking the parsed memory and
+yielding findings. No shared state, no ordering, no knowledge of each other.
+
+```python
+from agsync.rules import rule
+from agsync.model import ERROR, Finding
+
+@rule("no-undated-tasks", ERROR, "A task file carries no date.")
+def no_undated_tasks(memory):
+    for task in memory.tasks.values():
+        if "date" not in task.status_raw:
+            yield Finding("no-undated-tasks", task.path, 1, "no date")
+```
+
+**One report contract.** Every finding is `{rule, path, line, message, severity}`.
+Text output, JSON, and GitHub annotations all derive from it, so a new output
+format never touches a rule.
+
+## Roadmap
+
+- [x] Linter, config, baseline, JSON/GitHub output
+- [x] `init` scaffold, local hooks with chaining
+- [x] `replay`: measure the decay across a repository's whole history
+- [ ] `--fix`: regenerate the task index; interactive ID renumbering
+- [ ] YAML front matter schema — make the D-ID ↔ task graph structured instead of prose
+- [ ] Harness adapters (Claude Code, Cursor) writing commit trailers at commit time
+- [ ] `agsync draft`: turn captured trailers into a ledger entry, BYO key, opened as a PR
+- [ ] Single static binary
+
+### What this will never be
+
+**An intent-inference engine.** A `post-receive` hook fires *after* the push —
+the agent's turn is over and its context is gone. All the server sees is a diff
+and a message, strictly less than the agent had. The reason a project pivoted
+from one approach to another is not in the diff and no model recovers it from
+there.
+
+So: **capture at commit time, enforce at push time.** When the ledger entry
+lands, the model formats a *why* that a human or agent already stated. It never
+invents one. If nobody supplied a reason, the right outcome is a rejected push —
+not a plausible-looking fabrication. A ledger that looks trustworthy and isn't is
+worse than no ledger.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). New rules are welcome and are the easiest
+place to start — one function, one test, one row in the table above.
+
+## License
+
+MIT.