convez.ai
AgenteProdutividadeAvançado
th3vib3coder

Vibe Research Environment

th3vib3coder/vibe-research-environment

Shell de pesquisa file-backed com auditoria para trabalho científico com IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent de pesquisa científica com sistema de arquivo para gestão de fluxo de trabalho. Oferece workspace disciplinado para objetivos, papers, experimentos, resultados e escrita, mantendo auditoria completa e evitando perda de contexto em pesquisa assistida por IA. Integra-se ao kernel Vibe Science para governança de claims e validação científica.

Instalação

$npx convez-ai th3vib3coder/vibe-research-environment

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Gestão de fluxo de pesquisa científica com múltiplos agentes
  • Registro e rastreamento de papers, experimentos e resultados
  • Preparação de manuscritos com handoffs claim-aware
  • Auditoria e resumption de sessões de pesquisa longas

Veredito

Solução especializada e bem arquitetada para pesquisadores que usam IA agents em workflows científicos sérios. Exige disciplina e conhecimento técnico, mas resolve um problema real: evitar que trabalho crítico se perca em chat history. Não é ferramenta descartável, é infraestrutura de pesquisa.

README

A tradução para o português deste README ainda está na fila.

Vibe Research Environment (VRE)

VRE is a file-backed research operating shell for scientists who work with AI agents.

If you use an AI agent for literature, experiments, results, and writing, the default failure mode is brutal: the important work lives in chat, the chat gets compacted, and after a few days nobody can tell which paper was read, which experiment was run, which claim was reviewed, or which output is safe to put in a draft.

VRE fixes that by moving the operational memory of research onto disk. It gives the agent a disciplined workspace for objectives, papers, experiment manifests, result bundles, writing handoffs, memory mirrors, queues, lane runs, scheduled digests, and audit evidence.

VRE is usually paired with the Vibe Science kernel:

  • Vibe Science owns scientific truth: claims, citations, gates, governance hooks, R2 adversarial review, R3 judge review, serendipity, and the kernel SQLite database.
  • VRE owns research workflow state: what the agent is doing, what it has registered, what can be resumed, what was packaged, what needs review, and what evidence can be inspected.

VRE is not a statistics package, not a notebook engine, and not a chatbot UI. It is the operating layer around research work: the place where an AI-assisted research session becomes auditable, resumable, and harder to fool.


Contents


Who VRE Is For

VRE is for researchers, students, and research engineers who already use real scientific tools and want AI assistance without losing the trail.

It is especially useful when:

  • you are doing data-driven scientific work such as bioinformatics, scRNA-seq, omics, or adjacent computational research;
  • you want an AI agent to help with papers, manifests, result packaging, writing handoffs, and review preparation;
  • you need work to survive long gaps, chat compaction, or handoff to another agent;
  • you care about separating verified claims from drafts, speculation, and operational notes;
  • you want an agent that slows down at the right places, especially around claim promotion, R2 verdicts, destructive actions, and missing evidence.

VRE is probably too much if you only want a quick disposable chat. The point of VRE is discipline: it adds structure so that research does not evaporate.


What VRE Can Do Today

Core Research Flows

VRE ships helpers and command contracts for the everyday research loop:

AreaWhat VRE provides
LiteratureRegister papers, deduplicate by DOI, list papers, link papers to claims, surface citation gaps.
ExperimentsRegister schema-valid experiment manifests before analysis, update manifests, list experiments, surface blockers.
ResultsPackage completed experiment outputs into inspectable bundles with manifests and typed artifacts.
WritingBuild claim-aware handoffs, advisor packs, rebuttal packs, export snapshots, seeds, and deliverables.
MemoryRefresh markdown mirrors from kernel and workspace state, with freshness warnings.
StatusReport active flow, blockers, kernel bridge health, budget state, writing/results pointers, automation readiness, and latest attempts.

Phase 9 Objective Runtime

VRE also includes the newer Phase 9 objective layer:

AreaWhat VRE provides
Objectivesobjective start/status/pause/resume/stop/doctor with active-objective locking, budgets, wake policies, resume snapshots, and lifecycle events.
Bounded loopresearch-loop runs a bounded objective loop with wake leases, queue replay, blocker handling, memory sync, digest writing, and strategic drift checks.
Sanctioned executionrun-analysis executes only a reviewed local script template from a schema-valid analysis manifest.
Scheduler supportscheduler install/status/doctor/remove integrates unattended wake support through Windows Task Scheduler.
OrchestratorDurable queue, lane policies, execution/review lanes, provider gateway, recovery records, escalations, continuity profile, and task registry.
Review bindingReviewer-2 verdicts can be bound to typed claim edges in the supported REJECT + contradictedClaimId case.
Audit evidenceenvironment/audit/query.js can build the Wave 6 evidence excerpt from governance events and claim edges.

Governance And Audit Surfaces

VRE is designed to make uncertainty visible:

  • kernel bridge results carry availability/provenance metadata instead of silently pretending that missing data means zero;
  • governance events are append-only on the kernel side;
  • VRE objective events, queue records, lane runs, handoffs, claim edges, and audit outputs are durable files;
  • R2 verdicts and claim-edge binding use narrow, reviewed pathways;
  • npm run validate, npm run test:phase9, and CI enforce ledger, schema, surface-index, sandbox, personal-path, and closeout-honesty checks.

