Vinculivo

Verified Project Context & Decision Intelligence

Decisions with provenance. Change signals with evidence. Context your agents can actually use.

ArmoTuSitio · VS Code / ArmoTuSitio IDE · TypeScript · Local-first

[!IMPORTANT] v0.2.1 — Preview. This is a public Preview extension; marketplace availability is verified through the registries, not assumed from repository visibility. The release workflow reuses the exact three-platform-verified PR VSIX and publishes through OIDC after a qualifying merge. Real IDE UX acceptance remains a separate requirement. See release and recovery guide.

Why Vinculivo exists

Every engineering project accumulates architectural decisions, agent instructions, constraints, verification evidence and hidden knowledge. AI coding tools often start sessions without the context needed to respect those agreements. Vinculivo brings that context into the editor, linked to its evidence, without sending your repository to an external service.

Vinculivo is not another chatbot. It is a project-context and decision governance extension supporting a full workflow: discover → register → link → verify → detect changes → preflight → handoff.

Identidad de marca / Brand identity

El logo aprobado es la fuente de verdad: anillo circular, tres nodos exteriores, nodo central y conexiones en cian/violeta. No se cambió el símbolo; las adaptaciones conservan su geometría. El icono de Activity Bar utiliza una variante monocromática con currentColor.

• Manual de identidad, uso de logo y guía UX/UI
• Moodboard en SVG editable · PNG de alta resolución
• Inventario de assets y procedencia · Design tokens CSS

Nota: el panel ilustrado dentro del moodboard es una propuesta de dirección visual. Las futuras capturas funcionales deben proceder del Extension Host real, no de renders o mockups.

What works in this Preview candidate

UI and brand

The top brand icon and media/brand/vinculivo-activity-bar.svg share the same actual geometry: thin circular boundary, three outer nodes, a central fourth node and a triangular set of links. The Activity Bar is monochrome (currentColor), following VS Code theme conventions. The Control Center opens in the main editor, not in a compressed sidebar. Clicking Vinculivo's Activity Bar icon now opens or focuses this editor immediately; the temporary launcher sidebar closes automatically. The Command Palette command remains available as a fallback.

Screenshots — actual Control Center renderer

The four screenshots below are captured from Vinculivo’s actual src/ui.ts Webview implementation, rendered in headless Chromium with a deterministic, synthetic example workspace. They show implemented UI, not the conceptual brand moodboard. They are not screenshots of an installed VS Code / ArmoTuSitio IDE Extension Host, whose native visual acceptance remains pending. No private project data was used.

1. Overview — project intelligence

Documents indexed, linked source sections, decisions and signals requiring review, with file-and-line source navigation.

2. Decisions — human-confirmed knowledge

Decision lifecycle (proposed, accepted, superseded and deprecated), change warnings, linked files and the decision editor.

3. Preflight and agent handoff

Task-specific context selection, target agent, approximate token budget, review warnings and a source-referenced Markdown preview.

4. Evidence registry

Imported evidence summaries, their providers and provenance; reports remain unverified until checked against their original sources.

Reproducibility: scripts/readme-fixture.cjs contains only synthetic records. Build the extension (npm run build), then run scripts/capture-readme-screenshots.py with Python Playwright and Chromium (VINCULIVO_CHROMIUM may specify the executable). The script captures the same Webview HTML renderer shipped by the extension and checks for runtime JavaScript errors. Genuine VS Code / ArmoTuSitio IDE Extension Host screenshots are still part of the Preview acceptance checklist.

Quick start — Preview validation

