research-vault 0.1.0__tar.gz

research_vault-0.1.0/.githooks/commit-msg

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+# commit-msg — Research Vault git-discipline hook
+#
+# Enforces conventional-commit format on the commit subject:
+#   <type>(<scope>): <description>
+#   types: feat|fix|docs|refactor|test|chore|ci|build|perf
+#
+# Install via: rv git-discipline install
+exec rv git-discipline commit-msg "$1"

research_vault-0.1.0/.githooks/pre-commit

@@ -0,0 +1,15 @@
+#!/usr/bin/env sh
+# pre-commit — Research Vault git-discipline hook
+#
+# Runs cheapest-reject-first:
+#   1. protect-main (branch/path-keyed, identity-free)
+#   2. staged leakage scan (profile-aware: secrets everywhere; private
+#      markers framework-repo-only)
+#   3. rv lint (when src/ files are staged)
+#
+# Bypass consciously (never silently):
+#   git commit --no-verify      — bypass all hooks
+#   RV_ALLOW_MAIN_COMMIT=1      — bypass protect-main only
+#
+# Install via: rv git-discipline install
+exec rv git-discipline check --staged

research_vault-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,149 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # ── Hermetic pytest suite ────────────────────────────────────────────────────
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        # SR-PKG: install Tier-1 defaults + dev deps only.
+        # --all-extras would pull [local] (torch/vllm/sglang) which cannot
+        # resolve on CPU CI runners. Tier-2 is GPU-only and must stay opt-in.
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short
+
+  # ── Leakage scanner (full teeth — SR-4, broadened SR-PKG) ──────────────────
+  # SR-PKG: doctrine/ + examples/ moved into the wheel at
+  #   src/research_vault/data/doctrine/ + src/research_vault/data/examples/.
+  # Coverage broadened to the whole publish-bound tree (whole-tree by default,
+  # opt-out by exception — the safe polarity for a public publish).
+  # Scans: package data (doctrine/ + examples/), DEVLOG.md, root public-bound
+  # files (README.md, QUICKSTART.md, REFERENCES.md, SETUP.md),
+  # and src/ for hardcoded private paths — all private marker classes:
+  #   codenames · identity strings · site URLs · cluster paths ·
+  #   secret-shaped strings · versioned model IDs · non-template memory slugs
+  # Implemented in scripts/leakage_scan.sh (tested hermetically in tests/).
+  leakage-scan:
+    name: Leakage scan
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run leakage scanner over src/research_vault/data/doctrine/
+        run: bash scripts/leakage_scan.sh src/research_vault/data/doctrine
+
+      - name: Run leakage scanner over src/research_vault/data/examples/
+        run: bash scripts/leakage_scan.sh src/research_vault/data/examples
+
+      # SR-CCB: CLAUDE.md.tmpl ships in the wheel and gets written to every
+      # adopter's instance root — must be leakage-clean (publish-bound).
+      - name: Run leakage scanner over src/research_vault/data/templates/
+        run: bash scripts/leakage_scan.sh src/research_vault/data/templates
+
+      - name: Run leakage scanner over DEVLOG.md
+        run: bash scripts/leakage_scan.sh DEVLOG.md
+
+      - name: Run leakage scanner over root public-bound files
+        run: |
+          # Scan public-bound root files individually.
+          # REFERENCES.md and SETUP.md scanned when present (future artifacts).
+          # LICENSE + pyproject.toml added (SR-SETUP: ship to PyPI — must be clean).
+          for f in README.md QUICKSTART.md REFERENCES.md SETUP.md LICENSE pyproject.toml RELEASING.md; do
+            if [ -f "$f" ]; then
+              echo "--- scanning $f ---"
+              bash scripts/leakage_scan.sh "$f"
+            fi
+          done
+
+      - name: Check for hardcoded private paths in src/
+        run: |
+          echo "=== Hardcoded path scan (src/) ==="
+          if grep -rn --include="*.py" \
+              -E "(/juice2/|/scr2/|phoongkz|phoongkhangzhie)" \
+              src/ 2>/dev/null; then
+            echo "FAIL: hardcoded private paths found in src/"
+            exit 1
+          fi
+          echo "OK: no hardcoded private paths in src/"
+
+      # Hygiene-batch: class 10 crew narrative-names in Python source.
+      # Catches session-narrative attributions (Ada/Wren/Mason/Argus/Iris/Atlas)
+      # in shipped .py files. Runs leakage_scan.sh over src/ — the _grep_py_word
+      # helper in class 10 restricts matches to .py files only, so role docs
+      # (*.md in data/doctrine/roles/) are not flagged.
+      - name: Check for crew narrative-names in src/ Python source
+        run: bash scripts/leakage_scan.sh src/research_vault
+
+  # ── help --check gate ───────────────────────────────────────────────────────
+  help-check:
+    name: rv help --check
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install package
+        # SR-PKG: Tier-1 defaults only — Tier-2 [local] is GPU-only, not for CI.
+        run: uv sync
+
+      - name: Verify all verbs have when_to_use docstrings
+        run: uv run rv help --check
+
+  # ── rv lint gate ────────────────────────────────────────────────────────────
+  # Runs the project linter over the whole repo: leakage scan + config schema +
+  # verb docstring gate + test-hygiene rules (vacuous assertions, unpinned git
+  # init) + F811 redefined-while-unused check (catches shadowed def/class names
+  # in src/research_vault/ — the SR-MS-2 duplicate check_manuscript gap).
+  rv-lint:
+    name: rv lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install package
+        # SR-PKG: Tier-1 defaults only — Tier-2 [local] is GPU-only, not for CI.
+        run: uv sync
+
+      - name: Run rv lint (full repo)
+        run: uv run rv lint