Quick Start

1. Check Out Both Repositories Side By Side

mkdir research-os
cd research-os
git clone https://github.com/th3vib3coder/vibe-science.git
git clone https://github.com/th3vib3coder/vibe-research-environment.git

Recommended layout:

research-os/
  vibe-science/                  # scientific kernel and Claude Code plugin
  vibe-research-environment/     # VRE, this repository

VRE auto-detects a sibling vibe-science checkout. If your kernel lives elsewhere, set VRE_KERNEL_PATH.

export VRE_KERNEL_PATH=/absolute/path/to/vibe-science

PowerShell:

$env:VRE_KERNEL_PATH = "C:\absolute\path\to\vibe-science"

2. Install Dependencies

cd vibe-research-environment
npm install

VRE requires Node.js 18 or newer. CI currently uses Node.js 20.

3. Initialize VRE

node bin/vre init

This creates or checks the local state tree:

.vibe-science-environment/
  control/
  flows/
  memory/
  objectives/
  orchestrator/

If the kernel is found, init reports an active kernel bridge. If the kernel is missing, VRE reports kernel: degraded and continues honestly. Many workspace surfaces still work in degraded mode, but kernel truth such as claims, citations, gate checks, and R2 state cannot be trusted as complete.

4. Verify The Repository

npm run check

npm run check runs the validators and the Node test suite. CI also runs the named Phase 9 suite:

npm run test:phase9

Friendly Usage Manual

This section is the "how do I actually use it?" version.

Step 1. Ask VRE What State Exists

node bin/vre flow-status
node bin/vre orchestrator-status

Use flow-status for the operator view: active flow, blockers, memory freshness, kernel availability, recent attempts, experiments, writing exports, automation state, and result pointers.

Use orchestrator-status for the coordination view: objective, queue, lanes, escalations, recoveries, continuity mode, and next recommended action.

Step 2. Start An Objective

An objective is the durable shell around a research goal.

node bin/vre objective start \
  --title "PDAC T-cell exhaustion marker survey" \
  --question "Which exhaustion markers are defensible in PDAC scRNA-seq?" \
  --mode interactive \
  --budget "maxWallSeconds=3600,maxIterations=3,heartbeatIntervalSeconds=300"

For non-interactive modes, provide a wake policy:

node bin/vre objective start \
  --title "Overnight literature digest" \
  --question "Summarize recent PDAC scRNA-seq exhaustion evidence" \
  --mode unattended-batch \
  --budget "maxWallSeconds=7200,maxIterations=5,heartbeatIntervalSeconds=600" \
  --wake-policy "wakeOwner=windows-task-scheduler,leaseTtlSeconds=600,duplicateWakePolicy=no-op"

Useful objective commands:

node bin/vre objective status --objective OBJ-...
node bin/vre objective pause --objective OBJ-... --reason "waiting for user decision"
node bin/vre objective resume --objective OBJ-...
node bin/vre objective resume --objective OBJ-... --repair-snapshot
node bin/vre objective stop --objective OBJ-... --reason "completed"
node bin/vre objective doctor --objective OBJ-...

Step 3. Let The Agent Register Papers And Experiments

When an AI agent reads papers or prepares an analysis, it should not leave that work only in chat.

Agent-facing command contracts live in commands/:

/flow-literature --register
/flow-experiment --register
/flow-results --package EXP-001
/flow-writing --handoff
/flow-writing --advisor-pack 2026-04-30
/flow-writing --rebuttal-pack SUBMISSION-001

The agent reads the markdown contract, calls the helper in environment/, and lets VRE write the machine-owned files. The user should not have to type clerical details such as DOI lists or manifest fields if the agent can extract them from sources and files.

Step 4. Run Analysis Only Through A Manifested Path

VRE does not replace Scanpy, Seurat, DESeq2, R, Python, or notebooks. It does, however, require analysis work to be registered and bounded.

The current run-analysis surface supports a reviewed local Node-script template from a schema-valid analysis manifest:

node bin/vre run-analysis --manifest path/to/analysis-manifest.json

Dry run:

node bin/vre run-analysis --manifest path/to/analysis-manifest.json --dry-run

The manifest must declare inputs, outputs, expected artifacts, a safe command template, budgets, and safety flags. Network access is not allowed in the v1 reviewed template.

Step 5. Run A Bounded Research Loop

Once an objective exists, VRE can run one bounded loop invocation:

node bin/vre research-loop --objective OBJ-... --json --max-iterations 1

Resume mode:

node bin/vre research-loop --objective OBJ-... --json --resume

Heartbeat / wake mode:

node bin/vre research-loop --objective OBJ-... --json --heartbeat --wake-id wake-001

The loop is intentionally bounded. It writes queue records, objective events, snapshots, blockers, digests, and memory sync state. If evidence is ambiguous or unsafe, it blocks or escalates instead of silently continuing.

Step 6. Sync Memory Before Stopping

At the end of a research session:

node bin/vre sync-memory

This refreshes machine-owned memory mirrors under:

.vibe-science-environment/memory/mirrors/

