Skip to main content
Glama

VINW — Vibe Is Not Wish MCP

Vibe ≠ Wish. A Markdown-first, spiral-ascend workflow engine for strict software engineering process control.

VINW is an MCP server that gives an agent a process it cannot skip: seven layers, explicit baselines, recorded ascents, blocking review gates, and an audit trail a human can read at any time. It also ships a read-only TUI so you can watch the work without reading the chat log.

Contents

Related MCP server: EngiMCP

Design Purpose & Philosophy

The problem

Vibe coding is fast because the conversation is the only state. The conversation also forgets: why a decision was made, which version was approved, what was tried and reverted, and which assumption turned out to be wrong. When a test fails three hours later, the cheapest action is to patch the symptom in the file the agent happens to be looking at — not to ask which layer owns the root cause.

VINW starts from one premise:

When a wrong turn is expensive, the process must be an artifact, not a vibe.

So the process is a directory tree, state transitions are tool calls, the changelog is append-only, and the human is a gate rather than a spectator.

What VINW is

  • A process control plane. Seven layers from requirements to final acceptance, with explicit baselines, recorded ascents, and descent rounds.

  • A Markdown data plane. Requirements, evidence, design, implementation notes, test results, and the final report are plain files you can read, diff, and commit.

  • A tool surface over the same state. 40 MCP tools, a CLI, and a read-only TUI, all looking at the same .vinw/manifest.md.

  • A methodology, not just a server. An optional skill tells the agent which tool to call at each boundary.

  • A gate against self-certification. Independent audit reports, classification of every finding, and blocking checks at the points where a project would otherwise advance.

Principles

  1. The process is the artifact. Every layer produces a document. A baseline freezes the layer's README (its stage contract and summary) into .baseline/vNNN.md; the manifest is the single state machine and the README is its human-facing mirror. A rollback restores the baseline body but keeps the live todo list, so reverting a design never rewinds work progress.

  2. Spiral, not linear. Software engineering needs backtracking. When a test reveals a design flaw, VINW ascends to the layer that owns the root cause, restores its baseline, marks every layer below as superseded — not deleted — and starts a new descent round. The history of why the project went back is first-class data.

  3. Record before you roll back. Every ascent records from_layer, to_layer, to_baseline, reason, and the before/after descent numbers. Every change records intent before the modification. Nothing important is silently overwritten; even force=true leaves a [force] trace in the baseline reason.

  4. Gates over goodwill. "Please remember to check" is not a control. se_can_descend refuses while a blocking confirmation is open; design-review gates default to blocking; L4 cannot be baselined or descended from without a passing consistency state; unresolved audit escalations block the gate. The TUI and se_get_next_steps surface the block instead of letting it disappear into a chat message. (The supported path is to check se_can_descend before descending; like any advisory API, it cannot stop a caller that ignores it.)

  5. Evidence before design. L2 is not a literature-review decoration. It forces references, an evidence matrix, and a synthesis whose conclusions become constraints on L3. "I like this stack" is not an argument; "this stack wins on these weighted criteria, and here is the measurement" is.

  6. An audit proves the absence of drift, not the presence of correctness. The text check is a necessary condition: it verifies that required design symbols exist in code. The LLM audit looks for semantic gaps and demands file:line evidence. Tests are the constructive proof within their coverage. VINW keeps all three and never treats a green text check as proof that the code is right.

  7. Automate the mechanical; escalate the judgment. Triage classifies each finding as impl_bug, design_bug, design_gap, or ambiguous, with a confidence. Only impl_bug + high confidence may be fixed automatically. Design problems and ambiguity go to a human with four fields: difference, analysis, recommendation, and impact.

  8. Different planes need different storage. Project documents are Markdown: human-readable, git-friendly, reviewable. The global project registry is SQLite at $VINW_HOME/registry.db: machine state, concurrent writers, WAL, transactions. Forcing one medium to serve both jobs would weaken both.

  9. Self-hosting is the acceptance test. VINW is built with VINW. vinw-design/ is its own process record: 20 descents, 19 ascents, and 137 audit findings, each triaged through the same reports and gates the tool enforces on its users.

