visionlog-md 0.2.0__tar.gz

visionlog_md-0.2.0/.forge/manifest.yaml

@@ -0,0 +1,42 @@
+manifest_version: 1
+
+repo:
+  visibility: public
+  org: eidos-agi
+  topics: [mcp, vision, governance, guardrails, agent-tools]
+
+packaging:
+  build_system: hatchling
+  pypi:
+    name: visionlog-md
+    publish: true
+    trusted_publisher:
+      owner: eidos-agi
+      repo: visionlog.md
+      workflow: publish.yml
+      environment: pypi
+  readme:
+    absolute_images: true
+
+quality:
+  required_files:
+    - LICENSE
+    - README.md
+    - CHANGELOG.md
+    - CONTRIBUTING.md
+    - SECURITY.md
+  min_grade:
+    foss_check: B
+    ship_check: pass
+    sec_audit: clean
+
+dependencies:
+  max_count: 3
+
+ci:
+  workflows:
+    ci: true
+    publish: true
+  permissions:
+    contents_read: true
+  pre_commit: true

visionlog_md-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Lint
+        run: |
+          pip install ruff
+          ruff check visionlog_md/
+          ruff format --check visionlog_md/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run fixture verification
+        run: python refactor/verify-fixtures.py || true
+      - name: Run tests
+        run: pytest tests/ -v || echo "No pytest tests yet"
+
+  build-verify:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          pip install build twine
+          python -m build
+      - name: Verify metadata
+        run: twine check dist/*
+      - name: Verify wheel installs
+        run: |
+          python -m venv /tmp/test-venv
+          /tmp/test-venv/bin/pip install dist/*.whl
+          /tmp/test-venv/bin/python -c "import visionlog_md; print(visionlog_md.__version__)"

visionlog_md-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

visionlog_md-0.2.0/.gitignore

@@ -0,0 +1,38 @@
+# Node (TypeScript original)
+node_modules/
+dist/
+*.js.map
+*.tsbuildinfo
+*.db
+
+# Python (new primary)
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+build/
+*.egg
+*.whl
+
+.venv/
+venv/
+env/
+.env
+.env.local
+
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+.DS_Store
+Thumbs.db
+
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+.mcp.json

visionlog_md-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.0
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      - id: detect-private-key
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.3.0
+    hooks:
+      - id: codespell
+        args: [--skip, "*.lock,*.cast"]

visionlog_md-0.2.0/.visionlog/adr/ADR-001-the-trilogy-must-remain-composable-and-non-prescri.md

@@ -0,0 +1,29 @@
+---
+id: "ADR-001"
+type: "decision"
+title: "The trilogy must remain composable and non-prescriptive"
+status: "accepted"
+date: "2026-03-21"
+---
+
+## Context
+
+During a design session, an AI suggested adding an "Initiative" layer — a cross-cutting concept that would unify artifacts from all three trilogy tools under a single ID and lifecycle. The idea had genuine merit for observability and auditability.
+
+The user's response: "we should be careful about becoming too opinionated."
+
+This was not feedback on one feature. It was a design principle. The moment passed without being captured — which is itself the gap the trilogy exists to close.
+
+## Decision
+
+The trilogy tools (research.md, visionlog, ike.md) must remain composable and non-prescriptive. Each tool has one job. No tool should impose a cross-cutting methodology on top of the primitives it provides.
+
+Workflow conventions — like linking all artifacts under an initiative ID — belong in SOPs, not in schemas. A SOP recommends. A schema enforces. Enforcement should be reserved for things that are always true, not things that are useful in some contexts.
+
+The test for any proposed new construct: **does it make the existing job of the tool clearer, or does it add a new job?** If it adds a new job, it belongs in a SOP or in a separate tool.
+
+## Consequences
+
+- Feature proposals that add new cross-cutting abstractions must clear this bar before acceptance
+- Linking conventions (e.g., initiative_id) should be documented as optional SOP guidance, not schema requirements
+- The trilogy's value is in its simplicity — three focused tools with clear seams, not a framework

visionlog_md-0.2.0/.visionlog/config.yaml

@@ -0,0 +1,3 @@
+id: "80587952-9c97-401b-acdd-3d7378d7b6c7"
+project: "visionlog.md"
+created: "2026-03-21"

visionlog_md-0.2.0/.visionlog/guardrails/GUARD-001-no-new-cross-cutting-abstractions-without-clearing.md

@@ -0,0 +1,28 @@
+---
+id: "GUARD-001"
+type: "guardrail"
+title: "No new cross-cutting abstractions without clearing the composability test"
+status: "active"
+date: "2026-03-21"
+adr: "ADR-001"
+---
+
+## Rule
+
+Before adding any new construct to visionlog, research.md, or ike.md schemas, apply this test:
+
+**Does this make the existing job of the tool clearer, or does it add a new job?**
+
+If it adds a new job — stop. Either (a) put the convention in a SOP, (b) build it as a separate optional tool, or (c) run it through research.md to earn the decision before touching a schema.
+
+## Why
+
+The trilogy's strength is focused simplicity. Cross-cutting abstractions feel like improvements but are often methodology prescriptions in disguise. Once in a schema, they are enforced on every user. Once enforced, they are hard to remove. The cost compounds.
+
+This guardrail exists because in a live design session, an AI proposed an "Initiative" layer with genuine merit — and the principle it violated had never been written down. An unwritten principle cannot be enforced.
+
+## Violation Examples
+
+- Adding `initiative_id` as a field on ike.md tasks, visionlog goals, and research.md projects — prescribes a cross-cutting workflow not everyone needs
+- Adding a `risk_level` field to guardrails "because it would be useful" — adds a new classification job to what is already a clear construct
+- Adding a `confidence_score` to ADRs — imports a research.md concept into visionlog's domain

visionlog_md-0.2.0/.visionlog/sops/SOP-001-goal-decomposition.md

@@ -0,0 +1,36 @@
+---
+id: "SOP-001"
+type: "sop"
+title: "Goal Decomposition"
+status: "active"
+date: "2026-03-21"
+---
+
+## When to use this
+
+When a visionlog goal has no ike.md tasks yet, or when starting work on a goal that is `available` or `in-progress`. Do not create tasks without first consulting this SOP.
+
+## Steps
+
+1. **Read the goal** — call `visionlog.goal_view(id)`. Understand the exit criteria, dependencies, and what "complete" means.
+
+2. **Check guardrails** — call `visionlog.guardrail_list(status: active)`. Identify any guardrails that constrain how this goal is executed. If a proposed approach would violate one, stop and redesign before proceeding.
+
+3. **Propose milestones** — decompose the goal into 1–3 milestones. A milestone is a meaningful, demonstrable checkpoint — not a task list. Ask: what intermediate states of the world would prove we are on track?
+
+4. **Create milestones in ike.md** — call `ike.milestone_create` for each milestone. Name them after the outcome, not the activity.
+
+5. **Decompose each milestone into tasks** — for each milestone, identify the atomic work items. A task should be completable in one session. Call `ike.task_create` for each with:
+   - `visionlog_goal_id` set to the goal's ID
+   - `milestone` set to the milestone ID
+   - `priority` reflecting urgency
+   - `acceptance_criteria` defining what done looks like
+
+6. **Update goal status** — if the goal was `locked`, check whether its `depends_on` goals are complete. If yes, call `visionlog.goal_update(status: available)`. If you are starting work now, set `in-progress`.
+
+## Guards
+
+- Never create tasks without reading the goal and active guardrails first
+- A goal should have no more than 3 milestones unless the scope demands it — if it does, the goal is probably too large and should be split
+- Every task must have `acceptance_criteria` — a task without a definition of done will never be verifiably complete
+- Do not skip directly from goal to tasks — the milestone layer is what connects strategy to execution

visionlog_md-0.2.0/.visionlog/sops/SOP-002-completion-feedback.md

@@ -0,0 +1,32 @@
+---
+id: "SOP-002"
+type: "sop"
+title: "Completion Feedback"
+status: "active"
+date: "2026-03-21"
+---
+
+## When to use this
+
+After completing an ike.md task. Completion is not just marking a task done — it is closing the loop back to the goal. Follow this SOP every time.
+
+## Steps
+
+1. **Complete the task** — call `ike.task_complete(task_id)`. Record completion notes describing what was done and any decisions made during execution.
+
+2. **Check the milestone** — call `ike.task_list(milestone: <milestone_id>)`. If all tasks in the milestone are complete, call `ike.milestone_close(milestone_id)`.
+
+3. **Check the goal** — if a milestone was closed, call `ike.task_list(visionlog_goal_id: <goal_id>, include_completed: false)`. If no open tasks remain for this goal:
+   - Call `visionlog.goal_view(id)` — review exit criteria
+   - If exit criteria are met, call `visionlog.goal_update(id, status: complete)`
+   - If exit criteria are not fully met, create the remaining tasks before updating status
+
+4. **Capture decisions made** — if any non-obvious decisions were made during execution that aren't recorded anywhere, call `visionlog.decision_create` with `status: accepted` to formalize them. A decision made in execution but not recorded is a contract that was never written.
+
+5. **Check unlocks** — call `visionlog.goal_unlockable()`. If completing this goal unlocks others, update their status to `available`.
+
+## Guards
+
+- Never mark a goal complete without checking its exit criteria in visionlog
+- If you made a decision during execution, write the ADR — do not leave it in task notes
+- Do not skip step 5 — unlocking goals is how the DAG advances

visionlog_md-0.2.0/.visionlog/sops/SOP-003-blocked-task-escalation.md

@@ -0,0 +1,37 @@
+---
+id: "SOP-003"
+type: "sop"
+title: "Blocked Task Escalation"
+status: "active"
+date: "2026-03-21"
+---
+
+## When to use this
+
+When an ike.md task cannot proceed. A blocked task is a signal that the plan is misaligned with reality. Do not leave it blocked without diagnosing why and taking explicit action.
+
+## Steps
+
+1. **Record the blockage** — call `ike.task_edit(task_id, status: "In Progress")` and add a note with the reason. Name the reason precisely. Vague blocked reasons ("can't proceed") are not acceptable.
+
+2. **Diagnose the type** — determine which category applies:
+
+   **A. Dependency** — another task or goal must complete first.
+   Action: verify the dependency in ike.md or visionlog. Update `dependencies` on the task if not already set. Wait or switch to unblocked work.
+
+   **B. Information gap** — the task cannot be completed because knowledge is missing.
+   Action: open a research.md project to find the answer. Call `research.project_init` with a clear question. Update the blocked task's notes with the research project ID. Return to this task when the research project is decided.
+
+   **C. Contradiction** — the task conflicts with a visionlog guardrail or ADR.
+   Action: this is a serious escalation. The task as written is invalid. Either (a) redesign the task to comply, or (b) if the contract itself is wrong, open a research.md project to earn a new decision that supersedes the existing ADR. Do not proceed with a task that violates a guardrail.
+
+   **D. Resource or access constraint** — the agent lacks a tool, permission, or capability.
+   Action: create a high-priority task assigned to a human (`assignees: ["human"]`) describing the missing capability. The original task remains blocked until the human task is resolved.
+
+3. **Never leave a task blocked without a linked action** — every blocked task must have either a dependency link, a research project ID in its notes, a redesigned scope, or a human-assigned task waiting for it.
+
+## Guards
+
+- A blocked task with no diagnosis is invisible debt — it will sit in the backlog forever
+- Do not spawn a research.md project for questions that can be answered by reading existing visionlog ADRs or SOPs first
+- A contradiction with a guardrail is never a blocker to work around — it is a signal to stop and govern

visionlog_md-0.2.0/.visionlog/vision.md

@@ -0,0 +1,41 @@
+---
+title: "visionlog.md — The Governance Layer"
+type: "vision"
+date: "2026-03-21"
+---
+
+visionlog is the governance layer for AI-assisted projects. It holds the contracts that all execution must honor: vision, goals, guardrails, SOPs, and ADRs.
+
+## What it is
+
+A place for decisions that have been earned, goals that have been committed to, and rules that must not be broken. It is the static layer — the part of the system that changes slowly and deliberately, because governance that changes fast is not governance.
+
+## What it is not
+
+visionlog is not an orchestrator. It does not run agents, schedule work, or manage tasks. It does not tell you how to work — only what you have committed to and what you must not do.
+
+## Design philosophy
+
+**Composable, not prescriptive.**
+
+visionlog gives you primitives — goals, guardrails, SOPs, ADRs — and stays out of the way. It does not impose a methodology. It does not require you to use all of its constructs. It does not add cross-cutting concepts that prescribe how you organize work at a level above the tools.
+
+The right test for any new feature: does it make the existing job of the tool clearer, or does it add a new job? New jobs belong elsewhere.
+
+**Opinions go in SOPs, not in schemas.**
+
+If a workflow pattern is valuable — like linking execution back to a research decision — that belongs in a SOP that recommends a convention. It does not belong in a required schema field that forces the convention on everyone.
+
+**Contracts must be earned.**
+
+No guardrail, ADR, or SOP should be created without a reason. The reason must be recorded. A contract without a recorded rationale is noise, not governance.
+
+## The trilogy
+
+visionlog is the middle layer of a three-tool trilogy:
+
+- **research.md** — earn decisions with evidence before committing
+- **visionlog** — record what was decided and what must not be violated
+- **ike.md** — execute within those contracts
+
+The flow is one-way by design: research feeds visionlog, visionlog feeds ike. Each tool has one job. None of them reach into the others' domain.

visionlog_md-0.2.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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.1.0] - 2026-03-22
+
+### Added
+- Initial release

visionlog_md-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to visionlog
+
+Thanks for your interest in contributing.
+
+## Quick start
+
+```bash
+git clone https://github.com/eidos-agi/visionlog.md.git
+cd visionlog.md
+pip install -e ".[dev]"
+```
+
+## Development
+
+We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```bash
+ruff check .
+ruff format .
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+## For agent developers
+
+If you're building tools that AI agents will use, pay special attention to:
+
+1. **Tool descriptions** — Every `@tool` decorator must have a description that explains *when* to use it, not just *what* it does. An agent choosing between 20 tools needs clear differentiation.
+2. **Parameter descriptions** — Every parameter needs a `description` field. Agents don't have UI tooltips — the description is all they get.
+3. **Error messages** — When something fails, the error message must tell the agent what to do next. "Invalid input" is useless. "Expected ISO 8601 date string (e.g., 2026-03-22), got: 'yesterday'" is actionable.
+4. **Typed everything** — Type hints on all public functions. Agents parse types to understand contracts.
+
+## Pull requests
+
+- Keep PRs focused — one feature or fix per PR
+- Include tests for new functionality
+- Update CHANGELOG.md with your changes
+- Ensure `ruff check .` and `pytest` pass
+
+## Reporting issues
+
+Open an issue with:
+
+1. What you were trying to do
+2. What happened instead
+3. Steps to reproduce

visionlog_md-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daniel Shanklin
+
+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.

visionlog_md-0.2.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: visionlog-md
+Version: 0.2.0
+Summary: The static St. Peter — vision, goals, guardrails, SOPs, ADRs for AI agent governance
+Project-URL: Homepage, https://github.com/eidos-agi/visionlog.md
+Project-URL: Repository, https://github.com/eidos-agi/visionlog.md
+Author-email: Daniel Shanklin <daniel@eidosagi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-tools,governance,guardrails,mcp,vision
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# visionlog.md
+
+MCP server for long-term project governance. Records vision, goals, guardrails, SOPs, and architectural decisions (ADRs) — the contracts that all execution must honor.
+
+Part of the trilogy: **research.md → visionlog.md → ike.md**
+
+- research.md earns decisions with evidence
+- **visionlog.md** records them as binding contracts
+- ike.md executes within those contracts
+
+## What it enforces
+
+- Guardrails are active or deprecated — never deleted
+- ADRs are permanent once accepted — a new ADR supersedes, never overwrites
+- Goals form a DAG — dependencies must be resolved before a goal is available
+- Vision is sticky — it does not drift session to session
+
+## Trilogy conventions
+
+visionlog.md follows shared conventions with ike.md and research.md. See [CONVENTIONS.md](https://github.com/eidos-agi/ike.md/blob/main/CONVENTIONS.md) for the full standard.
+
+- Config lives at `.visionlog/config.yaml` (committed to git)
+- Tools: `project_init` (new project) and `project_set` (register existing for session)
+
+## Install
+
+Not yet published to npm. Install from local path.
+
+```bash
+npm install
+npm run build
+```
+
+Add to `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "visionlog": {
+      "command": "/absolute/path/to/visionlog.md/dist/visionlog",
+      "args": ["mcp", "start"]
+    }
+  }
+}
+```
+
+## Session protocol
+
+```
+project_set { path: "/path/to/project" }   <- returns project_id
+visionlog_boot { project_id: "..." }        <- active guardrails + goal state
+visionlog_guide { project_id: "..." }       <- vision + decisions + goal map
+```
+
+Read both `visionlog_boot` and `visionlog_guide` at the start of every session before touching any task or code.
+
+## Project structure
+
+```
+my-project/
+  .visionlog/
+    config.yaml          <- project GUID + metadata (commit this)
+    vision.md            <- north star, anti-goals, success criteria
+    goals/               <- GOAL-NNNN.md — DAG of milestones
+    adr/                 <- ADR-NNNN.md — architectural decisions
+    guardrails/          <- GUARD-NNNN.md — active constraints
+    sops/                <- SOP-NNNN.md — coordination protocols
+```
+
+## Tools
+
+### Session
+| Tool | Description |
+|------|-------------|
+| `project_init` | Initialize visionlog in a new project |
+| `project_set` | Register existing project for session, returns project_id |
+
+### Orientation (call at session start)
+| Tool | Description |
+|------|-------------|
+| `visionlog_boot` | Active guardrails + current goal state + backlog check |
+| `visionlog_guide` | Vision + key decisions + full goal map |
+| `visionlog_status` | Counts: goals, decisions, guardrails, SOPs |
+
+### Vision
+| Tool | Description |
+|------|-------------|
+| `vision_view` | Read the project vision |
+| `vision_set` | Set or update the vision document |
+
+### Goals
+| Tool | Description |
+|------|-------------|
+| `goal_create` | Add a goal to the DAG |
+| `goal_list` | List all goals with status |
+| `goal_view` | Read a goal |
+| `goal_update` | Update goal status or body |
+| `goal_unlockable` | List goals whose dependencies are met |
+
+### Decisions (ADRs)
+| Tool | Description |
+|------|-------------|
+| `decision_create` | Record an architectural decision |
+| `decision_list` | List all ADRs |
+| `decision_view` | Read an ADR |
+| `decision_update` | Update status or body |
+
+### Guardrails
+| Tool | Description |
+|------|-------------|
+| `guardrail_create` | Add a guardrail |
+| `guardrail_list` | List all guardrails |
+| `guardrail_view` | Read a guardrail |
+| `guardrail_update` | Update status or body |
+| `guardrail_inject` | Inject guardrails into an existing prompt |
+
+### SOPs
+| Tool | Description |
+|------|-------------|
+| `sop_create` | Add a standard operating procedure |
+| `sop_list` | List all SOPs |
+| `sop_view` | Read a SOP |
+| `sop_update` | Update status or body |