kbforge 0.2.0__tar.gz → 0.4.0__tar.gz

{kbforge-0.2.0 → kbforge-0.4.0}/.github/workflows/ci.yml

@@ -84,4 +84,4 @@ jobs:
           enable-cache: true
       - run: uv python install 3.13
       - run: uv build --no-sources
-      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+      - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1

{kbforge-0.2.0 → kbforge-0.4.0}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.21
+    rev: v0.15.22
     hooks:
       - id: ruff-check
         args: [--fix]
@@ -10,6 +10,6 @@ repos:
   # `uv check` under the hood, so kbforge's own dependencies resolve for ty --
   # a local `entry: ty check` hook cannot see them.
   - repo: https://github.com/astral-sh/ty-pre-commit
-    rev: v0.0.59
+    rev: v0.0.61
     hooks:
       - id: ty

kbforge-0.4.0/CHANGELOG.md

@@ -0,0 +1,173 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-07-25
+
+### Added
+
+- **Deletion propagation.** A concept removed at the source — via an explicit
+  tombstone (`CanonicalDocument.deleted=True`); absence is never inferred as
+  deletion — is now actually deleted from the target repo, not just described.
+  `ProposedChange.files_removed` carries the removal list, assigned by the
+  pipeline after synthesis so an LLM synthesizer cannot delete a file it
+  dislikes. Concepts still linking to a deleted one are pulled into scope and
+  re-synthesized so their now-dangling links are dropped. Both forge adapters
+  intersect removals with what is actually on the base tree first, since
+  GitLab (400) and GitHub (422) both reject deleting an absent path.
+
+### Fixed
+
+- **Data loss when a review request was left open across runs.** `publish_to_forge`
+  reset the sync branch to the default branch on every run; since the mirror
+  advances after each successful publish, a run publishing while a previous
+  review request was still open silently rebuilt the branch and lost everything
+  the earlier run had put there. The base now resolves to the sync branch
+  itself when a request is open, so runs accumulate into one review request;
+  when none is open the branch still rebuilds from the default branch, so a
+  merged or abandoned request leaves no stale branch behind.
+
+  Note the branch self-heals but the *content* does not, and never did: the
+  mirror advances on every successful publish, so a request closed without
+  merging discards its contents permanently — those concepts are never
+  re-proposed, and a published-then-abandoned deletion is not even seen as a
+  removal by a later run. Abandon a review request by merging it, or by
+  resetting **both** the mirror and the connector's cursor
+  (`<state-dir>/cursor-<connector-name>.json`) — deleting the mirror alone
+  does nothing for an incremental connector, whose surviving cursor still
+  bounds the next fetch to records past it, so few or none come back and
+  nothing is re-proposed.
+
+- **Links to still-published concepts were stripped on an incremental fetch.**
+  The set of resolvable link targets handed to synthesis was built from the
+  current fetch alone. An incremental connector's fetch need not contain a
+  concept that still exists, so a run carrying only a tombstone re-rendered the
+  referrer with *every* link removed — including links to concepts that were
+  still live and still published. §4.4 law 2 only fails on links that do not
+  resolve, never on links that went missing, so it shipped silently. That set is
+  now built from the mirror (the published state) unioned with the fetch, minus
+  the run's own tombstones.
+
+- **A fully-filtered removal set produced a degenerate commit payload.** With no
+  files and every removal already absent from base, the adapters posted
+  `actions: []` (GitLab) or `tree: []` (GitHub). Both forges reject it — GitLab
+  400 "Provide at least one action, or set allow_empty to true", GitHub 422
+  "Invalid tree info" — so every later run failed identically until the source
+  changed. Nothing is now committed when the branch already is base; when the
+  commit is also what creates the branch, GitLab sends `allow_empty` and GitHub
+  commits base's own tree.
+
+  On that create-branch path, the empty commit still opens (or updates) a
+  review request, so the rare case where every removal is already gone from
+  base is now visible rather than a hard failure: expect a request whose diff
+  is empty, whose body can still describe a removal that was, in fact, already
+  applied to the target (typically because an earlier run committed it but
+  died before the mirror advanced). That is strictly better than the prior
+  400/422 — closing or merging it is a no-op — but it is surprising enough to
+  flag if you see it.
+
+- The dry-run publisher applies `safe_join` to the paths it writes *and* the
+  paths it deletes, so a connector-supplied `native_id` of `../../../etc/foo`
+  can no longer reach outside the output directory. The forge publishers
+  already guarded this.
+
+## [0.3.0] - 2026-07-25
+
+### Added
+
+- `examples/github-issues-connector/` — a complete worked example of a credentialed
+  connector (GitHub issues → OKF concepts) with token auth, pagination, and a real
+  incremental cursor, plus a walkthrough README for writing your own connector.
+- GitHub (`--publisher github`) and GitLab (`--publisher gitlab`) publishers that
+  open or update a real pull/merge request from a `ProposedChange`. No new
+  runtime dependencies — both run on stdlib `urllib`. Tokens are read from
+  `GITHUB_TOKEN` / `GITLAB_TOKEN` (configurable via `token_env`), never the CLI.
+  Both send `Authorization: Bearer`, so either forge accepts a personal,
+  project or group access token as well as an OAuth token from `gh`/`glab`.
+- `tests/test_forge_live.py` — an opt-in (`--run-live`) suite that publishes to
+  real GitHub and GitLab scratch repos and reads the result back through `gh`
+  and `glab`, so no assertion depends on the code that wrote the state. Covers
+  the sequence offline tests structurally cannot: publish, republish, human
+  merge, publish again.
+- `--publisher NAME` and `--publish-set KEY=VALUE` CLI flags; `kbforge list` now
+  lists publishers.
+- `kbforge_validate_publish_config` hookspec so publisher config is checked
+  before the pipeline runs.
+
+### Changed
+
+- Publishers are now resolved by name. Previously the first registered plugin
+  implementing `kbforge_publish` won, which became order-dependent with more
+  than one publisher installed.
+- The core design stance is now "zero credentialed *connectors*" — publishing is
+  delivery, not a system-of-record integration.
+
+### Fixed
+
+- `kbforge.__version__` reported `0.1.0` for the whole of the 0.2.0 release. It
+  is now derived from installed package metadata, so `pyproject.toml` is the
+  single source of truth and the two cannot drift again.
+
+## [0.2.0] - 2026-07-19
+
+### Added
+
+- Grounded **LLM synthesizer** — `--synthesizer llm`, behind the optional
+  `kbforge[llm]` extra. The model writes only concept prose (title, description,
+  body) inside a kbforge-owned structural frame: anchors, links, facets, type, and
+  timestamp are assembled deterministically, so the §4.4 validators gate structure
+  the model cannot influence. Reached through Pydantic AI's LiteLLM provider, so
+  OpenRouter and a self-hosted LiteLLM gateway share one config path, and the API
+  key comes only from an environment variable. The deterministic stub remains the
+  default; synthesizer selection is a generic `Synthesizer` seam injected into the
+  pipeline.
+
+## [0.1.0] - 2026-07-19
+
+First release: a deterministic, credential-free walking skeleton of the kbforge
+production protocol.
+
+### Added
+
+- **Fixed pipeline** — `fetch → normalize → mirror → diff → scope → synthesize →
+  validate → publish`, run once by `kbforge run`. The order is not pluggable, and
+  neither are the two trust guarantees enforced in it: the **no-op rule** (a sync
+  that finds no change opens no merge request) and the **never-auto-merge rule**
+  (a publisher proposes; it never merges).
+- **Canonicalization** with the §4.3 stability law — `normalize` is deterministic,
+  clock-free, and volatile-free, so identical input always yields identical content
+  hashes. A byte-different but content-identical re-save (CRLF flips, a BOM, a
+  re-export) is not a change.
+- **Replay-safe mirror and read-only diff** — change is detected against a
+  core-owned mirror; the mirror advances only after a run fully succeeds. Absence
+  never implies a deletion.
+- **Two built-in connectors**, both credential-free:
+  - `local_files` — a folder of markdown-with-frontmatter, with an additive
+    `ignore_globs` config and always-on defaults (`.venv`, `.git`, `node_modules`,
+    tool caches) so pointing at a repository root does not sweep in dependencies.
+  - `git_commits` — one concept per commit, with genuine incremental sync: the
+    cursor is the last-synced SHA, so a re-run fetches only `<last>..<ref>`.
+- **§4.4 agent-facing artifact laws**, enforced as core validators at the `validate`
+  stage: facet well-formedness, link resolvability, anchor presence, and freshness
+  legibility, plus a projection↔files coherence check. Nothing non-conformant ships.
+- **Stub synthesizer** — deterministic, no LLM; reshapes canonical documents into
+  OKF concepts and gives the validators real structure to check.
+- **Dry-run publisher** — writes the proposed bundle to a local directory under a
+  source-named branch; never merges; idempotent.
+- **Plugin system** on Pluggy with entry-point discovery: any installed package
+  advertising the `kbforge.connectors` or `kbforge.publishers` entry-point group is
+  discovered without editing kbforge.
+- **CLI** — `kbforge list` shows available connectors; `kbforge run --connector NAME
+  --set KEY=VALUE ...` resolves the connector from the registry and takes YAML-typed
+  config, with no per-connector knowledge in the CLI.
+
+[Unreleased]: https://github.com/flyersworder/kbforge/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/flyersworder/kbforge/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/flyersworder/kbforge/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/flyersworder/kbforge/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/flyersworder/kbforge/releases/tag/v0.1.0