research_vault-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,60 @@
+name: Publish to PyPI
+
+# Trigger: a version tag pushed manually by the maintainer.
+# Usage: git tag v0.1.0 && git push origin v0.1.0
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Upload built artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/research-vault/
+
+    # PyPI Trusted Publishing (OIDC) — no PYPI_TOKEN secret required.
+    # The pending publisher must be registered on PyPI before the first release.
+    # See RELEASING.md for the exact registration steps.
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download built artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

research_vault-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+*.whl
+.venv/
+venv/
+env/
+.env
+.python-version
+
+# uv
+.uv/
+uv.lock
+
+# pytest
+.pytest_cache/
+.cache/
+
+# State directory (instance data — never committed in the framework repo)
+state/
+*.state/
+
+# Editor
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Instance secrets / dotfiles
+.secrets
+*.secret
+.keyring/
+
+# Local-only maintenance aids (private ~/vault path structure — not for the public repo)
+doctrine/drift-watch.md
+
+# Worktrees
+.worktrees/
+
+# Stray local dirs / OS cruft (not part of the OSS repo)
+tasks/
+.DS_Store
+**/.DS_Store

research_vault-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to Research Vault
+
+Thanks for your interest. Research Vault is a young project with a strong point of
+view: **the discipline is the product.** Contributions are welcome, but the bar is
+that a change must *keep the disciplines honest* — a feature that makes fabrication
+easier, or lets a gate be waved through, will be declined no matter how convenient.
+
+## The doctrine-first ethos
+
+The disciplines (anti-fabrication, every-outcome-is-a-finding, verify-the-artifact,
+pre-registration, human-only approval, crew-cannot-self-approve) live in
+`src/research_vault/data/doctrine/`. They are shipped as package data and read by
+the agents at work time.
+
+**A change to a discipline is a doctrine change.** If your PR alters how a gate
+behaves, what a role may do, or what counts as "verified," update the doctrine in
+the same change and say so explicitly in the PR description. Do not route around a
+discipline in code while leaving the doctrine stating the old rule — that drift is
+exactly what the project exists to prevent.
+
+## Development setup
+
+Research Vault targets **Python 3.12+** and uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/phoongkhangzhie/research-vault.git
+cd research-vault
+uv sync                     # create the environment + install dev deps (pytest)
+uv run rv --help            # confirm the CLI resolves
+```
+
+If you are working from a bare install and need the research toolkit:
+
+```bash
+rv bootstrap                # creates an isolated .venv and installs the toolkit
+rv check                    # verify the tier coverage matrix
+```
+
+## The test suite
+
+```bash
+uv run pytest               # the full suite
+uv run pytest -m slow       # isolated wheel build+install+run smoke tests (slower)
+```
+
+Test discipline (enforced by `rv lint`, see below — the project is strict about it):
+
+- **No vacuous assertions.** `assert True` / `or True` are flagged — a tautology
+  that always passes masks the bug it was meant to catch.
+- **Stress the code, not the docstring.** Asserting against `inspect.getsource(fn)`
+  is flagged — it passes even when the live code is broken, because the symbol may
+  survive only in a comment.
+- **Pin your branch in test git-inits.** `git init` without `--initial-branch` is
+  flagged — it passes locally and fails on master-default runners.
+
+New behavior needs a test that *and* stress-tests it. An LLM-judged gate needs a
+blind-judge canary (a known-outcome probe) so a mis-calibrated judge can't silently
+rubber-stamp — see `data/doctrine/honesty-gates.md`.
+
+## The lint / leakage gates
+
+Before opening a PR, run:
+
+```bash
+rv lint                     # leakage scan + config schema + test-hygiene + doc links
+```
+
+`rv lint` runs the **leakage gate** — the most important check for a public repo.
+The package must contain **zero private markers**: no absolute home-directory paths,
+no personal names, no internal codenames, no secrets. The forbidden-pattern list is
+config-driven, not compiled in. A leak is a blocking failure, not a footnote.
+
+> **Note on CI.** Automated CI/Actions may be disabled on this repo at times. When
+> it is, `rv lint` + the leakage scan + `uv run pytest` are the gates you run
+> **locally before every PR** — treat a red local gate exactly as you would a red
+> CI: fix it first, do not build on top of it.
+
+## Commit & PR conventions
+
+- **Conventional commits.** Use `type: summary` (`feat:`, `fix:`, `docs:`,
+  `refactor:`, `test:`, …). The git-discipline hooks (`rv git-discipline install`)
+  enforce the format, protect `main`, and run a leakage scan on commit.
+- **Commit as you go.** Commit incrementally as work lands — do not hold a large
+  uncommitted working tree hostage to one final commit. Work is recoverable only
+  once it is committed.
+- **Work on a branch / worktree, never on `main`.** `rv wt add <task>` creates an
+  isolated worktree on `feat/<task>`.
+- **Keep the change scoped.** One concern per PR. Update the `DEVLOG.md` with the
+  decisions you made, not just what you did.
+
+## The review discipline
+
+Research Vault distinguishes two merge classes, and **nobody merges on their own
+authority**:
+
+- **reviewer-gate** — a change is merged only after an independent reviewer verdict
+  *and* a green local gate.
+- **human-go** — stack-wide / cross-project / public-facing changes require a human
+  operator's explicit go, in addition to review.
+
+**Crew agents cannot self-approve.** In an agent-driven workflow, the human is the
+second party — an approval an agent could not obtain from a person must never be
+tunneled through another agent. This is enforced mechanically: the approval gate
+keys on an interactive terminal, and a dispatched agent has none.
+
+## Reporting issues
+
+File issues with a minimal reproduction and the output of `rv check`. For anything
+touching a discipline or a gate, describe the *honesty property* you believe is at
+risk — that framing helps triage faster than a feature label.