Non-goals

  • Not a code generator. VINW constrains a capable agent; it does not replace one.

  • Not a correctness guarantee. It makes process failures visible and recoverable, not impossible.

  • Not a linter, formatter, or test runner. It gates on their results rather than reimplementing them.

  • Not a cloud service. No account, no telemetry, no network dependency; the data is local files.

  • Not a straightjacket. force exists for real emergencies, but it is recorded as an exception, not hidden.

Self-hosting Record

Statistics snapshot at commit 4ea57ec (2026-11-14 22:34 +08:00; the last code-bearing commit — documentation-only commits after it do not change any number). At this commit the test suite reports 354 passed across 16 files, and the MCP surface exposes 40 tools. Regenerate with python scripts/readme_stats.py.

VINW's own implementation is its longest-running test case. As of this commit, 137 design/code deviations had been intercepted across 12 distinct LLM audits:

Type

Count

Description

Representative example

impl_bug

72

Code contradicts or omits something the approved design already specifies.

ensure() re-anchored the audited fingerprint even when the text re-check failed, so a rejected transition could be retried successfully.

design_gap

35

Code implements real behavior that the design never specified; the design has to catch up.

Drift detection and heal_drift were implemented and sitting in the gate path before L3 had any contract for them.

design_bug

16

The design itself is wrong, internally inconsistent, or contradicts behavior the implementation needs.

The design described two mutually exclusive triage routes: append a triage section to PROMPT v3, or expose a separate se_triage_prompt tool.

ambiguous

7

The design is silent and either reading is defensible; a human must choose the intended behavior.

The execution position of heal_drift (before or after the guards) was undefined; both readings were defensible.

unclassified

7

Reported before the audit contract required a classification field.

Early reviews that predate the triage workflow.

Total

137

—

—

Counting basis. All 137 findings are machine-counted by scripts/readme_stats.py from the twelve distinct LLM audit reports stored in L4-编码实现/consistency-reports/ (identical re-stores of the same content are de-duplicated by content hash). Classification comes from the stored triage verdicts where present, otherwise from the report's own field. Seven early findings predate the classification contract and are counted as unclassified rather than guessed. Rounds are counted separately, so a conceptual issue re-found by a later reviewer can appear twice; this is an audit-record count, not a deduplicated defect count (the same script recomputes it, so the numbers cannot drift silently). Process-only violations and development-time self-checks are excluded.

The full evidence lives in vinw-design/L4-编码实现/consistency-reports/ and the append-only changelog.

Two defects that the audit loop itself had to catch, not the gates: a stale MCP server process (killed and restarted; see the R30 record) and a test-only edit at L6 that the design-lag gate refused. Both are kept in the record rather than smoothed over.

How It Works

The seven layers

Layer

Question it answers

Primary artifacts

L1 需求拆解

What exactly are we building, and how will we know it is done?

proposals.md, todo list

L2 参考文献与方案搜证汇总

What already exists, and why is our choice better for this case?

references.md, evidence-matrix.md, synthesis.md

L3 方案细化

What is the architecture and the exact interface?

design-doc.md, api-design.md

L4 编码实现

Does the code match the approved design?

implementation notes, consistency reports

L5 测试验证

Does it work, and do failures point back to design?

test-plan.md, test-results.md, debug sessions

L6 检视清理

Is the debug scaffolding gone and the docs synced?

cleanup log

L7 终验

Is this deliverable, and what are the known limits?

final-report.md

The spiral

descent-1: L1 → L2 → L3 → L4 → L5
                          ↓ tests reveal a design flaw
    se_ascend(L5, L3, "v001", "API contract mismatch")
                          ↓
descent-2:           L3 (rollback to v001) → L4 → L5
                                  ↓ another issue found
    se_ascend(L5, L2, "v001", "Evidence matrix incomplete")
                          ↓
descent-3:      L2 → L3 → L4 → L5 → L6 → L7

An ascent is not a reset. It records the reason, restores the target layer's baseline, marks the layers below as superseded, and increments the descent counter. The project can therefore show both what was decided and why it was reopened.

Project layout