1. Open the PR and its green GitHub Actions run.
2. Download the vinculivo-private-vsix artifact, unzip it and verify the .vsix.sha256 checksum.
3. In ArmoTuSitio IDE or VS Code: Extensions → … → Install from VSIX…. Select vinculivo.vsix and reload the window.
4. Open a project in a trusted workspace and click the Vinculivo Activity Bar icon. The actual Control Center opens in the editor area.
5. Click Scan sources. Explore the documented sections and open a source line.
6. Open Decisions, create a proposal, link it to src/... or folder/**, then explicitly Review & accept after checking the code.
7. Change a linked file, rescan and check the review suggested signal. Open Preflight & handoff to create a task-specific briefing with the new warning.
8. Preview the Markdown and use Copy approved handoff (copy means user-approved export, not proof that decisions are correct). Paste where needed.

Installation from source

Requires Node.js 22+, npm and VS Code API ^1.96.0.

git clone https://github.com/Drako01/vinculivo.git
cd vinculivo
npm ci --ignore-scripts --no-audit --no-fund
npm run verify
npm run package:vsix

The repository is public. npm run package:vsix creates a candidate locally; it never publishes a release. The generated CI artifact is a validation candidate, not proof of Marketplace/Open VSX publication.

Decisions: what is reviewed, what is merely detected?

Vinculivo distinguishes workflow state and evidence state:

• Proposed: a developer entered or imported the decision; it is not accepted.
• Accepted: a developer explicitly acknowledged reviewing the sources and affected paths. This is not a formal correctness proof.
• Review suggested: a referenced document or linked file appears changed, or a Git diff touches a linked directory. Human confirmation is needed.
• Unknown: no reliable review baseline exists, or Git/linked evidence is unavailable.
• Superseded / deprecated: historic decisions remain visible but do not control new task preflights.

A clean signal means only no relevant changes were detected within the checked scope. It never means the decision is universally correct. Individual files are fingerprinted on review. Directory patterns such as src/auth/** are monitored through Git diffs from that SHA; a missing Git repository limits those signals.

Preflight and token economy

The selected task is used to score titles, source paths, excerpts and decisions without calling a model. Handoffs include:

1. The selected task and Git HEAD.
2. Review warnings, not hidden behind a "green" summary.
3. User-reviewed decision summaries, rationale and related paths.
4. Relevant sourced Markdown excerpts with file, line and digest.
5. Explicitly imported third-party evidence, labeled unverified.
6. Instructions to verify code and avoid repeating tests on unchanged code.

A maximum-size budget is enforced using UTF-8 bytes divided by four as an approximation of token count; this is not exact for any proprietary tokenizer. The preview is generated locally. Clipboard export requires a user action.

Evidence integration

Generic JSON reports can be imported manually; direct extension-to-extension adapters require the respective extension to register a compatible evidence provider. This design avoids undocumented coupling to the release internals of Probato PR, Indizivo, Orquestivo, Saturivo, Noditrivo and Vestigivo RCA.

Example file:

{
  "schema": "vinculivo-evidence-v1",
  "provider": "Orquestivo",
  "title": "PR [#127](https://github.com/Drako01/vinculivo/issues/127) checks",
  "summary": "Validated unit and CI checks against the referenced commit",
  "sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Read the evidence adapter contract. Source references and imported claims must be independently reviewed.

Workspace, privacy and security

Vinculivo makes no automatic external API request, sends no telemetry, and does not run or control AI agents. No automatic Git writes or shell scripts are executed. Repository scanning is explicit and requires Workspace Trust. Local Git reads use execFile without a shell and a timeout; git is optional. Path traversal and local symlink escapes are rejected.

• Indexed excerpts remain in extension memory; workspace-state storage retains documentation fingerprints, user-entered decisions and imported summaries.
• Exporting bundles writes a file only at the user-selected destination. Imported decisions must be re-reviewed.
• Clipboard content may be readable by other applications. Review it before pasting into external assistants. Heuristic credential redaction is not a DLP system.
• Documentation contents are untrusted. Handoffs explicitly warn destination agents not to follow embedded instructions as higher-priority commands.
• A vscode-remote provider may be indexed through the VS Code FS API; local Git comparisons are unavailable there, so baselines become unknown instead of green.

Full disclosures and responsible reporting: SECURITY.md.

Architecture

src/
  core.ts          Bounded Markdown parser, source fingerprints, context selection
  intelligence.ts  Decision lifecycle, change signals, preflight, portable handoff
  bundle.ts        Import/export decision bundle (always downgrade imported approvals)
  storage.ts       Workspace-scoped decision/evidence state
  scan.ts          VS Code FS + filesystem containment + bounded Git comparisons
  ui.ts            CSP-restricted theme-aware Control Center Webview
  extension.ts     Commands, state transitions, guarded user actions, evidence API

See architecture and threat model, user guide (ES), and QA matrix.

Commands

Settings: vinculivo.maxHandoffChars (default 50000, maximum 50000). Token budget is also configurable in the Preflight UI.

Build, verification and governance

npm ci --ignore-scripts --no-audit --no-fund
npm run typecheck
npm run test
npm run package:vsix

CI is PR/manual only, checking the same head SHA on ubuntu-latest, windows-latest and macos-latest. VSIX and checksum are uploaded only by Linux as private Actions artifacts. The main merge path does not re-execute the full suite or publish to GitHub Releases, Open VSX or Marketplace. Public distribution requires a separate explicit authorization.

Known boundaries (deliberate, not hidden)

• No LLM embeddings, private provider history ingestion, or claim of semantic proof. Deterministic local ranking provides traceability, not "AI understands your entire codebase".
• Documentation scan is bounded (up to 900 discovered Markdown files, 180 eligible files, 150 KB each, and up to 40 sections/file); incomplete scans are visible. Non-indexed files must not be treated as deleted.
• One selected workspace root is analyzed at a time; switching roots isolates decisions and evidence.
• Native remote Git history and extension-specific third-party report formats require independently verified adapters.
• Actual visual QA in ArmoTuSitio IDE, accessibility testing in a real extension host and real README captures remain private acceptance gates before a public release. We do not call those complete without evidence.

Español — resumen

Vinculivo es una extensión de inteligencia de contexto para VS Code y ArmoTuSitio IDE: indexa documentación, registra decisiones aprobadas por humanos, detecta cambios en archivos relacionados, prepara contextos específicos para Claude Code/Codex/Copilot y permite importar evidencia verificable. No envía información a terceros automáticamente; todas las exportaciones son explícitas. El desarrollo y el PR siguen privados hasta completar pruebas reales en el IDE.

Para el paso a paso y ejemplos, consultá Guía de uso (Español).