Mirrors are for resume and navigation. They do not replace kernel truth.

Step 7. Build Human-Friendly Outputs

When experiments and claims are ready, use writing and digest surfaces:

/flow-writing --handoff
/flow-writing --advisor-pack 2026-04-30
/flow-writing --rebuttal-pack SUBMISSION-001
/weekly-digest
/export-warning-digest
/stale-memory-reminder

These produce reviewable artifacts. They organize evidence and open issues, but they do not promote claims or verify citations by themselves.


Command Reference

Direct CLI Commands

Run direct commands as:

node bin/vre <command>
CommandPurpose
initCreate/check VRE state roots and report kernel bridge status.
flow-statusOperator-facing status summary.
orchestrator-statusQueue, lane, escalation, recovery, continuity, and objective status.
sync-memoryRefresh memory mirrors from allowed kernel/workspace projections.
capabilities --jsonGenerate and persist the Phase 9 capability handshake.
capabilities doctorInspect capability surface health.
objective startCreate and activate a new objective.
objective statusInspect one objective.
objective pausePause an active objective with a reason.
objective resumeResume a paused objective, optionally repairing the snapshot.
objective stopStop an objective with a reason.
objective doctorDiagnose objective state, scheduler readiness, and resume artifacts.
run-analysisExecute a reviewed analysis manifest through the sanctioned lane.
research-loopRun or resume a bounded objective loop.
scheduler installInstall a Windows scheduled wake task for an objective.
scheduler statusInspect scheduled wake state for an objective.
scheduler doctorDiagnose scheduler configuration for an objective.
scheduler removeRemove scheduled wake support for an objective.

Common CLI Options

CommandImportant options
objective start--title, --question, --mode, --reasoning-mode rule-only, --budget, --wake-policy for non-interactive modes.
objective status--objective OBJ-...
objective pause--objective OBJ-... --reason "..."
objective resume--objective OBJ-..., optional --repair-snapshot
objective stop--objective OBJ-... --reason "..."
run-analysis--manifest path/to/manifest.json, optional --dry-run
research-loop--objective OBJ-... --json, optional --resume, --heartbeat, --wake-id, --max-iterations, --max-wall-seconds, --mode
scheduler install/status/doctor/remove--objective OBJ-...

--budget and --wake-policy may be inline key=value lists, inline JSON, or paths to JSON files.

Agent Command Contracts

These are markdown contracts for an AI agent, not all direct shell verbs:

ContractPurpose
/flow-literatureRegister/list/link papers and surface literature gaps.
/flow-experimentRegister/update/list experiments and surface blockers.
/flow-resultsPackage completed experiment outputs.
/flow-writingBuild handoffs, advisor packs, rebuttal packs, and writing exports.
/flow-statusAgent-facing status contract for the same status surface.
/sync-memoryAgent-facing memory sync contract.
/orchestrator-runAgent contract for creating/continuing routed orchestrator work.
/orchestrator-statusAgent-facing orchestrator status contract.
/automation-statusShow automation readiness and latest artifacts.
/weekly-digestCreate a reviewable weekly research digest artifact.
/export-warning-digestSummarize export alerts.
/stale-memory-reminderSummarize stale memory mirror state.

Task Kinds

The orchestrator task registry currently includes:

Task kindLanePurpose
literature-flow-registerexecutionRegister a paper.
experiment-flow-registerexecutionRegister an experiment manifest.
results-bundle-discoverexecutionDiscover result bundles.
writing-export-finalizeexecutionFinalize a deliverable from an export snapshot.
session-digest-exportexecutionExport a session summary.
memory-sync-refreshexecutionRefresh memory mirrors.
session-digest-reviewreviewReview a session digest through the review lane.

Architecture

Human researcher
  |
  v
AI agent (Claude Code, Codex, Gemini CLI)
  |
  | reads command contracts and calls helpers
  v
VRE control plane
  |
  | attempts, events, decisions, capabilities, session snapshots
  v
VRE research runtime
  |
  | flows, objectives, orchestrator, queue, lanes, memory, automation
  v
.vibe-science-environment/ on disk

Vibe Science kernel/plugin
  |
  | claims, citations, gates, R2/R3, governance events, SQLite truth
  v
.vibe-science/ and kernel DB

The Two-Repo Boundary

RepositoryOwnsDoes not own
vibe-scienceScientific truth, plugin hooks, claims, citations, gates, R2/R3, serendipity, SQLite DB, governance events.VRE workflow state and result packaging.
vibe-research-environmentOperational workflow state, objective runtime, flow helpers, manifests, result bundles, memory mirrors, scheduler, queue/lane orchestration, connectors, audit excerpts.Kernel truth, claim promotion authority, citation truth, gate truth.

VRE reads kernel truth through environment/lib/kernel-bridge.js. It does not write kernel state directly.

Main VRE Layers