my-app/
├── .vinw/
│   ├── manifest.md          # Single state machine
│   ├── changelog.md         # Append-only change log
│   ├── ascensions.md        # Ascent history
│   └── decisions.md         # Cross-layer decisions
├── L1-需求拆解/
│   ├── README.md
│   └── proposals.md
├── L2-参考文献与方案搜证汇总/
│   ├── README.md
│   ├── references.md
│   ├── evidence-matrix.md
│   └── synthesis.md
├── L3-方案细化/
│   ├── README.md
│   ├── design-doc.md
│   └── api-design.md
├── L4-编码实现/
│   ├── README.md
│   ├── implementation.md
│   ├── consistency-reports/
│   └── .baseline/
│       └── v001.md
├── L5-测试验证/
│   ├── README.md
│   ├── test-plan.md
│   ├── test-results.md
│   └── debug-sessions/
├── L6-检视清理/
└── L7-终验/

Install & Configure

Requirements

  • Python 3.10+

  • A harness that can launch an MCP server over stdio or Streamable HTTP

  • Linux, macOS, or Windows

Fast path: let your agent install it

Copy the block below into your coding agent (Claude Code, Cursor, Windsurf, DSH, or any agent that can edit its own MCP configuration). Replace the four input values and the <one sentence> description, then send it. The prompt is written so the agent verifies each step and stops on failure instead of claiming success.

Install and configure VINW MCP for this workspace. Work autonomously, verify
every step, and stop with a short report if anything fails.

Inputs — replace these first:
  VINW_REPO = <absolute path to the vibe-is-not-wish-mcp checkout>
  WORK_ROOT = <absolute directory that will hold the project>
  PROJECT   = <project name, use lowercase-kebab-case>
  HARNESS   = <claude-code | claude-desktop | cursor | windsurf | vscode | dsh | other>

Steps:
1. Check prerequisites.
     python3 --version          # must be >= 3.10
     test -d "$VINW_REPO"
   If the checkout is missing, clone the repository there first. Do not guess
   a different path.

2. Install VINW in editable mode, so later git pulls take effect without a
   reinstall.
     cd "$VINW_REPO"
     python3 -m venv .venv
     .venv/bin/python -m pip install -U pip
     .venv/bin/python -m pip install -e .
     .venv/bin/python -c "import vinw; print(vinw.__file__)"
   PASS only if the printed path is inside $VINW_REPO/vinw. If it points at
   site-packages/vinw, the install is a stale copy: rerun the editable install
   and verify again.

3. Create the project. Skip this step if
   "$WORK_ROOT/$PROJECT/.vinw/manifest.md" already exists.
     .venv/bin/vinw init "$WORK_ROOT/$PROJECT" --name "$PROJECT" --desc "<one sentence>"

3.5 **Restart the MCP server after every install.** The DSH-spawned
   `vinw server` is a long-running process: `pip install` only changes
   files on disk, never the modules already loaded in memory. After any
   code change, kill the server process (DSH respawns it on the next tool
   call) or reinstall the plugin bundle. A stale server silently runs old
   gates — see the R30 incident record in vinw-design.

4. Verify registration. `vinw init` registers the project automatically in
   current revisions (pass `--no-register` to opt out). Check:
     .venv/bin/vinw project list
   If the project is missing (older version, `--no-register`, or a registry
   failure), register it manually:
     .venv/bin/vinw project add "$WORK_ROOT/$PROJECT" --name "$PROJECT"

