synlynk 0.27.5__tar.gz

synlynk-0.27.5/LICENSE

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

synlynk-0.27.5/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: synlynk
+Version: 0.27.5
+Summary: The coordination OS for multi-agent development — context injection, dispatch, telemetry, and sentinel for Claude, Agy, Codex, and Grok.
+License: MIT
+Project-URL: Homepage, https://synlynk.com
+Project-URL: Repository, https://github.com/nikhilsoman/synlynk
+Project-URL: Bug Tracker, https://github.com/nikhilsoman/synlynk/issues
+Project-URL: Changelog, https://github.com/nikhilsoman/synlynk/blob/main/CHANGELOG.md
+Keywords: ai,agents,claude,codex,gemini,grok,multi-agent,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
+Provides-Extra: hub
+Requires-Dist: nats-py>=2.16.0; extra == "hub"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/img/logo/lockup.svg" alt="synlynk — neutral control plane for coding tasks" height="80">
+</p>
+
+<p align="center"><strong>Synlynk is a neutral control plane that routes coding tasks across AI vendors and local models, then proves the result.</strong></p>
+<p align="center"><a href="https://synlynk.com">synlynk.com</a></p>
+
+<p align="center">
+  <a href="https://github.com/nikhilsoman/synlynk"><img src="https://img.shields.io/badge/tests-5399%20collected-brightgreen" alt="Tests"</a>
+  <a href="https://github.com/nikhilsoman/synlynk"><img src="https://img.shields.io/badge/version-0.27.5-blue" alt="Version"></a>
+  <a href="https://github.com/nikhilsoman/synlynk"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  <a href="https://github.com/nikhilsoman/synlynk"><img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python"></a>
+</p>
+
+Synlynk is a neutral control plane that routes coding tasks across AI vendors and local models, then proves the result. The Python CLI injects scoped project context into every dispatch, uses empirical harness allocation only after a harness has at least five completed, merged jobs for the relevant task type, and follows the documented interim policy until then. See the [empirical capability policy](docs/blog/244-chore-empirical-capability-policy.md) and [routing policy](.synlynk/policy.json). Synlynk also tracks costs and hallucination loops. A shared `project-docs/` directory keeps every tool in sync: Claude Code, Codex, and AGY all read the same context, decisions, and progress.
+
+**v0.27.5:** Developer Preview Stable Release — Full 6-gate operationalization milestone including VS Code / OpenVSX extension listing & distribution (v0.27.0), verified sub-15-minute quickstart onboarding loop (v0.27.1), prerequisite auditing & doctor self-healing remediation (v0.27.2), 5-way cross-harness journey matrix for Claude, Codex, Agy, Grok, and Muse (v0.27.3), comprehensive acceptance matrix and GOVERNS audit (v0.27.4), and stable distribution packaging (v0.27.5). 5399 tests collected.
+
+## Documentation
+
+Start with the [documentation hub](docs/README.md), the [10-minute quickstart](docs/quickstart.md), or a [task-oriented how-to](docs/how-to/README.md). The complete [command reference](docs/reference/commands.md) is generated from `COMMAND_TAXONOMY`.
+
+| | | |
+|:---:|:---:|:---:|
+| [![Official Reference](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/site/src/assets/img/docs/synlynk-official-reference-thumb.png)](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/docs/synlynk-official-reference.pdf) | [![Command Reference](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/site/src/assets/img/docs/synlynk-command-reference-thumb.png)](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/docs/synlynk-command-reference.pdf) | [![Quick Start Guide](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/site/src/assets/img/docs/synlynk-quickstart-guide-thumb.png)](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/docs/synlynk-quickstart-guide.pdf) |
+| **[Official Reference](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/docs/synlynk-official-reference.pdf)** | **[Command Reference](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/docs/synlynk-command-reference.pdf)** | **[Quick Start Guide](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/docs/synlynk-quickstart-guide.pdf)** |
+| 14-page full reference: architecture, all commands, agent profiles, relay, SQLite schema, changelog | 9-page command catalog: flags, options, usage scenarios | 5-page getting started: install, init, dispatch, invite |
+
+## Install
+
+**From PyPI (Standard / Global CLI):**
+```bash
+pip install synlynk
+# or isolated via pipx
+pipx install synlynk
+```
+
+**From Source / Git:**
+```bash
+pipx install git+https://github.com/nikhilsoman/synlynk
+```
+
+**Visual Studio Code Extension:**
+Native IDE reach into agent dispatch, jobs, logs, and diagnostics is available in [`clients/vscode/`](clients/vscode/).
+
+**Run directly without installing (contributor / checkout mode):**
+```bash
+python3 bin/synlynk.py <command>
+```
+
+**Requirements:** Python 3.10+, stdlib only — zero required external dependencies.
+
+## Quick start
+
+Get up and running in 60 seconds:
+
+1. **Install synlynk globally:**
+   ```bash
+   pipx install git+https://github.com/nikhilsoman/synlynk
+   ```
+
+2. **Initialize your project:**
+   Runs the interactive FTUE wizard to discover installed AI agent CLI tools, configure workspace topology, and bootstrap project state.
+   ```bash
+   synlynk init --wizard
+   ```
+
+3. **Analyze repository structure:**
+   Scans the codebase to build and update the static source map.
+   ```bash
+   synlynk scan
+   ```
+
+4. **Migrate existing flat-file projects (optional):**
+   If you have a project created using an older version of synlynk, migrate its `project-docs/` markdown files to `state.db`.
+   ```bash
+   synlynk migrate
+   ```
+
+5. **Dispatch a task to an agent in the background:**
+   ```bash
+   synlynk dispatch claude --task "refactor auth module"
+   ```
+   `--task` must be a non-empty string — `dispatch_agent()` fails closed on an empty or whitespace-only task before creating any job, worktree, or cost entry (see [#720](https://github.com/nikhilsoman/synlynk/issues/720))
+   If `--task` is built from a shell variable in automation, don't interpolate it unchecked — an unset variable silently expands to an empty string
+   Sanity-check what a dispatch would actually send with `--dry-run` first:
+   ```bash
+   synlynk dispatch claude --task "$TASK_VAR" --dry-run
+   ```
+
+   Every dispatched agent is also asked to echo a receipt marker
+   (`SYNLYNK_TASK_RECEIVED: <task_sha256>`) as its literal first line of
+   output, confirming it received the exact task text before doing any
+   work. If a job's log is missing this marker (or prints it late, or with
+   the wrong digest) and no corroborating git activity shows up in its
+   worktree, Synlynk marks the job `task_delivery_failed` and skips
+   auto-finalize/push for that worktree — the files stay in place for
+   audit. If real work *did* land despite a missing/late marker, the job
+   is not blocked; it's flagged with a non-blocking WARN note instead
+   (see #720).
+
+6. **Check running jobs:**
+   ```bash
+   synlynk jobs
+   ```
+
+7. **Tail a job's output:**
+   ```bash
+   synlynk logs --job <job-id>
+   ```
+
+## How it works
+
+At the core of synlynk is a dual-storage model designed for agent speed and Git reliability:
+
+- **`state.db` is the permanent source of truth** for all project state, including stories, roadmaps, memories, devlogs, and costs.
+- **`project-docs/` flat files are write-through backups.** Every write to `state.db` automatically updates the corresponding markdown files in `project-docs/` (e.g., `todo.md`, `roadmap.md`, `memory.md`, `costs.md`). This ensures a human-readable, Git-trackable record of project state.
+- **`generate_context()` resolves state dynamically.** Once a project is migrated, it reads directly from the SQLite database to compile the current active context. For non-migrated repositories, it falls back to reading raw flat files.
+- **`synlynk exec <cmd>` manages context injection.** Before handing off to your AI tool, it compiles the active tasks and decisions, writes a compacted snapshot to `.synlynk/context.md` (active tasks only, no completed items), and checks cumulative spend limits in `.synlynk/config.json`. After the session ends, it detects flatline loops (3 consecutive failures of the same command) and writes alerts to `sentinel.md`.
+
+The AI tool is instructed (via `CLAUDE.md` / `GEMINI.md`) to read `.synlynk/context.md` at session start. Cost tracking is fully automated: `state.db` records costs to the `cost_entries` table, which are written through to `project-docs/costs.md`.
+
+## Commands
+
+Commands are grouped by where you'll reach for them in a typical project lifecycle.
+
+<!-- commands:start -->
+
+**Start here:**
+
+- `synlynk home`
+- `synlynk init`
+- `synlynk start`
+- `synlynk quickstart`
+- `synlynk brainstorm`
+- `synlynk brief`
+- `synlynk scan`
+- `synlynk join`
+- `synlynk governs`
+- `synlynk preflight`
+- `synlynk status`
+- `synlynk watch`
+- `synlynk viz`
+
+Full command reference: [docs/reference/commands.md](docs/reference/commands.md)
+
+<!-- commands:end -->
+<!-- commands:end -->

synlynk-0.27.5/README.md

@@ -0,0 +1,148 @@
+<p align="center">
+  <img src="docs/img/logo/lockup.svg" alt="synlynk — neutral control plane for coding tasks" height="80">
+</p>
+
+<p align="center"><strong>Synlynk is a neutral control plane that routes coding tasks across AI vendors and local models, then proves the result.</strong></p>
+<p align="center"><a href="https://synlynk.com">synlynk.com</a></p>
+
+<p align="center">
+  <a href="https://github.com/nikhilsoman/synlynk"><img src="https://img.shields.io/badge/tests-5399%20collected-brightgreen" alt="Tests"</a>
+  <a href="https://github.com/nikhilsoman/synlynk"><img src="https://img.shields.io/badge/version-0.27.5-blue" alt="Version"></a>
+  <a href="https://github.com/nikhilsoman/synlynk"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  <a href="https://github.com/nikhilsoman/synlynk"><img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python"></a>
+</p>
+
+Synlynk is a neutral control plane that routes coding tasks across AI vendors and local models, then proves the result. The Python CLI injects scoped project context into every dispatch, uses empirical harness allocation only after a harness has at least five completed, merged jobs for the relevant task type, and follows the documented interim policy until then. See the [empirical capability policy](docs/blog/244-chore-empirical-capability-policy.md) and [routing policy](.synlynk/policy.json). Synlynk also tracks costs and hallucination loops. A shared `project-docs/` directory keeps every tool in sync: Claude Code, Codex, and AGY all read the same context, decisions, and progress.
+
+**v0.27.5:** Developer Preview Stable Release — Full 6-gate operationalization milestone including VS Code / OpenVSX extension listing & distribution (v0.27.0), verified sub-15-minute quickstart onboarding loop (v0.27.1), prerequisite auditing & doctor self-healing remediation (v0.27.2), 5-way cross-harness journey matrix for Claude, Codex, Agy, Grok, and Muse (v0.27.3), comprehensive acceptance matrix and GOVERNS audit (v0.27.4), and stable distribution packaging (v0.27.5). 5399 tests collected.
+
+## Documentation
+
+Start with the [documentation hub](docs/README.md), the [10-minute quickstart](docs/quickstart.md), or a [task-oriented how-to](docs/how-to/README.md). The complete [command reference](docs/reference/commands.md) is generated from `COMMAND_TAXONOMY`.
+
+| | | |
+|:---:|:---:|:---:|
+| [![Official Reference](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/site/src/assets/img/docs/synlynk-official-reference-thumb.png)](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/docs/synlynk-official-reference.pdf) | [![Command Reference](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/site/src/assets/img/docs/synlynk-command-reference-thumb.png)](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/docs/synlynk-command-reference.pdf) | [![Quick Start Guide](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/site/src/assets/img/docs/synlynk-quickstart-guide-thumb.png)](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/docs/synlynk-quickstart-guide.pdf) |
+| **[Official Reference](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/docs/synlynk-official-reference.pdf)** | **[Command Reference](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/docs/synlynk-command-reference.pdf)** | **[Quick Start Guide](https://raw.githubusercontent.com/nikhilsoman/synlynk/main/docs/synlynk-quickstart-guide.pdf)** |
+| 14-page full reference: architecture, all commands, agent profiles, relay, SQLite schema, changelog | 9-page command catalog: flags, options, usage scenarios | 5-page getting started: install, init, dispatch, invite |
+
+## Install
+
+**From PyPI (Standard / Global CLI):**
+```bash
+pip install synlynk
+# or isolated via pipx
+pipx install synlynk
+```
+
+**From Source / Git:**
+```bash
+pipx install git+https://github.com/nikhilsoman/synlynk
+```
+
+**Visual Studio Code Extension:**
+Native IDE reach into agent dispatch, jobs, logs, and diagnostics is available in [`clients/vscode/`](clients/vscode/).
+
+**Run directly without installing (contributor / checkout mode):**
+```bash
+python3 bin/synlynk.py <command>
+```
+
+**Requirements:** Python 3.10+, stdlib only — zero required external dependencies.
+
+## Quick start
+
+Get up and running in 60 seconds:
+
+1. **Install synlynk globally:**
+   ```bash
+   pipx install git+https://github.com/nikhilsoman/synlynk
+   ```
+
+2. **Initialize your project:**
+   Runs the interactive FTUE wizard to discover installed AI agent CLI tools, configure workspace topology, and bootstrap project state.
+   ```bash
+   synlynk init --wizard
+   ```
+
+3. **Analyze repository structure:**
+   Scans the codebase to build and update the static source map.
+   ```bash
+   synlynk scan
+   ```
+
+4. **Migrate existing flat-file projects (optional):**
+   If you have a project created using an older version of synlynk, migrate its `project-docs/` markdown files to `state.db`.
+   ```bash
+   synlynk migrate
+   ```
+
+5. **Dispatch a task to an agent in the background:**
+   ```bash
+   synlynk dispatch claude --task "refactor auth module"
+   ```
+   `--task` must be a non-empty string — `dispatch_agent()` fails closed on an empty or whitespace-only task before creating any job, worktree, or cost entry (see [#720](https://github.com/nikhilsoman/synlynk/issues/720))
+   If `--task` is built from a shell variable in automation, don't interpolate it unchecked — an unset variable silently expands to an empty string
+   Sanity-check what a dispatch would actually send with `--dry-run` first:
+   ```bash
+   synlynk dispatch claude --task "$TASK_VAR" --dry-run
+   ```
+
+   Every dispatched agent is also asked to echo a receipt marker
+   (`SYNLYNK_TASK_RECEIVED: <task_sha256>`) as its literal first line of
+   output, confirming it received the exact task text before doing any
+   work. If a job's log is missing this marker (or prints it late, or with
+   the wrong digest) and no corroborating git activity shows up in its
+   worktree, Synlynk marks the job `task_delivery_failed` and skips
+   auto-finalize/push for that worktree — the files stay in place for
+   audit. If real work *did* land despite a missing/late marker, the job
+   is not blocked; it's flagged with a non-blocking WARN note instead
+   (see #720).
+
+6. **Check running jobs:**
+   ```bash
+   synlynk jobs
+   ```
+
+7. **Tail a job's output:**
+   ```bash
+   synlynk logs --job <job-id>
+   ```
+
+## How it works
+
+At the core of synlynk is a dual-storage model designed for agent speed and Git reliability:
+
+- **`state.db` is the permanent source of truth** for all project state, including stories, roadmaps, memories, devlogs, and costs.
+- **`project-docs/` flat files are write-through backups.** Every write to `state.db` automatically updates the corresponding markdown files in `project-docs/` (e.g., `todo.md`, `roadmap.md`, `memory.md`, `costs.md`). This ensures a human-readable, Git-trackable record of project state.
+- **`generate_context()` resolves state dynamically.** Once a project is migrated, it reads directly from the SQLite database to compile the current active context. For non-migrated repositories, it falls back to reading raw flat files.
+- **`synlynk exec <cmd>` manages context injection.** Before handing off to your AI tool, it compiles the active tasks and decisions, writes a compacted snapshot to `.synlynk/context.md` (active tasks only, no completed items), and checks cumulative spend limits in `.synlynk/config.json`. After the session ends, it detects flatline loops (3 consecutive failures of the same command) and writes alerts to `sentinel.md`.
+
+The AI tool is instructed (via `CLAUDE.md` / `GEMINI.md`) to read `.synlynk/context.md` at session start. Cost tracking is fully automated: `state.db` records costs to the `cost_entries` table, which are written through to `project-docs/costs.md`.
+
+## Commands
+
+Commands are grouped by where you'll reach for them in a typical project lifecycle.
+
+<!-- commands:start -->
+
+**Start here:**
+
+- `synlynk home`
+- `synlynk init`
+- `synlynk start`
+- `synlynk quickstart`
+- `synlynk brainstorm`
+- `synlynk brief`
+- `synlynk scan`
+- `synlynk join`
+- `synlynk governs`
+- `synlynk preflight`
+- `synlynk status`
+- `synlynk watch`
+- `synlynk viz`
+
+Full command reference: [docs/reference/commands.md](docs/reference/commands.md)
+
+<!-- commands:end -->
+<!-- commands:end -->

synlynk-0.27.5/VERSION

@@ -0,0 +1 @@
+0.27.5

synlynk-0.27.5/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "synlynk"
+dynamic = ["version"]
+description = "The coordination OS for multi-agent development — context injection, dispatch, telemetry, and sentinel for Claude, Agy, Codex, and Grok."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["ai", "agents", "claude", "codex", "gemini", "grok", "multi-agent", "developer-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+dependencies = []
+ 
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0.0",
+    "pytest-xdist>=3.0.0",
+]
+hub = [
+    "nats-py>=2.16.0",
+]
+
+[project.urls]
+Homepage = "https://synlynk.com"
+Repository = "https://github.com/nikhilsoman/synlynk"
+"Bug Tracker" = "https://github.com/nikhilsoman/synlynk/issues"
+Changelog = "https://github.com/nikhilsoman/synlynk/blob/main/CHANGELOG.md"
+
+[project.scripts]
+synlynk = "synlynk:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["synlynk*"]
+
+[tool.setuptools.dynamic]
+version = { file = ["VERSION"] }
+
+[tool.setuptools.package-data]
+synlynk = ["py.typed", "capability_baseline.json", "packs/*.yaml"]

synlynk-0.27.5/setup.cfg

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