LayerKey paths
CLI dispatcherbin/vre
Command contractscommands/*.md
Control planeenvironment/control/
Research flowsenvironment/flows/
Objectivesenvironment/objectives/
Orchestratorenvironment/orchestrator/
Memoryenvironment/memory/
Automationenvironment/automation/
Connectorsenvironment/connectors/
Domain packsenvironment/domain-packs/
Audit helpersenvironment/audit/query.js
Schemasenvironment/schemas/
Testsenvironment/tests/
Runtime state.vibe-science-environment/

Safety Model

VRE is opinionated because research automation without discipline is dangerous.

1. No Silent Zero

A missing kernel database is not the same as "zero claims" or "no blockers". Kernel bridge envelopes carry dbAvailable, sourceMode, and degraded reason metadata. If the bridge is degraded, VRE should say so.

2. File-Backed State

Attempts, decisions, events, manifests, bundles, queue records, lane runs, handoffs, digests, and memory mirrors live on disk. The chat transcript is not the source of truth.

3. Manifest Before Analysis

Experiments and sanctioned analysis runs must be described before execution. The current run-analysis surface is narrow by design: schema-valid manifest, reviewed command template, safe paths, bounded runtime, and no network access.

4. R2 Before Claim Promotion

Claim promotion belongs to the Vibe Science kernel and its review gates. VRE can prepare evidence and route review work, but it does not silently promote scientific claims.

5. Append-Only And Fail-Closed Where It Matters

Governance events and ledgers are designed to be inspectable. Many write paths fail closed on invalid schema, missing metadata, duplicate conflicts, unsafe paths, or unsupported templates.

6. Reviewable Automation

Scheduled digests and reminders create review artifacts. They do not replace per-patch ledger discipline, do not decide gates, and do not mutate scientific truth.


Technical Details

Local State Directory

VRE writes machine-owned state under:

.vibe-science-environment/
  automation/
  claims/
  control/
  experiments/
  flows/
  memory/
  objectives/
  orchestrator/
  results/
  writing/

Do not edit these files by hand unless a specific maintenance task says so. Use the helpers and command contracts.

Environment Variables

VariablePurpose
VRE_KERNEL_PATHExplicit path to vibe-science; overrides sibling auto-discovery.
VRE_VERBOSE=1Print per-command kernel bridge active/degraded diagnostics to stderr.
VRE_BUDGET_MAX_USDMiddleware hard-stop spend limit.
VRE_BUDGET_ESTIMATED_COST_USDAdvisory cost threshold.
VRE_CLAUDE_CLIOverride path to the Claude CLI. On Windows, often claude.cmd.
VRE_CODEX_CLIOverride path to the Codex CLI. On Windows, often codex.cmd.
VRE_REVIEW_EVIDENCE_MODETest/review-lane evidence-mode override.
VRE_EXTERNAL_WAKE_CALLERIdentity for external research-loop wake calls.
VRE_HEARTBEAT_PROBE_ONLY=1Exercise heartbeat probe mode without running the full loop.
VRE_HEARTBEAT_MIN_INTERVAL_MSProcess-local heartbeat governance rate limit.
VRE_RUN_ANALYSIS_TIMEOUT_MSOperator cap for sanctioned analysis execution timeout.
VIBE_SCIENCE_DB_PATHUsed by plugin-owned bridge CLIs when an explicit DB path is needed.
VIBE_SCIENCE_PLUGIN_ROOTUsed by plugin-owned bridge CLIs when plugin root discovery needs help.
VIBE_SCIENCE_AUDIT_QUERY_CLIOverride path for the plugin audit-query CLI.
ANTHROPIC_API_KEYPassed through to Claude CLI executor when needed.
OPENAI_API_KEYPassed through to Codex CLI executor when needed.
CLAUDE_CONFIG_DIRPassed through to Claude CLI executor when needed.

Validation And Tests

Useful commands:

npm run validate
npm run test:phase9
npm test
npm run check
npm run build:surface-index
npm run check:phase9-ledger

Current validator coverage includes counts, CI workflow, Phase 9 ledger rules, surface index, write sandbox, no-personal-path checks, and closeout honesty.

Current Surface Counts

At the current Wave 5 v2.1 evidence-side closeout, the VRE validators expect:

SurfaceCount
Install bundle manifests11
Schemas54
Eval tasks25
Eval metrics5
Eval benchmarks5
CI validators15

These counts are enforced by repository validators and should be updated only with the code that changes the surface.


Current Status

Wave 5 v2.1 is complete on the evidence side. The implementation trail for seq 113-130 landed, R2 inline pending is zero, and seq 130 records R2 inline OK.

The operator gate flip from wave-5-implementation-allowed.status to completed is intentionally separate. Wave 6 is formally unlocked after that operator action. The operating rule remains: Phase 10 does not begin before Phase 9 is complete.

For live CI state, check GitHub Actions. This README describes the repository surface, not a guarantee about every future commit.


Italiano

Vibe Research Environment (VRE)

VRE e' una shell operativa file-backed per fare ricerca con agenti AI.

Quando usi un agente AI per letteratura, esperimenti, risultati e scrittura, il problema classico e' questo: il lavoro importante rimane nella chat, la chat viene compattata, e dopo qualche giorno non e' piu' chiaro quali paper siano stati letti, quale esperimento sia stato eseguito, quale claim sia stato revisionato, o quale output sia abbastanza solido per entrare in una bozza.

VRE risolve questo problema spostando la memoria operativa della ricerca su disco. Da' all'agente uno spazio disciplinato per obiettivi, paper, manifesti di esperimento, bundle di risultati, handoff di scrittura, mirror di memoria, code, lane run, digest schedulati ed evidenza auditabile.

VRE di solito lavora insieme al kernel Vibe Science:

  • Vibe Science possiede la verita' scientifica: claim, citazioni, gate, hook di governance, review avversaria R2, judge review R3, serendipity e il database SQLite del kernel.
  • VRE possiede lo stato operativo del workflow: cosa sta facendo l'agente, cosa ha registrato, cosa si puo' riprendere, cosa e' stato impacchettato, cosa richiede review, e quale evidenza si puo' ispezionare.

VRE non e' un pacchetto statistico, non e' un motore notebook, e non e' una UI chatbot. E' il livello operativo intorno al lavoro di ricerca: il punto in cui una sessione di ricerca assistita da AI diventa auditabile, riprendibile e piu' difficile da falsare.


Indice


A Chi Serve VRE

VRE e' pensato per ricercatori, studenti e research engineer che usano gia' strumenti scientifici reali e vogliono usare agenti AI senza perdere la traccia del lavoro.

E' particolarmente utile quando:

  • fai ricerca data-driven, per esempio bioinformatica, scRNA-seq, omics o aree computazionali vicine;
  • vuoi che un agente AI aiuti con paper, manifesti, packaging dei risultati, handoff di scrittura e preparazione di review;
  • vuoi che il lavoro sopravviva a pause lunghe, compattazione della chat o passaggi tra agenti;
  • devi separare claim verificati, bozze, speculazione e note operative;
  • vuoi un agente che rallenti nei punti giusti: promozione dei claim, verdetti R2, azioni distruttive e evidenza mancante.

VRE e' probabilmente troppo se vuoi solo una risposta usa-e-getta in chat. Il punto di VRE e' la disciplina: aggiunge struttura per evitare che la ricerca evapori.


Cosa Sa Fare VRE Oggi

Flussi Di Ricerca

VRE include helper e contratti di comando per il loop quotidiano di ricerca:

AreaCosa fornisce VRE
LetteraturaRegistrazione paper, deduplica DOI, lista paper, link paper-claim, gap citazionali.
EsperimentiManifesti di esperimento schema-valid prima dell'analisi, update, lista, blocker.
RisultatiPackaging di output completati in bundle ispezionabili con manifesti e artifact tipizzati.
ScritturaHandoff claim-aware, advisor pack, rebuttal pack, export snapshot, seed e deliverable.
MemoriaMirror markdown aggiornati da kernel e workspace, con warning di freschezza.
StatoFlow attivo, blocker, stato kernel bridge, budget, writing/results pointer, automazioni e tentativi recenti.

Runtime Obiettivi Phase 9

VRE include anche il livello moderno degli obiettivi Phase 9:

AreaCosa fornisce VRE
Obiettiviobjective start/status/pause/resume/stop/doctor con lock dell'obiettivo attivo, budget, wake policy, resume snapshot ed eventi lifecycle.
Loop boundedresearch-loop con wake lease, replay della coda, blocker, memory sync, digest e strategic drift check.
Esecuzione autorizzatarun-analysis esegue solo template locali revisionati a partire da un analysis manifest valido.
Schedulerscheduler install/status/doctor/remove integra wake unattended via Windows Task Scheduler.
OrchestratorCoda durevole, lane policy, execution/review lane, provider gateway, recovery, escalation, continuity profile e task registry.
Review bindingI verdetti Reviewer-2 possono produrre typed claim edges nel caso supportato REJECT + contradictedClaimId.
Audit evidenceenvironment/audit/query.js costruisce l'evidence excerpt Wave 6 da governance events e claim edges.

Governance E Audit

VRE e' progettato per rendere visibile l'incertezza:

  • il kernel bridge espone metadati di disponibilita' e provenienza, invece di fingere che dati mancanti significhino zero;
  • gli eventi di governance sono append-only lato kernel;
  • eventi obiettivo, queue records, lane run, handoff, claim edges e output audit sono file durevoli;
  • verdetti R2 e claim-edge binding passano da percorsi stretti e revisionati;
  • npm run validate, npm run test:phase9 e CI controllano ledger, schemi, surface index, write sandbox, personal path e closeout honesty.

Quick Start

1. Clona I Due Repository Affiancati

mkdir research-os
cd research-os
git clone https://github.com/th3vib3coder/vibe-science.git
git clone https://github.com/th3vib3coder/vibe-research-environment.git

Layout consigliato:

research-os/
  vibe-science/                  # kernel scientifico e plugin Claude Code
  vibe-research-environment/     # VRE, questo repository

VRE auto-rileva un checkout sibling vibe-science. Se il kernel vive altrove, imposta VRE_KERNEL_PATH.

export VRE_KERNEL_PATH=/absolute/path/to/vibe-science

PowerShell:

$env:VRE_KERNEL_PATH = "C:\absolute\path\to\vibe-science"

2. Installa Le Dipendenze

cd vibe-research-environment
npm install

VRE richiede Node.js 18 o superiore. La CI usa Node.js 20.

3. Inizializza VRE

node bin/vre init

Questo crea o controlla l'albero di stato locale:

.vibe-science-environment/
  control/
  flows/
  memory/
  objectives/
  orchestrator/

Se il kernel viene trovato, init segnala un kernel bridge attivo. Se manca, VRE segnala kernel: degraded e continua in modo onesto. Molte superfici di workspace funzionano ancora in degraded mode, ma claim, citazioni, gate e stato R2 del kernel non vanno considerati completi.

4. Verifica Il Repository

npm run check

npm run check esegue validatori e test Node. La CI esegue anche la suite Phase 9 nominata:

npm run test:phase9

Manuale Friendly

Questa e' la versione "come lo uso davvero?".

Step 1. Chiedi A VRE Quale Stato Esiste

node bin/vre flow-status
node bin/vre orchestrator-status

Usa flow-status per la vista operatore: flow attivo, blocker, freschezza memoria, disponibilita' kernel, tentativi recenti, esperimenti, export di scrittura, automazioni e pointer ai risultati.

Usa orchestrator-status per la vista coordinamento: obiettivo, coda, lane, escalation, recovery, continuity mode e prossima azione raccomandata.

Step 2. Apri Un Obiettivo

Un obiettivo e' il contenitore durevole intorno a una domanda di ricerca.

node bin/vre objective start \
  --title "PDAC T-cell exhaustion marker survey" \
  --question "Which exhaustion markers are defensible in PDAC scRNA-seq?" \
  --mode interactive \
  --budget "maxWallSeconds=3600,maxIterations=3,heartbeatIntervalSeconds=300"

Per modalita' non interattive, aggiungi una wake policy:

node bin/vre objective start \
  --title "Overnight literature digest" \
  --question "Summarize recent PDAC scRNA-seq exhaustion evidence" \
  --mode unattended-batch \
  --budget "maxWallSeconds=7200,maxIterations=5,heartbeatIntervalSeconds=600" \
  --wake-policy "wakeOwner=windows-task-scheduler,leaseTtlSeconds=600,duplicateWakePolicy=no-op"

Comandi utili per gli obiettivi:

node bin/vre objective status --objective OBJ-...
node bin/vre objective pause --objective OBJ-... --reason "waiting for user decision"
node bin/vre objective resume --objective OBJ-...
node bin/vre objective resume --objective OBJ-... --repair-snapshot
node bin/vre objective stop --objective OBJ-... --reason "completed"
node bin/vre objective doctor --objective OBJ-...

Step 3. Lascia Che L'Agente Registri Paper Ed Esperimenti

Quando un agente AI legge paper o prepara un'analisi, quel lavoro non deve restare solo in chat.

I contratti agent-facing stanno in commands/:

/flow-literature --register
/flow-experiment --register
/flow-results --package EXP-001
/flow-writing --handoff
/flow-writing --advisor-pack 2026-04-30
/flow-writing --rebuttal-pack SUBMISSION-001

L'agente legge il contratto markdown, chiama l'helper in environment/, e VRE scrive i file machine-owned. L'utente non dovrebbe digitare dettagli clericali come liste DOI o campi manifesto se l'agente puo' estrarli da fonti e file.

Step 4. Esegui Analisi Solo Attraverso Un Percorso Manifestato

VRE non sostituisce Scanpy, Seurat, DESeq2, R, Python o notebook. Pero' richiede che il lavoro analitico sia registrato e bounded.

L'attuale superficie run-analysis supporta un template locale Node revisionato da un analysis manifest schema-valido:

node bin/vre run-analysis --manifest path/to/analysis-manifest.json

Dry run:

node bin/vre run-analysis --manifest path/to/analysis-manifest.json --dry-run

Il manifesto deve dichiarare input, output, artifact attesi, template comando, budget e safety flag. Nel template revisionato v1 la rete non e' consentita.

Step 5. Esegui Un Research Loop Bounded

Quando esiste un obiettivo, VRE puo' eseguire una invocazione bounded del loop:

node bin/vre research-loop --objective OBJ-... --json --max-iterations 1

Resume mode:

node bin/vre research-loop --objective OBJ-... --json --resume

Heartbeat / wake mode:

node bin/vre research-loop --objective OBJ-... --json --heartbeat --wake-id wake-001

Il loop e' intenzionalmente bounded. Scrive queue record, eventi obiettivo, snapshot, blocker, digest e stato di memory sync. Se l'evidenza e' ambigua o insicura, blocca o fa escalation invece di continuare in silenzio.

Step 6. Sincronizza La Memoria Prima Di Fermarti

Alla fine di una sessione di ricerca:

node bin/vre sync-memory

Questo aggiorna i mirror machine-owned sotto:

.vibe-science-environment/memory/mirrors/

I mirror servono per resume e navigazione. Non sostituiscono la verita' del kernel.

Step 7. Costruisci Output Leggibili Da Umani

Quando esperimenti e claim sono pronti, usa le superfici di writing e digest:

/flow-writing --handoff
/flow-writing --advisor-pack 2026-04-30
/flow-writing --rebuttal-pack SUBMISSION-001
/weekly-digest
/export-warning-digest
/stale-memory-reminder

Questi producono artifact revisionabili. Organizzano evidenza e questioni aperte, ma non promuovono claim e non verificano citazioni da soli.


Reference Dei Comandi

Comandi CLI Diretti

Esegui i comandi diretti cosi':

node bin/vre <command>
ComandoScopo
initCrea/controlla lo stato VRE e segnala lo stato del kernel bridge.
flow-statusSommario operatore.
orchestrator-statusStato di coda, lane, escalation, recovery, continuity e obiettivo.
sync-memoryAggiorna i mirror di memoria da proiezioni consentite.
capabilities --jsonGenera e persiste il capability handshake Phase 9.
capabilities doctorDiagnostica la superficie capability.
objective startCrea e attiva un nuovo obiettivo.
objective statusIspeziona un obiettivo.
objective pauseMette in pausa un obiettivo attivo con motivo.
objective resumeRiprende un obiettivo, con eventuale repair snapshot.
objective stopFerma un obiettivo con motivo.
objective doctorDiagnostica stato obiettivo, scheduler e artifact di resume.
run-analysisEsegue un analysis manifest revisionato tramite lane autorizzata.
research-loopEsegue o riprende un loop bounded di obiettivo.
scheduler installInstalla una wake task Windows per un obiettivo.
scheduler statusIspeziona lo stato scheduler di un obiettivo.
scheduler doctorDiagnostica la configurazione scheduler.
scheduler removeRimuove il supporto scheduler per un obiettivo.

Opzioni Comuni

ComandoOpzioni importanti
objective start--title, --question, --mode, --reasoning-mode rule-only, --budget, --wake-policy per modalita' non interattive.
objective status--objective OBJ-...
objective pause--objective OBJ-... --reason "..."
objective resume--objective OBJ-..., opzionale --repair-snapshot
objective stop--objective OBJ-... --reason "..."
run-analysis--manifest path/to/manifest.json, opzionale --dry-run
research-loop--objective OBJ-... --json, opzionale --resume, --heartbeat, --wake-id, --max-iterations, --max-wall-seconds, --mode
scheduler install/status/doctor/remove--objective OBJ-...

--budget e --wake-policy possono essere liste inline key=value, JSON inline, oppure path a file JSON.

Contratti Agent-Driven

Questi sono contratti markdown per un agente AI, non necessariamente verbi shell diretti:

ContrattoScopo
/flow-literatureRegistra/lista/linka paper e mostra gap di letteratura.
/flow-experimentRegistra/aggiorna/lista esperimenti e mostra blocker.
/flow-resultsImpacchetta output di esperimenti completati.
/flow-writingCostruisce handoff, advisor pack, rebuttal pack ed export.
/flow-statusContratto agent-facing per la stessa status surface.
/sync-memoryContratto agent-facing per memory sync.
/orchestrator-runContratto per creare/continuare lavoro orchestrato.
/orchestrator-statusContratto agent-facing per stato orchestrator.
/automation-statusMostra readiness automazioni e ultimi artifact.
/weekly-digestCrea un digest settimanale revisionabile.
/export-warning-digestRiassume alert sugli export.
/stale-memory-reminderRiassume stato stale dei mirror di memoria.

Task Kind

Il task registry dell'orchestrator include:

Task kindLaneScopo
literature-flow-registerexecutionRegistra un paper.
experiment-flow-registerexecutionRegistra un manifesto di esperimento.
results-bundle-discoverexecutionScopre bundle di risultati.
writing-export-finalizeexecutionFinalizza un deliverable da export snapshot.
session-digest-exportexecutionEsporta un sommario di sessione.
memory-sync-refreshexecutionAggiorna mirror di memoria.
session-digest-reviewreviewRevisiona un digest tramite review lane.

Architettura

Ricercatore umano
  |
  v
Agente AI (Claude Code, Codex, Gemini CLI)
  |
  | legge contratti comando e chiama helper
  v
Control plane VRE
  |
  | attempts, events, decisions, capabilities, session snapshots
  v
Runtime di ricerca VRE
  |
  | flows, objectives, orchestrator, queue, lanes, memory, automation
  v
.vibe-science-environment/ su disco

Kernel/plugin Vibe Science
  |
  | claims, citations, gates, R2/R3, governance events, SQLite truth
  v
.vibe-science/ e DB kernel

Confine Tra I Due Repo

RepositoryPossiedeNon possiede
vibe-scienceVerita' scientifica, hook plugin, claim, citazioni, gate, R2/R3, serendipity, DB SQLite, governance events.Stato workflow e packaging risultati VRE.
vibe-research-environmentStato operativo, objective runtime, flow helper, manifesti, result bundle, memory mirror, scheduler, queue/lane orchestration, connector, audit excerpt.Verita' del kernel, autorita' di promozione claim, verita' citazionale, verita' dei gate.

VRE legge la verita' del kernel tramite environment/lib/kernel-bridge.js. Non scrive direttamente lo stato del kernel.

Layer Principali

LayerPath principali
CLI dispatcherbin/vre
Contratti comandocommands/*.md
Control planeenvironment/control/
Flow di ricercaenvironment/flows/
Obiettivienvironment/objectives/
Orchestratorenvironment/orchestrator/
Memoriaenvironment/memory/
Automazioneenvironment/automation/
Connectorenvironment/connectors/
Domain packenvironment/domain-packs/
Helper auditenvironment/audit/query.js
Schemienvironment/schemas/
Testenvironment/tests/
Stato runtime.vibe-science-environment/

Modello Di Sicurezza

VRE e' opinionated perche' l'automazione di ricerca senza disciplina e' pericolosa.

1. No Silent Zero

Un database kernel mancante non significa "zero claim" o "nessun blocker". Gli envelope del kernel bridge portano metadati dbAvailable, sourceMode e degraded reason. Se il bridge e' degradato, VRE deve dirlo.

2. Stato Su File

Attempt, decisioni, eventi, manifesti, bundle, queue record, lane run, handoff, digest e memory mirror vivono su disco. La chat non e' la fonte di verita'.

3. Manifesto Prima Dell'Analisi

Esperimenti ed esecuzioni autorizzate devono essere descritti prima dell'esecuzione. L'attuale run-analysis e' stretto di proposito: manifest schema-valido, template comando revisionato, path sicuri, runtime bounded e niente accesso rete.

4. R2 Prima Della Promozione Claim

La promozione dei claim appartiene al kernel Vibe Science e ai suoi gate di review. VRE puo' preparare evidenza e instradare lavoro di review, ma non promuove claim scientifici in silenzio.

5. Append-Only E Fail-Closed Dove Conta

Eventi di governance e ledger sono progettati per essere ispezionabili. Molti percorsi di scrittura falliscono su schema invalido, metadati mancanti, duplicati in conflitto, path non sicuri o template non supportati.

6. Automazione Revisionabile

Digest schedulati e reminder creano artifact revisionabili. Non sostituiscono la disciplina ledger per patch, non decidono gate e non mutano la verita' scientifica.


Dettagli Tecnici

Directory Di Stato Locale

VRE scrive stato machine-owned sotto:

.vibe-science-environment/
  automation/
  claims/
  control/
  experiments/
  flows/
  memory/
  objectives/
  orchestrator/
  results/
  writing/

Non modificare questi file a mano, salvo task di manutenzione specifici. Usa helper e contratti comando.

Variabili D'Ambiente

VariabileScopo
VRE_KERNEL_PATHPath esplicito a vibe-science; sovrascrive auto-discovery sibling.
VRE_VERBOSE=1Stampa diagnostica active/degraded del kernel bridge su stderr.
VRE_BUDGET_MAX_USDLimite hard-stop di spesa gestito dal middleware.
VRE_BUDGET_ESTIMATED_COST_USDSoglia advisory di costo.
VRE_CLAUDE_CLIOverride path Claude CLI. Su Windows spesso claude.cmd.
VRE_CODEX_CLIOverride path Codex CLI. Su Windows spesso codex.cmd.
VRE_REVIEW_EVIDENCE_MODEOverride test/review-lane evidence mode.
VRE_EXTERNAL_WAKE_CALLERIdentita' per wake call esterne di research-loop.
VRE_HEARTBEAT_PROBE_ONLY=1Testa heartbeat probe senza eseguire il loop completo.
VRE_HEARTBEAT_MIN_INTERVAL_MSRate limit process-local per eventi heartbeat.
VRE_RUN_ANALYSIS_TIMEOUT_MSCap operatore per timeout di esecuzione analisi.
VIBE_SCIENCE_DB_PATHUsato dai bridge CLI plugin-owned quando serve un DB esplicito.
VIBE_SCIENCE_PLUGIN_ROOTUsato dai bridge CLI plugin-owned quando serve scoprire il plugin root.
VIBE_SCIENCE_AUDIT_QUERY_CLIOverride path audit-query CLI del plugin.
ANTHROPIC_API_KEYPassato al Claude CLI executor quando serve.
OPENAI_API_KEYPassato al Codex CLI executor quando serve.
CLAUDE_CONFIG_DIRPassato al Claude CLI executor quando serve.

Validazione E Test

Comandi utili:

npm run validate
npm run test:phase9
npm test
npm run check
npm run build:surface-index
npm run check:phase9-ledger

La validazione corrente copre counts, workflow CI, regole ledger Phase 9, surface index, write sandbox, no-personal-path e closeout honesty.

Conteggi Di Superficie Correnti

Alla chiusura evidence-side Wave 5 v2.1, i validatori VRE si aspettano:

SuperficieConteggio
Install bundle manifests11
Schemi54
Eval tasks25
Eval metrics5
Eval benchmarks5
CI validators15

Questi conteggi sono enforced dai validatori del repo e vanno aggiornati solo insieme al codice che cambia la superficie.


Stato Corrente

Wave 5 v2.1 e' completa lato evidenza. Il trail implementativo seq 113-130 e' landed, R2 inline pending e' zero, e seq 130 registra R2 inline OK.

Il flip operatore da wave-5-implementation-allowed.status a completed resta separato di proposito. Wave 6 si sblocca formalmente dopo quell'azione operatore. La regola operativa resta: Phase 10 non inizia prima che Phase 9 sia terminata.

Per lo stato CI live, controlla GitHub Actions. Questo README descrive la superficie del repository, non garantisce lo stato di ogni commit futuro.

Ver o original no GitHub

Bom para

Relacionados