5. Connect the MCP server. Prefer stdio unless the harness cannot launch a
   subprocess.
   stdio endpoint:
     command = $VINW_REPO/.venv/bin/vinw
     args    = ["server"]
     cwd     = $WORK_ROOT/$PROJECT
   Harness-specific wiring:
     - claude-code: from "$WORK_ROOT/$PROJECT", run
         claude mcp add vinw -- "$VINW_REPO/.venv/bin/vinw" server
     - claude-desktop: merge the JSON below into
         "~/Library/Application Support/Claude/claude_desktop_config.json"
         (Windows: %APPDATA%\Claude\claude_desktop_config.json)
     - cursor: merge the JSON below into ~/.cursor/mcp.json
     - windsurf: merge the JSON below into ~/.codeium/windsurf/mcp_config.json
     - vscode: put the same object under the "servers" key in .vscode/mcp.json
     - dsh: create a configuration-only bundle with package.json (dsh.bundle.patch)
         and cordis.patch.yml inserting @deepseek-ai/dsh-mcp-client with
         serverName=vinw, transport=stdio, command, args, cwd; install it with
         plugin_manager. A working example is in .dsh-bundles/vinw-mcp/.
   JSON shape for clients that use mcpServers:
     {
       "mcpServers": {
         "vinw": {
           "command": "$VINW_REPO/.venv/bin/vinw",
           "args": ["server"],
           "cwd": "$WORK_ROOT/$PROJECT"
         }
       }
     }
   If the client ignores "cwd", start it from the project directory, or call
   se_use_project("$PROJECT") once, or pass the "project" argument to tools.

   HTTP alternative, for clients that only accept a URL:
     start "$VINW_REPO/.venv/bin/vinw server --http --port 3000" as a managed
     background process, keep it running, and use
     http://127.0.0.1:3000/mcp. Do not start a second copy on the same port.

6. Verify end to end.
     .venv/bin/vinw status "$WORK_ROOT/$PROJECT"
   Restart or reload the harness if it caches MCP connections, then call:
     se_get_project       -> must return name, current_layer, current_descent
     se_get_next_steps    -> must list the L1 work
   If the tools are missing, inspect the harness MCP log. Do not claim success
   without the two tool results.

7. Report back:
   - repository, venv, and project paths
   - transport used, and the exact config file or command changed
   - output of `vinw project list` and `se_get_project`
   - watch command: $VINW_REPO/.venv/bin/vinw tui "$WORK_ROOT/$PROJECT"
   - the next action the user must take (normally: approve the L1 gate)

Manual install

cd vibe-is-not-wish-mcp

# 1. Editable install in a local venv
python3 -m venv .venv
.venv/bin/python -m pip install -U pip
.venv/bin/python -m pip install -e .        # add ".[dev]" for pytest/ruff

# 2. Create a project — current revisions register it automatically
.venv/bin/vinw init ./projects/my-app --name my-app --desc "My application"
.venv/bin/vinw project list   # verify the project is visible

# 3. Watch it (read-only)
.venv/bin/vinw tui my-app

# 4. Serve it
.venv/bin/vinw server                     # stdio
.venv/bin/vinw server --http --port 3000  # http://127.0.0.1:3000/mcp

Why -e matters: it makes the vinw console script and the vinw Python package come from this checkout. A non-editable copy in site-packages will keep running old code after you pull, which produces the classic "the fix is in the source but the TUI still shows the bug" illusion.

vinw init registers the project automatically in current revisions. On an older revision, or when you pass --no-register, register it explicitly:

.venv/bin/vinw project add ./projects/my-app --name my-app

Register with your harness

stdio is the simplest and works everywhere that can launch a subprocess:

{
  "mcpServers": {
    "vinw": {
      "command": "/absolute/path/to/vibe-is-not-wish-mcp/.venv/bin/vinw",
      "args": ["server"],
      "cwd": "/absolute/path/to/project/my-app"
    }
  }
}

Harness

Where the config goes

Notes

Claude Code

claude mcp add vinw -- /abs/.venv/bin/vinw server

Run from the project directory

Claude Desktop

Settings → Connectors → Add custom connector, or claude_desktop_config.json

JSON shape above

Cursor

~/.cursor/mcp.json

JSON shape above

Windsurf

~/.codeium/windsurf/mcp_config.json

JSON shape above

VS Code Copilot

.vscode/mcp.json

Put the object under "servers"

DeepSeek Harness

configuration-only bundle installed through plugin_manager

See below

Kimi

No native MCP client

Use the Kimi plugin, or a local bridge

Streamable HTTP is convenient when several clients should share one server:

.venv/bin/vinw server --http --port 3000
# Connect at http://127.0.0.1:3000/mcp

For a DeepSeek Harness bundle, the repository contains a working example in .dsh-bundles/vinw-mcp/. Update the absolute paths and install it as a local bundle:

