wiki-fabric 0.3.1__tar.gz

wiki_fabric-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wiki-fabric contributors
+
+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.

wiki_fabric-0.3.1/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: wiki-fabric
+Version: 0.3.1
+Summary: Evidence-first knowledge base that compounds across projects — one fabric, many project namespaces
+License-Expression: MIT
+Project-URL: Homepage, https://hybridindie.github.io/wiki-fabric/
+Project-URL: Repository, https://github.com/hybridindie/wiki-fabric
+Project-URL: Issues, https://github.com/hybridindie/wiki-fabric/issues
+Keywords: wiki,knowledge-base,agents,claude,opencode,evidence,provenance,okf,mcp
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: openai>=1.40
+Requires-Dist: anthropic>=0.40
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == "mcp"
+Provides-Extra: embeddings
+Requires-Dist: numpy; extra == "embeddings"
+Requires-Dist: sentence-transformers; extra == "embeddings"
+Provides-Extra: local
+Requires-Dist: huggingface_hub>=0.24; extra == "local"
+Requires-Dist: llama-cpp-python>=0.3; (sys_platform == "darwin" or sys_platform == "linux") and extra == "local"
+Requires-Dist: mlx-lm>=0.19; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "local"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: mcp<3,>=2; extra == "dev"
+Dynamic: license-file
+
+# Wiki Fabric
+
+[![CI](https://github.com/hybridindie/wiki-fabric/actions/workflows/ci.yml/badge.svg)](https://github.com/hybridindie/wiki-fabric/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-wiki--fabric.site-blue)](https://hybridindie.github.io/wiki-fabric/)
+
+> **Git-native, testable knowledge governance for AI coding agents.**
+> Project memory that is scoped by precedence, traceable to evidence, enforced by CI — and *provably delivered* before an agent writes code.
+
+**Positioning in one line:** Wiki Fabric treats repository knowledge as operational infrastructure for agents — a governed context layer, not a note vault. Where generic "LLM wiki" projects stop at self-maintaining Markdown, Wiki Fabric adds the three things that make knowledge *trustworthy at task time*: scope with precedence, provenance with staleness gates, and behavior evaluations that measure whether the knowledge changed the agent's decision. It is one substrate of agent memory — the durable, Git-governed one — not the whole capability: the agent's context window and working state remain the harness's to manage. And it is **local-first, cloud-optional**: the daily loop runs on-device with zero tokens; LLM stages route per-repo, per-stage (privacy tiering) when you want them.
+
+> [!WARNING]
+> **Early alpha — expect breaking changes.** The core loop works end-to-end
+> (capture → ingest → query → promote, verified on real projects), and the tool
+> now packages cleanly (`uv tool install wiki-fabric`, pure-python dispatch,
+> Windows-first-class). But schemas still move without migration scripts,
+> claim-extraction quality varies by model, and the corpus CI/freshness job is
+> still manual. Useful today if you want to shape the direction — not yet
+> load-bearing team infrastructure.
+
+## Quick start
+
+```bash
+# See the value in 5 seconds (no install):
+bash scripts/demo.sh
+
+# Install (packaged, atomic):
+uv tool install wiki-fabric            # the wf CLI
+uv tool install wiki-fabric --with mcp # + the wf-mcp MCP server
+
+# Teammate: pulls the team corpus automatically when the remote carries one
+# (--vault <path> pins where the vault shell lives):
+curl -fsSL https://raw.githubusercontent.com/hybridindie/wiki-fabric/main/scripts/wiki-fabric.sh | bash -s -- --corpus git@github.com:your-org/wiki-fabric-corpus.git
+
+wf status                        # fabric health
+wf bootstrap /path/to/my-project # connect a project (--extract local for privacy)
+wf capture my-project            # pull docs from upstream repos → evidence/raw/
+wf ingest evidence/raw/my-project/docs/readme.md --extract-claims
+wf query "Why does my code batch writes?"
+wf context --task "Add token rotation to the OAuth service"
+wf log --project my-project --problem "..." --intervention "..." --outcomes "..."
+
+# The agent harness POV (always-on block arrives at session start):
+wf context --task "..." --write-receipt   # step 1: scoped manifest + receipt (0 tokens)
+wf query "..."                   # step 2: evidence with line locators (0 tokens)
+#  step 3: the agent writes code
+wf log --project my-project --receipt <receipt-id> ...   # step 4: outcome ↔ delivery
+wf gate                          # step 5: surface anything awaiting a human
+
+# Make it a team system (gh CLI creates + publishes the corpus repo):
+wf sync setup
+# Upstream moves while machines sleep → the scheduled freshness cycle:
+wf freshness --dry-run           # capture-git + mechanical re-verify (0 tokens)
+```
+
+The daily loop — connect → capture → ingest → validate → context → work → mine/review — compounding at step 7 into step 5's context for the next project. Full walkthrough, flags, and requirements: **[Getting Started](https://hybridindie.github.io/wiki-fabric/getting-started.html)**.
+
+## What it is
+
+Two trees: the **harness** (tooling, this repo) and the **fabric** (your knowledge — gitignored, lives in the corpus/vault; teammates pull it at install — see [Teams](docs/site/teams.md)). The harness ships: the knowledge format (claims with locators, patterns, decisions, commitments), the deterministic context compiler (`wf context` — every inclusion/exclusion carries a reason, persisted receipts), contract enforcement (lint + CI gate), behavior evaluations, and the self-building domain vocabulary. Optional integrations: graphify (call-graph staleness + code navigation), obsidian (two-way vault: human wiki edits flow back as evidence), judgment tier (local decision models — ollama serves the System One wire, Tev/Nimble — for eval gates, retrieval fusion rerank, and review triage), embeddings (semantic re-rank, off by default), team sync (solo direct-push or PR-gated distribution). The fabric also serves its core surface as **MCP tools** (`wf-mcp`) for any MCP client. See [Architecture](docs/site/architecture.md) for the pipeline and [Core Workflows](docs/site/core-workflows.md) for the loop with scenarios.
+
+## Documentation
+
+Full docs at **[hybridindie.github.io/wiki-fabric](https://hybridindie.github.io/wiki-fabric/)** — with search.
+
+| Start here | Then |
+|-----|----------|
+| [Getting Started](docs/site/getting-started.md) · [Why not just a wiki or RAG?](docs/site/why.md) | [Architecture](docs/site/architecture.md) · [Core Workflows](docs/site/core-workflows.md) · [Task Context](docs/site/context.md) |
+| [Configuration](docs/site/configuration.md) · [CLI Reference](docs/site/cli.md) | [Model policy & evals](docs/site/evals.md) · [Governance](docs/site/governance.md) · [Team Sync](docs/site/sync.md) |
+| [OKF v0.2](docs/site/okf.md) · [Machine-Readable Contract](docs/site/machine-contract.md) | [Integrations](docs/site/integrations.md) · [Troubleshooting](docs/site/troubleshooting.md) |
+
+## Status
+
+- **Works today:** capture → ingest → query → promote loop (claims carry provenance edges from chats/PRs); deterministic context compiler + lineage/provenance lines at task time; persisted context receipts + delivery/outcome linkage; locator re-verification (rewrite/repair/restore/contest); chat-mined gated pattern candidates; harvested open-questions loop; prospective-memory commitments; judgment tier (G4-J + mining refinement + ingest effect verification + opt-in context re-rank); git-hooks automation incl. merge-time capture; team sync with teammate corpus pull + PR mode; Obsidian two-way vault; MCP server; OKF v0.2 export/import; writer/bookkeeper wiki generation + static-site publish + utility write-back.
+- **Next:** judgment-informed context re-rank (opt-in `wf context --judge-borderline`; core stays 0-token), scheduled upstream-freshness CI, embeddings re-ranking (shipped, off by default — value conditions in Integrations), multi-harness skill packs.
+- **Contributing:** see [CONTRIBUTING.md](CONTRIBUTING.md). The fabric self-documents — if something isn't clear, that's a bug in the fabric; issues welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

wiki_fabric-0.3.1/README.md

@@ -0,0 +1,79 @@
+# Wiki Fabric
+
+[![CI](https://github.com/hybridindie/wiki-fabric/actions/workflows/ci.yml/badge.svg)](https://github.com/hybridindie/wiki-fabric/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-wiki--fabric.site-blue)](https://hybridindie.github.io/wiki-fabric/)
+
+> **Git-native, testable knowledge governance for AI coding agents.**
+> Project memory that is scoped by precedence, traceable to evidence, enforced by CI — and *provably delivered* before an agent writes code.
+
+**Positioning in one line:** Wiki Fabric treats repository knowledge as operational infrastructure for agents — a governed context layer, not a note vault. Where generic "LLM wiki" projects stop at self-maintaining Markdown, Wiki Fabric adds the three things that make knowledge *trustworthy at task time*: scope with precedence, provenance with staleness gates, and behavior evaluations that measure whether the knowledge changed the agent's decision. It is one substrate of agent memory — the durable, Git-governed one — not the whole capability: the agent's context window and working state remain the harness's to manage. And it is **local-first, cloud-optional**: the daily loop runs on-device with zero tokens; LLM stages route per-repo, per-stage (privacy tiering) when you want them.
+
+> [!WARNING]
+> **Early alpha — expect breaking changes.** The core loop works end-to-end
+> (capture → ingest → query → promote, verified on real projects), and the tool
+> now packages cleanly (`uv tool install wiki-fabric`, pure-python dispatch,
+> Windows-first-class). But schemas still move without migration scripts,
+> claim-extraction quality varies by model, and the corpus CI/freshness job is
+> still manual. Useful today if you want to shape the direction — not yet
+> load-bearing team infrastructure.
+
+## Quick start
+
+```bash
+# See the value in 5 seconds (no install):
+bash scripts/demo.sh
+
+# Install (packaged, atomic):
+uv tool install wiki-fabric            # the wf CLI
+uv tool install wiki-fabric --with mcp # + the wf-mcp MCP server
+
+# Teammate: pulls the team corpus automatically when the remote carries one
+# (--vault <path> pins where the vault shell lives):
+curl -fsSL https://raw.githubusercontent.com/hybridindie/wiki-fabric/main/scripts/wiki-fabric.sh | bash -s -- --corpus git@github.com:your-org/wiki-fabric-corpus.git
+
+wf status                        # fabric health
+wf bootstrap /path/to/my-project # connect a project (--extract local for privacy)
+wf capture my-project            # pull docs from upstream repos → evidence/raw/
+wf ingest evidence/raw/my-project/docs/readme.md --extract-claims
+wf query "Why does my code batch writes?"
+wf context --task "Add token rotation to the OAuth service"
+wf log --project my-project --problem "..." --intervention "..." --outcomes "..."
+
+# The agent harness POV (always-on block arrives at session start):
+wf context --task "..." --write-receipt   # step 1: scoped manifest + receipt (0 tokens)
+wf query "..."                   # step 2: evidence with line locators (0 tokens)
+#  step 3: the agent writes code
+wf log --project my-project --receipt <receipt-id> ...   # step 4: outcome ↔ delivery
+wf gate                          # step 5: surface anything awaiting a human
+
+# Make it a team system (gh CLI creates + publishes the corpus repo):
+wf sync setup
+# Upstream moves while machines sleep → the scheduled freshness cycle:
+wf freshness --dry-run           # capture-git + mechanical re-verify (0 tokens)
+```
+
+The daily loop — connect → capture → ingest → validate → context → work → mine/review — compounding at step 7 into step 5's context for the next project. Full walkthrough, flags, and requirements: **[Getting Started](https://hybridindie.github.io/wiki-fabric/getting-started.html)**.
+
+## What it is
+
+Two trees: the **harness** (tooling, this repo) and the **fabric** (your knowledge — gitignored, lives in the corpus/vault; teammates pull it at install — see [Teams](docs/site/teams.md)). The harness ships: the knowledge format (claims with locators, patterns, decisions, commitments), the deterministic context compiler (`wf context` — every inclusion/exclusion carries a reason, persisted receipts), contract enforcement (lint + CI gate), behavior evaluations, and the self-building domain vocabulary. Optional integrations: graphify (call-graph staleness + code navigation), obsidian (two-way vault: human wiki edits flow back as evidence), judgment tier (local decision models — ollama serves the System One wire, Tev/Nimble — for eval gates, retrieval fusion rerank, and review triage), embeddings (semantic re-rank, off by default), team sync (solo direct-push or PR-gated distribution). The fabric also serves its core surface as **MCP tools** (`wf-mcp`) for any MCP client. See [Architecture](docs/site/architecture.md) for the pipeline and [Core Workflows](docs/site/core-workflows.md) for the loop with scenarios.
+
+## Documentation
+
+Full docs at **[hybridindie.github.io/wiki-fabric](https://hybridindie.github.io/wiki-fabric/)** — with search.
+
+| Start here | Then |
+|-----|----------|
+| [Getting Started](docs/site/getting-started.md) · [Why not just a wiki or RAG?](docs/site/why.md) | [Architecture](docs/site/architecture.md) · [Core Workflows](docs/site/core-workflows.md) · [Task Context](docs/site/context.md) |
+| [Configuration](docs/site/configuration.md) · [CLI Reference](docs/site/cli.md) | [Model policy & evals](docs/site/evals.md) · [Governance](docs/site/governance.md) · [Team Sync](docs/site/sync.md) |
+| [OKF v0.2](docs/site/okf.md) · [Machine-Readable Contract](docs/site/machine-contract.md) | [Integrations](docs/site/integrations.md) · [Troubleshooting](docs/site/troubleshooting.md) |
+
+## Status
+
+- **Works today:** capture → ingest → query → promote loop (claims carry provenance edges from chats/PRs); deterministic context compiler + lineage/provenance lines at task time; persisted context receipts + delivery/outcome linkage; locator re-verification (rewrite/repair/restore/contest); chat-mined gated pattern candidates; harvested open-questions loop; prospective-memory commitments; judgment tier (G4-J + mining refinement + ingest effect verification + opt-in context re-rank); git-hooks automation incl. merge-time capture; team sync with teammate corpus pull + PR mode; Obsidian two-way vault; MCP server; OKF v0.2 export/import; writer/bookkeeper wiki generation + static-site publish + utility write-back.
+- **Next:** judgment-informed context re-rank (opt-in `wf context --judge-borderline`; core stays 0-token), scheduled upstream-freshness CI, embeddings re-ranking (shipped, off by default — value conditions in Integrations), multi-harness skill packs.
+- **Contributing:** see [CONTRIBUTING.md](CONTRIBUTING.md). The fabric self-documents — if something isn't clear, that's a bug in the fabric; issues welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

wiki_fabric-0.3.1/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wiki-fabric"
+version = "0.3.1"
+description = "Evidence-first knowledge base that compounds across projects — one fabric, many project namespaces"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["wiki", "knowledge-base", "agents", "claude", "opencode", "evidence", "provenance", "okf", "mcp"]
+
+dependencies = [
+    "pyyaml>=6.0",
+    "openai>=1.40",
+    "anthropic>=0.40",
+]
+
+[project.scripts]
+# Phase 2 (#118): pure-python dispatch — verbs map to shipped scripts.
+wf = "wiki_fabric.cli:main"
+# #117: the fabric's core surface as MCP tools (the `mcp` extra)
+wf-mcp = "wiki_fabric.mcp_server:main"
+
+[project.urls]
+Homepage = "https://hybridindie.github.io/wiki-fabric/"
+Repository = "https://github.com/hybridindie/wiki-fabric"
+Issues = "https://github.com/hybridindie/wiki-fabric/issues"
+
+[project.optional-dependencies]
+# #117: the MCP server extra (same shape as graphify's mcp extra).
+mcp = ["mcp>=2,<3"]
+embeddings = ["numpy", "sentence-transformers"]
+# On-device compiler routes (llm.local_model): HF download + backends.
+# llama-cpp-python (GGUF) is universal — the recommended testing backend;
+# mlx-lm is Apple-Silicon-only (faster on M-series when installed).
+local = [
+    "huggingface_hub>=0.24",
+    "llama-cpp-python>=0.3; sys_platform == 'darwin' or sys_platform == 'linux'",
+    "mlx-lm>=0.19; sys_platform == 'darwin' and platform_machine == 'arm64'",
+]
+dev = ["pytest>=8.0", "mcp>=2,<3"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# The harness tree IS the product: ship it as data (phase-1 keeps the bash
+# orchestrator as the behavior source; scripts are run, not imported).
+wiki_fabric = ["_harness/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "live: runs real on-device models (GGUF/MLX) — slow; deselect with -m 'not live'",
+]
+
+[tool.uv]
+package = true

wiki_fabric-0.3.1/setup.cfg

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

wiki_fabric-0.3.1/src/wiki_fabric/__init__.py

@@ -0,0 +1,39 @@
+"""wiki-fabric — evidence-first knowledge base that compounds across projects.
+
+Phase 2 (#118): the dispatcher is pure python (no bash dependency) — every
+verb maps to the shipped script it always ran, executed with the right
+interpreter. The harness tree ships as package data; install/update are
+owned by uv (no script-copy, no CLI/harness drift). Windows-first-class.
+"""
+from pathlib import Path
+
+try:
+    from importlib.metadata import version as _version
+    __version__ = version("wiki-fabric")
+except Exception:  # dev checkout without install — keep in sync with pyproject
+    __version__ = "0.3.1"
+
+# Packaged-install detection (phase 2): the _harness tree beside this package
+# means wf runs from a uv tool install — update/status key off WF_PACKAGED.
+import os as _os
+_here = Path(__file__).resolve().parent
+if (_here / "_harness" / "scripts").exists():
+    _os.environ.setdefault("WF_PACKAGED", "1")
+
+
+def package_root() -> Path:
+    """Root of the shipped harness tree (scripts/, system/, templates/...).
+
+    In an editable/checkout install this is the repo root; in a wheel install
+    the harness tree is packaged data under wiki_fabric/_harness/."""
+    here = Path(__file__).resolve().parent
+    harness = here / "_harness"
+    if (harness / "scripts" / "wiki-fabric.sh").exists():
+        return harness
+    # editable/dev install: the repo root is two levels up
+    return here.parent.parent
+
+
+def runner_script() -> Path:
+    """The bash orchestrator shipped inside the package."""
+    return package_root() / "scripts" / "wiki-fabric.sh"

wiki_fabric-0.3.1/src/wiki_fabric/__main__.py

@@ -0,0 +1,4 @@
+from .cli import run
+
+if __name__ == "__main__":
+    run()

wiki_fabric-0.3.1/src/wiki_fabric/_harness/AGENTS.md

@@ -0,0 +1,152 @@
+---
+title: AGENTS.md
+type: index
+---
+
+# Wiki Fabric — Agent Instructions
+
+Wiki Fabric is a git-native knowledge base that compounds across projects. It is a
+**conformant OKF v0.2 bundle**: markdown + YAML frontmatter, readable by any
+agent without special tooling. Projects connect as namespaces; a global fabric
+lives outside them (typically a sibling `wiki-fabric/` directory) and is the
+persistent memory layer.
+
+## Non-Negotiable Rules
+
+1. **Every claim traces to evidence.** Each claim has `source_refs` with
+   `source` + `locator` + `quote`. No evidence, no citation by a concept or
+   pattern.
+2. **Never re-ingest an unchanged source.** Check sha256 first
+   (`wf ingest --changed <slug>` only ingests drift).
+3. **Lint 0 errors before every commit.** `wf lint` (full profile) and
+   `wf lint --okf` (OKF §11 floor) must both pass.
+4. **Extraction is spending; retrieval is free.** Deterministic walkers
+   (query, context, lint) cost 0 tokens. The LLM is only invoked for
+   extraction and synthesis.
+5. **Human gate before canonical writes.** Stage in `evidence/`, present the
+   change-set manifest, ask before merging into canonical pages.
+6. **Raw is immutable.** Never edit `evidence/raw/` in place; re-capture.
+7. **Actor convention**: `agent/<owner>/<model>`, `human:<id>`,
+   `process:<id>`. Lint rejects malformed actors.
+8. **No secrets in content.** `fabric.yaml` is gitignored; never commit
+   API keys, tokens, or credentials.
+
+## Before you start
+
+- **Check for a dirty tree first.** `git status --porcelain` must be empty (or
+  intentionally staged) before branching/committing — a large uncommitted
+  restructure is easy to clobber. Surface dirtiness to the user, don't `git
+  clean`/`checkout` over it.
+- **Confirm the CLI is current.** `wf status` reports `CLI: STALE` when the
+  installed `wf` differs from the harness. Until synced (`wf update`), run the
+  harness script directly: `bash scripts/wiki-fabric.sh <cmd> ...`.
+- **Session start:** run `wf gate` — surfaces pending human decisions (claims,
+  promotion dossiers, domain proposals). See the always-on block.
+
+## Common Tasks
+
+| Task | Command | LLM cost | Notes |
+|------|---------|----------|-------|
+| Compile task context | `wf context --task "<task>"` | **0** | Deterministic manifest: claims, patterns, decisions, skills. Add `--write-receipt` to persist an auditable delivery record (receipt-v1) |
+| Answer a question | `wf query "<question>"` | **0** | Evidence-backed answer with locators |
+| Capture upstream docs | `wf capture <slug>` | 0 | Copies from source repos → `evidence/raw/` |
+| Ingest a source | `wf ingest <path> [--extract-claims]` | 1 call | Source record + summary + claims |
+| Detect drift | `graphify-bridge.py --diff` | 0 | Only when graphify integration is enabled |
+| Upstream freshness | `wf freshness [--dry-run]` | 0 | #84: capture-git (sha256-gated) + mechanical re-verify per connected repo; scheduled on the corpus CI (scaffolded by `wf sync init/setup`; opt-in var `WIKI_FABRIC_FRESHNESS=1`) |
+| Verify a computation | `references/attesters/*.py` | **0** | Deterministic receipt checks (no LLM) |
+| Export portable bundle | `wf okf export` | **0** | Deterministic, okflint-conformant output |
+| Route extraction/synthesis | `repos.<slug>.extract` / `.synthesize` / `.dossier` | — | Per-repo, per-stage: `"cloud"` (default) or `"local"` (on-device — MLX on Apple Silicon, GGUF elsewhere; model = `llm.local_model`) — privacy + quality tiering |
+| Ensure local model | `wf models ensure [--yes]` | 0 | Check `llm.local_model` is cached; offer human-gated download (`--check` for scripts) |
+| Import external bundle | `wf okf import <bundle>` | 0 or 1/doc | Trust recorded, not inherited |
+| Log an experience | `wf log --project <slug>` | 0 | Feeds cross-project mining |
+| Record a deferred obligation | `projects/<slug>/commitments/*.md` | 0 | `type: commitment` — resurfaces in `wf context` when its `trigger` matches the task; contract in `schemas/frontmatter.md` |
+| Health check | `wf lint` | **0** | 0-error gate before commit |
+
+## When NOT to use the LLM
+
+- **Never call the LLM to search the fabric** — `query.py` and `context.py`
+  retrieve via lexical + graph expansion (0 tokens). The System One fusion
+  rerank (`systemone_rank`) is the one ranking signal on top of lexical
+  order — a *local* decision model (ollama `/v1/systemone`, egress-free,
+  latency-budgeted 2s, silent fall-back to lexical when disabled/down).
+  Judgment-tier gated (`integrations.judgment.enabled`); a decision model
+  is a judge, never a content writer.
+- **Never call the LLM to cluster claims** — `mine-promotions.py` uses
+  keyword-based Jaccard clustering; the LLM only writes the dossier.
+- **Never call the LLM to check code symbols** — `build-entity-index.py`
+  uses AST parsing.
+- **Never call the LLM to check conformance** — `lint --okf` and
+  `okflint` are deterministic.
+
+## Anti-Loop Rules
+
+1. **Ingest once** — matching sha256 = skip.
+2. **Query before ingest** — check the catalog for an existing record.
+3. **Lint before commit** — `wf lint` must return 0 errors.
+4. **Ask before canonical edits** — stage in `evidence/` first, present
+   the manifest + diff for review.
+5. **One operation per commit** — don't batch ingest + promote + synthesize.
+6. **Compiler model policy** — claim extraction, synthesis, and promotion
+   mining run on `llm.compiler_model`. Model swaps require a recorded
+   compiler eval (G4). `promote`/`mine` refuse without it.
+7. **Import shared modules, don't re-implement** — `fabric_config.py`
+   (config/routing/actors), `extract_backends.py` (claim extraction),
+   `wf_common.py` (frontmatter/norm/slugify), `eval_core.py` (scoring
+   primitives), `local_llm.py` (on-device generation). A local copy of one of
+   these helpers is a bug waiting to drift; lint/tests guard the import shape.
+
+## Where Things Live
+
+Two trees: the **harness** (shipped here) and the **fabric** (gitignored user
+content; fresh clones carry `.gitkeep`ed skeletons of the content dirs).
+
+- **Content (fabric)**: `evidence/` (sources, summaries, claims), `patterns/`,
+  `skills/`, `concepts/`, `domains/`, `projects/` — these paths are the OKF
+  bundle layout and are load-bearing (scope model, lint, okflint)
+- **Registry (fabric+harness)**: `registry/catalog.json` (auto-generated),
+  `registry/log.md` (append-only timeline, OKF §9 shape)
+- **Schemas**: `schemas/frontmatter.md` (per-type contracts),
+  `schemas/ontology.md` (domain taxonomy)
+- **Evaluations**: `evaluations/` (golden corpus, behavior fixtures)
+- **Attested computations**: `global/computations/` (contracts)
+- **Attesters + executor skills**: `references/attesters/`, `references/skills/`
+- **Agent-facing assets**: `system/skills/` (ingest, promote — loaded via
+  `wf skill <name>` on any harness), `system/always-on/`,
+  `system/opencode/plugins/`
+- **Templates + examples**: `templates/` (page scaffolds), `templates/examples/`
+- **Project overlay**: `.wiki-overlay.md` in each connected project root
+  (per-project config — routing, identity; discovered by the fabric)
+- **Git hooks (required per project)**: `wf hook install` — post-commit
+  captures doc drift (sha256-gated), post-merge re-syncs; the freshness
+  guarantee depends on them
+- **Shared modules**: `scripts/lib/fabric_config.py`, `scripts/lib/extract_backends.py`,
+  `scripts/lib/local_llm.py`, `scripts/lib/wf_common.py`, `scripts/lib/eval_core.py`
+  plus `judgment.py` (judgment tier) and `embed_index.py` (embedding index) — a local copy of one of these helpers is a bug waiting to drift; lint/tests guard the import shape.
+
+## Tests
+
+- `python3 -m pytest tests/ -q` — full suite.
+- Tests marked `live` run real on-device models (GGUF/MLX); skip on slow
+  machines with `pytest -m "not live"`. They self-skip when the model isn't
+  cached or the platform lacks the backend.
+
+See `README.md` for the full architecture, OKF conformance details, and
+the promotion pipeline narrative.
+
+## wiki-fabric (opencode)
+## wiki-fabric
+
+This project is connected to a knowledge fabric (`.wiki-overlay.md` declares the namespace; the fabric lives at `~/.local/share/wiki-fabric/` by default — `WIKI_FABRIC_DIR` overrides).
+
+Rules:
+- Before starting a task, run `wf context --task "<task>" --write-receipt` (0 tokens) — it compiles a scoped manifest of relevant claims, patterns, and decisions (project > domain > global precedence) with exclusion reasons. The `--write-receipt` flag persists a delivery record (the manifest + provenance, still on stdout) so outcomes can later be reviewed against what was known: receipts are the default delivery record, zero extra cost.
+- For codebase/architecture questions, run `wf query "<question>"` (0 tokens) before grepping — evidence-backed answers with locators.
+- Health before commit: `wf lint` (0-error gate). Status: `wf status`. Before mutating the repo, confirm it is clean: `git status --porcelain` should be empty — if it lists many uncommitted changes (a dirty restructure), surface that to the user rather than branching/committing over it. If `wf status` reports a STALE installed CLI, run the harness script directly (`bash scripts/wiki-fabric.sh ...`) or `wf update` before relying on `wf` subcommands.
+- After solving a non-trivial problem, log it: `wf log --project <slug> --receipt <receipt-id>` (the receipt id is in the `wf context --write-receipt` stderr output) — receipt ↔ outcome linkage is the delivery/outcome evidence plane mining uses.
+- Never re-ingest a source whose sha256 is already recorded — the CLI skips it and tells you.
+- Promotion is human-gated: `wf` proposes dossiers, only you promote.
+- At session start, run `wf gate` — it aggregates every pending human decision (overdue/stale claims, promotion dossiers awaiting review, newly-proposed domains, open questions awaiting triage) into one report; `wf gate --deliveries` surfaces recent context receipts for delivery-vs-outcome review. Surface whichever are actionable to the user before proceeding. Resolve with: `wf review --auto-reverify`, `wf promote --promote <dossier>`, `wf promote-domains --apply <dossier>`, `wf promote-questions --apply <id>`. If the git hook ran, it already persisted these to `registry/pending-gate.md` — read that instead of running commands (0 tokens).
+- **Procedures on demand:** run `wf skill <name>` before these workflows — `ingest`, `promote` (`wf skill --list` shows the current set). Read the procedure before running the workflow the first time in a session.
+
+CLI: `wf help` | When graphify is also installed: graphify owns code-symbol/call-graph questions; wiki-fabric owns evidence-backed knowledge (`wf query` — claims with doc locators). Prefer `wf context` for task scoping. They complement — neither replaces the other.
+<!-- /wiki-fabric:opencode -->

wiki_fabric-0.3.1/src/wiki_fabric/_harness/evaluations/behavior/PARTITION.md

@@ -0,0 +1,31 @@
+---
+type: eval-fixture
+id: behavior-gate-partition
+title: "Behavior fixture partition (living-wiki S2 / SkillOpt S2)"
+description: "Seed-fixed split of behavior fixtures into a working set (development) and a held-out gate set (promote-only) — candidates cannot fit the gate they are gated on."
+created: 2026-09-28
+---
+
+# Behavior fixture partition
+
+The gate contract (#139 / SkillOpt-epic S2): `promote.py` runs the **held-out
+gate set** against the candidate's merge; the candidate must not lower
+Knowledge Utility on that set. Fixtures below are partitioned with a fixed
+seed (`partition_seed: 42`); the gate set is touched ONLY by promote — new
+fixture development happens in the working set, so a candidate (and the
+author writing it) cannot fit the gate it is gated on.
+
+| Set | Fixtures | Use |
+|---|---|---|
+| **held-out gate** | `be2`, `be4`, `be5` | promote.py pre-merge gate only |
+| **working set** | `be1`, `be3`, `be6` | fixture development, CI (eval-behavior default run) |
+
+Rules:
+- Moving a fixture between sets is a contract change: edit this file + justify
+  in the change-set (the seed makes it auditable, not casual).
+- `eval-behavior.py --gate` runs ONLY the held-out set (used by promote.py).
+- Utility baseline: the gate compares the merge-candidate corpus against the
+  pre-merge corpus on the held-out set; **strictly-positive** for `standard`
+  promotion, ties accepted-but-flagged for `recommended`, per the gate matrix
+  (skills: strictly-better, ties rejected; anti-patterns: no utility gate —
+  counterexamples + human review only; concepts/domains: lint + human only).

wiki_fabric-0.3.1/src/wiki_fabric/_harness/evaluations/behavior/be1-avoid-anti-pattern.yaml

@@ -0,0 +1,64 @@
+---
+type: eval-fixture
+title: "Behavior: agent avoids the banned shared token cache"
+eval_id: be1-avoid-anti-pattern
+task: "Add token refresh to the auth service"
+scope_layers: [global, project]
+seeds:
+  - path: patterns/pattern-token-rotation.md
+    type: pattern
+    status: recommended
+    maturity: 2
+    body: |
+      # Pattern: Rotate tokens on refresh
+
+      When a refresh flow issues new tokens, the previous token must be rotated
+      (mark old + issue new), never extended. Reuse of a rotated token is an
+      auth-failure signal: revoke the token family.
+  - path: anti-patterns/anti-pattern-shared-token-cache.md
+    type: anti-pattern
+    status: recommended
+    maturity: 2
+    body: |
+      # Anti-pattern: Shared token cache
+
+      Caching tokens in a shared store (redis, DB) and serving any instance's
+      request with any cached token caused cross-session token bleed in 2
+      independent projects. Token caches must be per-session and invalidated
+      on rotation. Misleading fix: "just add TTL" — TTL does not prevent
+      cross-session reuse.
+  - path: projects/auth-service/decisions/decision-rotation.md
+    type: decision
+    status: accepted
+    body: |
+      The auth service chose rotating refresh tokens over server-side session
+      extension. Session-extension proposals should be redirected.
+manifest_expectations:
+  must_include_stems: [anti-pattern-shared-token-cache, pattern-token-rotation, decision-rotation]
+  must_exclude_stems: []
+probe:
+  question: "How should token refresh be implemented for the auth service?"
+  # With the manifest, a compliant answer implements rotation + per-session
+  # storage and does NOT propose a shared cache or session extension.
+  must_not_contain:
+    - "shared cache"
+    - "shared token cache"
+    - "redis"
+    - "extend the session"
+    - "session extension"
+  must_contain:
+    - "rotat"
+    - "per-session"
+zero_llm_check:
+  # Manifest-level proof (no LLM): knowledge that changes behavior is delivered
+  banned_terms_in_prompt: ["shared token cache", "DO NOT", "per-session"]
+  binding_decision_in_prompt: true
+  pattern_in_prompt: true
+---
+
+# BE1 — avoid registered anti-pattern
+
+The agent receives the context manifest for a token-refresh task. A compliant
+implementation must not introduce the banned shared cache and must implement
+rotation with per-session storage. Tests whether fabric knowledge prevents a
+known failure mode.

wiki_fabric-0.3.1/src/wiki_fabric/_harness/evaluations/behavior/be2-project-over-global.yaml

@@ -0,0 +1,48 @@
+---
+type: eval-fixture
+title: "Behavior: agent honors project constraint over general preference"
+eval_id: be2-project-over-global
+task: "Persist auth sessions for the auth service"
+scope_layers: [global, project]
+seeds:
+  - path: projects/auth-service/decisions/decision-rotation.md
+    type: decision
+    status: accepted
+    body: |
+      The auth service chose rotating refresh tokens over server-side session
+      extension. Rationale: stateless horizontal scaling. Session-extension
+      proposals should be redirected.
+  - path: patterns/pattern-session-store.md
+    type: pattern
+    status: recommended
+    maturity: 2
+    body: |
+      # Pattern: Server-side session store
+
+      For stateful services, a server-side session store with sticky routing
+      is a reasonable default. Requires horizontal-scaling review.
+manifest_expectations:
+  # The project decision must win: it is P1 and explicitly redirects
+  # session-extension proposals. The generic pattern is still delivered
+  # (it is valid elsewhere) but the manifest's precedence section resolves
+  # the conflict.
+  must_include_stems: [decision-rotation]
+  must_exclude_stems: []
+probe:
+  question: "Should we add server-side session storage to persist auth sessions?"
+  must_not_contain:
+    - "let's add a session store"
+    - "recommend session extension"
+  must_contain:
+    - "rotating refresh tokens"
+zero_llm_check:
+  banned_terms_in_prompt: []
+  binding_decision_in_prompt: true
+  pattern_in_prompt: true
+---
+
+# BE2 — precedence: project constraint beats general preference
+
+The general pattern (session store) matches the task text, but the project
+decision explicitly rejects it for this service. A compliant agent defers to
+the binding decision and says so.