{kbforge-0.2.0 → kbforge-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kbforge
-Version: 0.2.0
+Version: 0.4.0
 Summary: Agent-first knowledge bases, forged from your systems of record
 Project-URL: Homepage, https://github.com/flyersworder/kbforge
 Project-URL: Repository, https://github.com/flyersworder/kbforge
@@ -72,12 +72,13 @@ and the [artifact-contract spec](docs/design/2026-07-18-agent-facing-artifact-co
 **Alpha — a working walking skeleton.** The deterministic core runs end to end with no
 credentials: two built-in connectors (`local_files`, `git_commits`), canonicalization
 with a stability law, a replay-safe mirror and diff, the §4.4 validator gate, and a
-dry-run publisher — change detection, the no-op rule, and incremental sync via a real
-cursor all exercised by the test suite. Synthesis ships in two forms: a deterministic
-stub (the default, no LLM) and an opt-in grounded LLM synthesizer (`--synthesizer llm`,
-via the `kbforge[llm]` extra).
+dry-run publisher, plus change detection, the no-op rule, and incremental sync via a
+real cursor, all exercised by the test suite. Two credentialed publishers, GitHub and
+GitLab, are also available (opt-in via `--publisher`, token from an env var). Synthesis ships in
+two forms: a deterministic stub (the default, no LLM) and an opt-in grounded LLM
+synthesizer (`--synthesizer llm`, via the `kbforge[llm]` extra).
 
-Not built yet: a credentialed system-of-record connector, and a GitHub-PR publisher. See
+Not built yet: a credentialed system-of-record connector. See
 [`docs/architecture.md`](docs/architecture.md) for the full map.
 
 ## Quickstart
@@ -112,6 +113,51 @@ kbforge run --connector local_files --set path=./docs \
 The synthesizer reaches models through a LiteLLM provider, so OpenRouter and a
 self-hosted LiteLLM gateway share one config path.
 
+## Publishing to GitHub or GitLab
+
+The default publisher writes the proposal to a local directory. To open a real
+pull request or merge request instead, select a forge publisher and give it a
+repo. The token comes from an env var, never the CLI:
+
+```bash
+export GITHUB_TOKEN=...            # or GITLAB_TOKEN
+kbforge run --connector local_files --set path=./docs \
+  --publisher github --publish-set repo=acme/knowledge-base \
+  --mirror .kbforge/mirror --out .kbforge/out --state .kbforge/state
+```
+
+Both publishers accept the same config: `repo` (required), `base` (default: the
+repo's default branch), `base_path` (a subdirectory, default: repo root),
+`branch` (default: `sync/<system>`), `title`, `api_base` (point it at GitHub
+Enterprise or a self-managed GitLab), and `token_env`.
+
+kbforge maintains **one long-lived sync branch and one open review request** per
+source system: a later run force-updates that branch and edits the existing
+PR/MR rather than opening a second one. Three consequences worth knowing:
+
+- Concepts deleted from the source are deleted from the target repo, provided the
+  connector emits an explicit tombstone. Absence never implies a deletion.
+- Manual commits on the sync branch are preserved **while its review request is
+  open** — a later run builds on the branch rather than resetting it. Once no
+  request is open, the next run rebuilds the branch from the default branch and
+  those commits are gone. A hand edit to a concept kbforge later regenerates is
+  overwritten by that regeneration either way.
+- **Close a kbforge review request only by merging it.** The mirror advances on
+  every successful publish, so the concepts a request carries are never
+  re-proposed. Closing one unmerged discards its contents permanently: the
+  target repo simply never gets them, and a published-then-abandoned deletion
+  leaves the doc gone from the mirror, so no later run even sees it as a
+  removal. To undo an abandoned request, reset **both** the mirror and the
+  connector's cursor: delete the mirror directory and, in the state directory
+  (`--state`), the connector's `cursor-<connector-name>.json`. Deleting the
+  mirror alone does not work for an incremental connector — its cursor still
+  points past the abandoned content, so the next `kbforge_fetch` returns only
+  what changed since then, which can be little or nothing, and no re-proposal
+  happens at all. Only once both are gone does a re-run re-propose everything
+  from scratch.
+
+kbforge never merges. No publisher has a merge method.
+
 ## Design stance
 
 The core ships **zero credentialed connectors and zero CI logic.** The two built-in
@@ -126,6 +172,10 @@ repositories. The interface is the product.
 myservice = "my_package:connector"
 ```
 
+A complete worked example — a credentialed GitHub Issues connector (~160 lines) with
+token auth, pagination, and a real incremental cursor — is in
+[`examples/github-issues-connector/`](examples/github-issues-connector/).
+
 The pipeline order — fetch → normalize → mirror → diff → scope → synthesize → validate →
 publish — is deliberately **not** pluggable, and neither are the no-op rule or the
 never-auto-merge rule. Those are the trust guarantees; making them pluggable would make
@@ -166,6 +216,23 @@ prek install                 # ruff + ty on every commit
 uv run pytest
 ```
 
+The default suite never touches the network. Tests that call a real external
+service are marked `live` and skipped unless you pass `--run-live`.
+
+The forge publishers have a live suite because their offline tests can only
+assert what we *meant* to send — a real forge is the only thing that can say
+the intent was right. It needs a throwaway repo on each forge and the two CLIs
+(`gh`, `glab`) authenticated; each run writes under a fresh `live/<run-id>/`
+prefix, so nothing accumulates and no repo is ever deleted.
+
+```bash
+GITHUB_TOKEN=$(gh auth token) \
+GITLAB_TOKEN=$(glab config get token --host gitlab.com) \
+KBFORGE_LIVE_GITHUB_REPO=you/kbforge-live-test \
+KBFORGE_LIVE_GITLAB_REPO=you/kbforge-live-test \
+uv run pytest tests/test_forge_live.py --run-live
+```
+
 ## License
 
 MIT

{kbforge-0.2.0 → kbforge-0.4.0}/README.md

@@ -37,12 +37,13 @@ and the [artifact-contract spec](docs/design/2026-07-18-agent-facing-artifact-co
 **Alpha — a working walking skeleton.** The deterministic core runs end to end with no
 credentials: two built-in connectors (`local_files`, `git_commits`), canonicalization
 with a stability law, a replay-safe mirror and diff, the §4.4 validator gate, and a
-dry-run publisher — change detection, the no-op rule, and incremental sync via a real
-cursor all exercised by the test suite. Synthesis ships in two forms: a deterministic
-stub (the default, no LLM) and an opt-in grounded LLM synthesizer (`--synthesizer llm`,
-via the `kbforge[llm]` extra).
+dry-run publisher, plus change detection, the no-op rule, and incremental sync via a
+real cursor, all exercised by the test suite. Two credentialed publishers, GitHub and
+GitLab, are also available (opt-in via `--publisher`, token from an env var). Synthesis ships in
+two forms: a deterministic stub (the default, no LLM) and an opt-in grounded LLM
+synthesizer (`--synthesizer llm`, via the `kbforge[llm]` extra).
 
-Not built yet: a credentialed system-of-record connector, and a GitHub-PR publisher. See
+Not built yet: a credentialed system-of-record connector. See
 [`docs/architecture.md`](docs/architecture.md) for the full map.
 
 ## Quickstart
@@ -77,6 +78,51 @@ kbforge run --connector local_files --set path=./docs \
 The synthesizer reaches models through a LiteLLM provider, so OpenRouter and a
 self-hosted LiteLLM gateway share one config path.
 
+## Publishing to GitHub or GitLab
+
+The default publisher writes the proposal to a local directory. To open a real
+pull request or merge request instead, select a forge publisher and give it a
+repo. The token comes from an env var, never the CLI:
+
+```bash
+export GITHUB_TOKEN=...            # or GITLAB_TOKEN
+kbforge run --connector local_files --set path=./docs \
+  --publisher github --publish-set repo=acme/knowledge-base \
+  --mirror .kbforge/mirror --out .kbforge/out --state .kbforge/state
+```
+
+Both publishers accept the same config: `repo` (required), `base` (default: the
+repo's default branch), `base_path` (a subdirectory, default: repo root),
+`branch` (default: `sync/<system>`), `title`, `api_base` (point it at GitHub
+Enterprise or a self-managed GitLab), and `token_env`.
+
+kbforge maintains **one long-lived sync branch and one open review request** per
+source system: a later run force-updates that branch and edits the existing
+PR/MR rather than opening a second one. Three consequences worth knowing:
+
+- Concepts deleted from the source are deleted from the target repo, provided the
+  connector emits an explicit tombstone. Absence never implies a deletion.
+- Manual commits on the sync branch are preserved **while its review request is
+  open** — a later run builds on the branch rather than resetting it. Once no
+  request is open, the next run rebuilds the branch from the default branch and
+  those commits are gone. A hand edit to a concept kbforge later regenerates is
+  overwritten by that regeneration either way.
+- **Close a kbforge review request only by merging it.** The mirror advances on
+  every successful publish, so the concepts a request carries are never
+  re-proposed. Closing one unmerged discards its contents permanently: the
+  target repo simply never gets them, and a published-then-abandoned deletion
+  leaves the doc gone from the mirror, so no later run even sees it as a
+  removal. To undo an abandoned request, reset **both** the mirror and the
+  connector's cursor: delete the mirror directory and, in the state directory
+  (`--state`), the connector's `cursor-<connector-name>.json`. Deleting the
+  mirror alone does not work for an incremental connector — its cursor still
+  points past the abandoned content, so the next `kbforge_fetch` returns only
+  what changed since then, which can be little or nothing, and no re-proposal
+  happens at all. Only once both are gone does a re-run re-propose everything
+  from scratch.
+
+kbforge never merges. No publisher has a merge method.
+
 ## Design stance
 
 The core ships **zero credentialed connectors and zero CI logic.** The two built-in
@@ -91,6 +137,10 @@ repositories. The interface is the product.
 myservice = "my_package:connector"
 ```
 
+A complete worked example — a credentialed GitHub Issues connector (~160 lines) with
+token auth, pagination, and a real incremental cursor — is in
+[`examples/github-issues-connector/`](examples/github-issues-connector/).
+
 The pipeline order — fetch → normalize → mirror → diff → scope → synthesize → validate →
 publish — is deliberately **not** pluggable, and neither are the no-op rule or the
 never-auto-merge rule. Those are the trust guarantees; making them pluggable would make
@@ -131,6 +181,23 @@ prek install                 # ruff + ty on every commit
 uv run pytest
 ```
 
+The default suite never touches the network. Tests that call a real external
+service are marked `live` and skipped unless you pass `--run-live`.
+
+The forge publishers have a live suite because their offline tests can only
+assert what we *meant* to send — a real forge is the only thing that can say
+the intent was right. It needs a throwaway repo on each forge and the two CLIs
+(`gh`, `glab`) authenticated; each run writes under a fresh `live/<run-id>/`
+prefix, so nothing accumulates and no repo is ever deleted.
+
+```bash
+GITHUB_TOKEN=$(gh auth token) \
+GITLAB_TOKEN=$(glab config get token --host gitlab.com) \
+KBFORGE_LIVE_GITHUB_REPO=you/kbforge-live-test \
+KBFORGE_LIVE_GITLAB_REPO=you/kbforge-live-test \
+uv run pytest tests/test_forge_live.py --run-live
+```
+
 ## License
 
 MIT

{kbforge-0.2.0 → kbforge-0.4.0}/docs/architecture.md

@@ -27,9 +27,12 @@ This library is the reference implementation of that missing half:
 | **Production protocol** (connectors, canonicalization, diff, provenance, publish) | **this library** | this spec |
 | Serving protocol | MCP | exists |
 
-Design stance carried over from the main doc: **the core ships zero connectors,
-zero credentials, zero CI logic.** Connectors are plugins; deployments are separate
-repos. The interface is the product.
+Design stance carried over from the main doc: **the core ships zero credentialed
+connectors, zero CI logic.** Connectors are plugins; deployments are separate
+repos. The interface is the product. Publishers are the exception that proves
+it: publishing is the producer's own delivery mechanism, not an integration with
+someone's system of record, so `github` and `gitlab` ship in core — reading their
+credentials from the environment, never from config.
 
 ---
 
@@ -75,8 +78,8 @@ remove them. (This is the same posture as ADR-2 in the main doc.)
 
 1. **Connectors** (`ConnectorSpec`, §5.1) — bring data *in* from a system of record.
    Fully specified in this sketch; this is what we build first.
-2. **Publishers** (`PublisherSpec`, §5.2) — push proposals *out* (GitLab MR, GitHub PR,
-   local dry-run). Thin; sketched here because the pilot needs exactly one (GitLab).
+2. **Publishers** (`PublisherSpec`, §5.2) — push proposals *out*. Three ship in core:
+   `dry-run` (local), `github` (PR), `gitlab` (MR).
 
 Synthesis (the LLM step) and validation are **core stages with narrow extension
 hooks** (§5.3), not open plugin families — they carry the grounding contract and the
@@ -398,7 +401,7 @@ class ConnectorSpec:
 
 ```python
 class PublisherSpec:
-    """Where proposals go. Pilot ships gitlab-mr; dry-run ships in core."""
+    """Where proposals go. MUST NOT merge (§5.2)."""
 
     @hookspec
     def kbforge_publisher_info(self) -> ConnectorInfo: ...
@@ -410,6 +413,61 @@ class PublisherSpec:
         re-running a failed pipeline updates the same MR, never opens twins."""
 ```
 
+Three publishers ship in core: `dry-run` (default; writes to a directory),
+`github` (pull requests) and `gitlab` (merge requests). All three implement
+`kbforge_publish` and `kbforge_validate_publish_config`; none implements a merge
+method, which is how §5.2's never-merge rule is enforced structurally rather
+than by convention.
+
+The two forge publishers sit behind a `ForgeClient` protocol whose methods name
+intentions (`put_files`, `find_open_pr`) rather than REST endpoints, because the
+forges decompose "commit these files" incompatibly — GitLab in one call, GitHub
+in four. They are unconditional rather than gated behind an extra: both run on
+stdlib `urllib`, so there is no dependency for an extra to install. Deliberately
+absent, so their absence reads as a decision rather than an omission: labels,
+reviewers and draft PRs; pagination in `find_open_pr` (a branch has at most one
+open PR); rate-limit backoff (a run makes fewer than ten calls); and auto-merge,
+which is excluded permanently rather than deferred.
+
+Their offline tests inject a fake transport, which pins the request we intended
+to make but cannot judge whether the intent was right — a real forge caught two
+defects the offline suite structurally could not see. Hence `tests/test_forge_live.py`
+(`--run-live`), which asserts through `gh`/`glab` rather than through kbforge's
+own readers.
+
+While a review request is open, a run sets the sync branch from the branch
+itself rather than from the default branch, so successive runs accumulate into
+one review request. When none is open the branch is rebuilt from the default
+branch, so a merged or abandoned request leaves no stale *branch* behind.
+
+That is a property of the branch only, and emphatically not of the content.
+The mirror advances after every successful publish, so a concept carried by a
+request that is closed without merging is never re-proposed: the target repo
+lacks it permanently. The same holds in reverse for a deletion — once published,
+the doc is gone from the mirror, so a later tombstone is not even a removal.
+Closing a kbforge review request without merging therefore discards its contents
+for good. Abandon a request by merging it, or by resetting **both** the mirror
+and the connector's cursor (`_load_cursor`/`_save_cursor` in `pipeline.py` keep
+it in the state directory, at `<state-dir>/cursor-<connector-name>.json`,
+separate from the mirror). Deleting the mirror alone is not enough for an
+incremental connector: the surviving cursor still bounds `kbforge_fetch` to
+records past it, so the next run can fetch few or no records, `ChangeSet.is_noop`
+fires, and nothing is re-proposed. Only deleting both re-proposes everything
+from scratch.
+
+Deletions travel
+as `ProposedChange.files_removed`, assigned by the pipeline rather than by a
+synthesizer: deletion is structure, not prose, so a model cannot delete a
+concept it dislikes.
+
+Declined as scope, deliberately rather than by omission: rebasing the sync
+branch when the default branch moves under an open review request (the branch
+may go stale; the forge's own merge handles it, and conflicts are unlikely
+because only kbforge writes concept files); inferring a deletion from a
+document's absence (tombstones stay explicit — see §4.2); and flagging
+non-kbforge commits pushed onto the sync branch in the review body (the README
+documents the sharp edge instead).
+
 ### 5.3 Core-stage extension hooks (narrow, additive-only)
 
 ```python

kbforge-0.4.0/examples/README.md

@@ -0,0 +1,10 @@
+# Examples
+
+Worked examples of extending kbforge. Each is a self-contained package that installs
+alongside kbforge and is discovered through an entry point — no changes to kbforge
+core.
+
+- [**github-issues-connector**](github-issues-connector/) — a complete credentialed
+  connector (~160 lines) that syncs a repository's GitHub issues into OKF concepts,
+  with token auth, pagination, and a real incremental cursor. The template for
+  writing your own connector.

kbforge-0.4.0/examples/github-issues-connector/README.md

@@ -0,0 +1,119 @@
+# Example: a GitHub Issues connector
+
+A complete, credentialed kbforge connector in ~160 lines — the worked example for
+writing your own. It syncs a repository's issues into OKF concepts, and it lives in
+its **own package**, discovered by kbforge purely through an entry point. Nothing in
+kbforge core changes.
+
+This is the shape every connector follows. Copy it, rename it, swap the `fetch`
+body for your system of record.
+
+## How kbforge finds it
+
+A connector is any object that implements the connector hooks, advertised under the
+`kbforge.connectors` entry-point group in your package's `pyproject.toml`:
+
+```toml
+[project.entry-points."kbforge.connectors"]
+github_issues = "kbforge_github_issues:connector"
+```
+
+Once your package is installed alongside kbforge, `kbforge list` shows it and
+`kbforge run --connector github_issues …` uses it. No fork, no registration call.
+
+## The four hooks (the whole contract)
+
+| hook | job |
+|---|---|
+| `kbforge_connector_info` | static self-description (name, version, source) |
+| `kbforge_validate_config` | return a list of problems (`[]` = ok); **no I/O** |
+| `kbforge_fetch(config, cursor)` | pull raw records; `cursor=None` = full backfill |
+| `kbforge_normalize(records)` | raw records → `CanonicalDocument`s; **pure & clock-free** |
+
+That's it. Everything downstream — canonicalization, the replay-safe mirror, diff,
+the no-op rule, incremental scoping, synthesis (stub or LLM), the §4.4 validators,
+and publish — you get for free. A connector only teaches kbforge how to *read* your
+source.
+
+## What this connector shows
+
+**`fetch` — the real-world work.** It reads a token from the `GITHUB_TOKEN`
+environment variable (never from config; the variable name is overridable with
+`--set token_env=MY_TOKEN` — the value still comes only from the environment), pages
+through the REST API, filters out
+pull requests (GitHub's issues endpoint returns them too), and returns each issue as
+a `RawRecord` carrying the issue JSON plus an `anchor_hint` (stable id, URL,
+timestamp). The **cursor** is the maximum `updated_at` seen, so the next run passes
+`since=<watermark>` and fetches only issues changed since — real incremental sync,
+just like the built-in `git_commits` connector.
+
+**`normalize` — deterministic by law.** It is a *pure* parse of the stored JSON into
+a `CanonicalDocument`: no network, no clock (the timestamp came from `fetch`). kbforge
+enforces this — `assert_stability` normalizes twice and rejects a connector whose
+output isn't identical. One design choice worth copying: `updated_at` and the comment
+count are deliberately kept **out** of the concept, so a comment-only edit produces an
+identical concept and stays a no-op, while a real body/label/state change is detected.
+
+**The rules a connector must respect:**
+- **Deterministic, clock-free `normalize`** (the §4.3 stability law).
+- **Retriever, not extractor** — return the source content verbatim with anchors;
+  interpretation is the synthesizer's job, not the connector's.
+- **Credentials only from the environment**, never from config values.
+- **Stable document identity** — a `doc_id` that survives across syncs, so change
+  detection works (here: `github_issues:owner/repo/issues/<number>`).
+
+## Run it
+
+```bash
+# from this directory
+uv sync --extra dev
+uv run pytest                      # 8 offline tests (deterministic, no network)
+
+export GITHUB_TOKEN=$(gh auth token)
+uv run kbforge run \
+  --connector github_issues \
+  --set repo=owner/name \
+  --mirror .kbforge/mirror --out .kbforge/out --state .kbforge/state
+```
+
+Add `--synthesizer llm --llm-set model=deepseek/deepseek-v4-flash` (with
+`kbforge[llm]` and `OPENROUTER_API_KEY`) to turn each issue into a synthesized concept
+instead of the verbatim stub.
+
+That run stops at the dry-run publisher, which writes the bundle under `--out`.
+To close the loop and open a real merge request (needs kbforge 0.3.0+; this
+package itself only depends on 0.2.0 APIs, since publishing is a kbforge CLI
+capability rather than something a connector links against):
+
+```bash
+export GITLAB_TOKEN=$(glab config get token --host gitlab.com)
+uv run kbforge run \
+  --connector github_issues --set repo=owner/name \
+  --publisher gitlab --publish-set repo=group/knowledge-base \
+  --publish-set base_path=kb-from-issues \
+  --mirror .kbforge/mirror --out .kbforge/out --state .kbforge/state
+```
+
+The two `repo` values are independent, and the example is deliberately
+cross-forge to make that obvious: the connector *reads* issues from GitHub, the
+publisher *writes* concepts to GitLab. Use `--publisher github` to target a
+GitHub repo instead — the connector side is unchanged either way.
+
+Both halves are credentialed, which is the one wrinkle worth knowing: this
+connector and the `github` publisher both default to `GITHUB_TOKEN`. When the
+source read and the knowledge-base write should carry different scopes, split
+them — `--set token_env=SOURCE_TOKEN` for the connector, `--publish-set
+token_env=KB_TOKEN` for the publisher.
+
+## Deliberately out of scope
+
+Kept simple so the shape stays legible — each of these is a natural enhancement if
+you extend it:
+
+- **Comments** aren't folded into the concept body (one extra API call per issue).
+- **Deletions** aren't derived from absence (a kbforge-wide gap — needs tombstones).
+- **HTTP errors** surface as a raw `httpx.HTTPStatusError` — a production connector
+  would distinguish 401 (bad token), 404 (repo not found), and 403 rate-limits
+  (honoring `X-RateLimit-Reset`) with clearer messages.
+- **Page-number pagination** with `sort=updated` can, in theory, skip or duplicate an
+  issue updated by someone else mid-fetch; it self-heals on the next incremental sync.