{
  "name": "@local/vinw-mcp",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "files": ["cordis.patch.yml"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}
- insert:
    - id: vinw-mcp
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: vinw
        transport: stdio
        command: /absolute/path/to/.venv/bin/vinw
        args: ["server"]
        cwd: /absolute/path/to/project/my-app
        failOnStartupError: false

Kimi has no native MCP client today. The two practical options are the VINW Kimi plugin in vinw-plugin/ (methodology only) or a small local bridge that exposes the HTTP endpoint in a format Kimi can consume.

Verify

.venv/bin/vinw project list
.venv/bin/vinw status ./projects/my-app

vinw status prints the project name, current descent and layer, pending confirmations, and ascent count. Then ask the agent to call se_get_project; it must return the same project.

Troubleshooting

Symptom

Cause and fix

vinw: command not found

Use .venv/bin/vinw, or activate the venv, or install globally with pipx install .

Import points at site-packages/vinw

Stale non-editable install; reinstall with pip install -e .

New project missing from the TUI selector

Run vinw project list. If absent, register it: vinw project add <path> --name <name>. In current revisions, vinw init and se_init_project register automatically; --no-register / register=false opts out, and a registry failure is reported as a warning

sqlite3.OperationalError: unable to open database file

$VINW_HOME (default ~/.vinw) is not writable, often because the agent runs in a sandbox. Set VINW_HOME to a writable directory

MCP tools do not appear after configuration

Restart or reload the harness; check its MCP log; ensure the command path is absolute and executable

No active project from a tool

se_use_project("<name>"), or pass project="<path-or-name>" to the tool

HTTP server exits immediately

Port already in use; choose another --port

TUI says no project

Press p to open the selector, or start with vinw tui <path|name>

Watching Progress

The same state is visible from three surfaces: the TUI for humans, MCP tools for agents, and the CLI for scripts.

For humans: the TUI

.venv/bin/vinw tui                    # project selector
.venv/bin/vinw tui my-app             # by registered name
.venv/bin/vinw tui ./projects/my-app  # by path

The TUI does not modify project documents or workflow state. It polls the project files every 2 seconds, so it can stay open in a second terminal while an agent works. It never blocks the agent; the only write it makes is the registry's last-accessed timestamp when you switch projects. If a file is caught mid-write, it keeps the last good render and shows the error instead of crashing.

Keys

Key

Action

p

Open the project selector

↑ / ↓ + Enter

Choose a project (in the selector)

Esc

Cancel the selector

r

Force an immediate refresh

q

Quit

The three panels

  1. Top — layer graph. Current descent and layer, each layer's state and latest baseline, ascent arrows with their reasons, L4 consistency and drift badges, and a drift warning panel when code and design disagree.

  2. Middle — todos and gates. Open todo items across layers, split into 🔒 blocking (blocks the supported advance path) and 🔓 review-only (does not block it), with counts.

  3. Bottom — state and recent changes. Whether the project can descend, the recommended next call, contextual hints, and the last three changelog entries.

Layer legend

Mark

Meaning

◆

Current layer, when it is already baselined (bold cyan)

▶

In progress (bold yellow when it is the current layer)

✅

Baselined

↻

Superseded — needs redo in this descent

🏁

Completed (L7 only)

○

Pending / never started

dim green

A passed baseline or completed layer that is not current

L4 audit badges

Badge

Meaning

chk✓

Text consistency passed

chk!

Text consistency found inconsistencies

chk⚙

Consistency check could not run (configuration error)

⚠冲突

Text and LLM verdicts conflict; likely an extractor defect

·待审

An LLM verdict is required but missing

/llm✓

LLM verdict passed

Drift badges

Badge

Meaning

⚠漂移

Code changed after the approved design

🚫设计滞后

Code moved ahead of the design; update L3 first

⚠需重审

Design changed; the previous audit no longer applies

⚠漂移未知

The fingerprint is unavailable; do not treat as clean

What to watch while an agent works

  • Current layer / descent changed? That is a baseline, descend, or ascend event. Check the bottom panel for the reason.

  • A 🔒 gate appeared? se_can_descend will refuse until a human decides. The TUI cannot approve it; tell the agent your decision so it can call se_resolve_confirmation.

  • 🚫设计滞后 or chk!? Do not let the agent push on. It must fix the implementation or ascend to L3.

  • Todos moving? The middle panel is the cheapest progress indicator.

  • Changelog tail? The bottom panel shows the last three entries; the full append-only log is in .vinw/changelog.md.

For agents: MCP tools and CLI

Agents should treat the MCP tools as the API and the TUI as a read-only monitor. The source of truth is <project>/.vinw/manifest.md.

Question

Call

What is the full state?

se_get_project — layer graph, ascents, blocking gates, review items, consistency, drift

What should I do next?

se_get_next_steps — work list, gate, next transition, special instruction

What is left?

se_get_todos — todos across non-superseded layers

What changed recently?

se_get_changelog(limit=...)

Can I descend?

se_can_descend

What baselines exist?

se_list_baselines(layer=...)

What documents exist?

se_list_documents(layer=...)

Does a human need to decide?

se_get_escalations, se_triage_prompt

Which projects are known?

se_list_projects, se_use_project, or the project= argument

Startup resolution. vinw server auto-loads a project from cwd/vinw-design/.vinw/manifest.md or cwd/.vinw/manifest.md. If neither exists, call se_use_project("<name-or-path>") once or pass project="<name-or-path>" to individual tools.

A practical polling discipline

Start of a session or after a layer switch:
  se_get_project

Before choosing an action:
  se_get_next_steps

While working:
  se_get_todos
  se_get_changelog(limit=5)

Before baseline or descend:
  se_can_descend
  se_get_project          # read consistency and drift

When audit findings appear:
  se_get_escalations
  se_triage_prompt

After a change:
  se_get_changelog        # confirm the write was recorded

At the end of a layer:
  se_get_project          # verify status and baseline

Do not poll in a tight loop. Call these at state boundaries; the TUI already provides continuous observation for the human.

Shell-level checks work too, and are useful in CI or when the agent cannot reach MCP tools:

.venv/bin/vinw status ./projects/my-app
.venv/bin/vinw project list
.venv/bin/vinw project history my-app

Ask your agent for a progress report. A reliable prompt is:

Report VINW progress for this project. Use se_get_project and
se_get_next_steps. Give me: current layer and descent, all blocking gates,
open todos, consistency and drift status, and the single next action. If a
human decision is pending, quote the gate id and the exact decision you need.

Watching together

The TUI and MCP tools are designed to run at the same time:

  • The TUI reads project state; MCP tools write it. The TUI cannot corrupt the workflow.

  • The TUI refreshes every 2 seconds, so it usually shows a new state before the agent's summary arrives.

  • The agent sees the same facts through se_get_project, so the human and the agent cannot tell two different stories about the same layer.

  • If the TUI and the agent disagree, manifest.md wins. Ask the agent to read it directly.

MCP Tools

40 tools, grouped by job. Every project-scoped tool accepts an optional project argument (path or registered name); when omitted, the active project is used. Registry tools operate on the registry itself.

Area

Tools

Project lifecycle

se_init_project, se_get_project, se_complete_project

Registry

se_register_project, se_list_projects, se_use_project, se_remove_project, se_set_project_state, se_project_history, se_export_projects, se_prune_projects

Documents & baselines

se_store_document, se_read_document, se_list_documents, se_list_baselines

Workflow

se_baseline, se_ascend, se_descend, se_can_descend

Gates

se_require_confirmation, se_resolve_confirmation, se_purge_confirmations

Change log

se_log_change, se_get_changelog

Todos & guidance

se_get_todos, se_update_todo, se_get_next_steps

Audit & triage

se_check_consistency, se_store_consistency_report, se_triage_prompt, se_store_triage, se_get_escalations, se_record_triage_decision

Repair

se_repair_state, se_sync_layer_readmes

Search

se_search_proposals

The authoritative tool contracts live in vinw-design/L3-方案细化/api-design.md. The design catalog is generated from vinw/server.py and checked by a test, so the published list and the implementation cannot silently diverge.

Citation & Reference Format

Citing VINW

If you use VINW in academic work, a report, or another project, cite the software and, when the claim depends on a specific state, pin the commit.

Plain text

M0reDr1nk. VINW: Vibe Is Not Wish MCP (Version 0.2.0) [Computer software].
2026. https://github.com/M0reDr1nk/vibe-is-not-wish-mcp

BibTeX

@software{vinw2026,
  author       = {M0reDr1nk},
  title        = {{VINW}: Vibe Is Not Wish MCP},
  year         = {2026},
  version      = {0.2.0},
  url          = {https://github.com/M0reDr1nk/vibe-is-not-wish-mcp},
  note         = {Markdown-first, spiral-ascend workflow engine for strict
                  software engineering process control}
}

Pinning a commit. For reproducible claims, cite a commit-pinned URL instead of main:

https://github.com/M0reDr1nk/vibe-is-not-wish-mcp/tree/<commit-sha>

For example, the self-hosting statistics in this README were compiled at 830a5c2; cite that commit if you are reproducing the table. State the commit you actually inspected, not the newest one by default.

Referencing the audit trail

VINW's records use stable, short identifiers. They are designed to be quoted in issues, reviews, and papers without ambiguity.

Kind

Format

Scope

Example

Commit

7-character short SHA

Repository

830a5c2

Baseline

vNNN

Layer

L4-编码实现/v013

Ascent

asc-NNN

Project

asc-013

Change

chg-YYYYMMDD-HHMMSS-NNN

Project

chg-20261114-030842-147

Confirmation

cfm-YYYYMMDD-HHMMSS-NNN

Project

cfm-20261113-153121-001

Consistency report

report-<id>[-NN].md

Project

report-954217cd

Finding

INC-NNN / GAP-NNN

Report-local

report-954217cd/INC-001

Design or code location

file:line or file:start-end

Repository

api-design.md:610-612

Layer document

<layer>/<filename>

Project

L3-方案细化/api-design.md

Two rules matter when citing findings:

  1. Finding IDs are report-local. INC-001 exists in several reports with different meanings; for example, report-7474b697/INC-001 and report-954217cd/INC-001 are different defects. Always qualify it with the report: report-954217cd/INC-001, not INC-001.

  2. Report IDs are usually content-derived. Most are hashes of the report content; a -NN suffix marks a re-check or a second part. Some early reports use a descriptive ID such as report-L4-r1-text.md. Cite the filename as stored under L4-编码实现/consistency-reports/.

For a review comment, the full form is:

report-954217cd/INC-001 (impl_bug, confidence=high)

Referencing literature in L2

L2 uses three prefixes so that a claim can be traced to its kind of source:

Prefix

Use for

Example

ref-NNN

Academic papers, standards, official documentation

ref-001

oss-NNN

Open-source projects, products, existing implementations

oss-001

internal-NNN

Internal or historical projects used as evidence (same pattern as ref-/oss-)

internal-001

Each entry lives in L2-参考文献与方案搜证汇总/references.md with its title, source/link, key conclusion, and relevance. The evidence matrix and synthesis should cite the ID (ref-001), not repeat a bare URL; this keeps the evidence chain stable when a link moves.

  • Use relative paths for files in this repository.

  • Use commit permalinks for evidence that must remain stable: https://github.com/M0reDr1nk/vibe-is-not-wish-mcp/blob/<commit-sha>/<path>#Lx-Ly.

  • Do not cite a moving branch when the claim depends on a specific line; pin the commit and the line range.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for structured document management of markdown and YAML files, with RBAC, git-based approval workflows, and semantic search, enabling agents to read, edit, and maintain documents under governance.
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that gives LLM agents structured, safe, and traceable access to engineering project documentation stored in Markdown/Git repositories, enabling management of requirements, decisions, tests, tasks, and impact analysis.
      14
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Repository-native protocol and MCP server for coordinating work items, documentation, changelogs, and project memory between humans and AI agents, using Markdown files in a Git repository as the canonical data source.
      30
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI coding agents and hosts to enforce deterministic repository boundaries via MCP, providing structured reads, supervised edits, snapshots, audits, and recovery with machine-readable evidence.
      MIT