deep-context

Build comprehensive, verified context from a folder. Designed for corpora ≤200 files where full reads are tractable.

Modes

Pick based on user input:

Default to build if mode is ambiguous and .context/ doesn't exist; default to diff if it exists and any file changed; default to ask if user passes a question alongside an unchanged corpus.

Output layout

Output layout

Inside the target folder:

<folder>/.context/
├── INDEX.md              # human-readable summary + verification report
├── DIGEST.md             # one-page actionable TL;DR (written at step 8.5)
├── CHANGES.md            # written by diff mode — what changed since last run
├── CONFLICTS.md          # contradictions between per-file notes (may be empty)
├── GLOSSARY.md           # cross-corpus terms and entities (may be empty)
├── RED_TEAM.md           # adversarial verification findings
├── SELF_TEST.md          # self-test calibration results
├── OMISSIONS.md          # source-derived omission probe results
├── ASK_LOG.md            # append-only log of ask-mode misses (excluded from note integrity hashing)
├── ASK_CONTEXT.md        # rolling multi-turn ask-mode conversation context (last 5 exchanges)
├── manifest.json         # {path, sha256, size, mtime, scanned_at} per file + run metadata
├── index.json            # machine-readable summary (JSON sidecar)
├── server.py             # generated MCP server (written by serve mode only)
└── files/
    └── <relpath>.md      # one note per source file, mirrors source tree

Never write outside .context/. Never modify source files.

Workflow

-1. Domain hint (optional)

If the user passes --domain=<legal|code|sales|research|finance|medical> or the corpus filename/content patterns strongly suggest a domain, load the matching extraction template (small additive section, not a replacement). Domain templates add structured fields to per-file notes. Examples:

• legal: case numbers, court, parties, statute references, dates (DD.MM.YYYY normalized to ISO), monetary amounts, deadlines, cited precedents
• code: language, exports, imports, side effects, test coverage, public API surface
• sales: account, deal stage, ACV, close date, decision-makers, objections
• research: hypothesis, method, sample size, findings, confidence level, citations
• finance: amounts, currency, dates, parties, account/invoice numbers, due dates, status (paid/outstanding)
• medical: diagnoses (de-identified), medications, dosages, dates of service, providers, encounter types — NEVER raw patient identifiers (name, MRN, DOB, SSN, address, phone, email) by default

If no domain hint is provided AND the corpus is mixed, skip domain enrichment and use the generic schema. Domain templates are additive — they don't replace the standard Purpose/Key content/etc. sections.

PHI/PII handling (medical mode — best-effort, NOT a privacy guarantee):

⚠️ Honest disclaimer: Medical-mode redaction is best-effort, not HIPAA-grade de-identification. Combinations of quasi-identifiers (rare diagnosis + date of service + provider name + age + ZIP3) can re-identify a patient even when name/MRN/DOB are removed. If you need certified de-identification (HIPAA Safe Harbor or Expert Determination), use a dedicated tool — not this skill.

When --domain=medical, before any extraction, ask the user exactly once:

"Medical mode persists derived notes under .context/. Default policy:

1. Redact direct identifiers (name, MRN, DOB, SSN, full address, phone, email, account, license, IP, biometric IDs, full-face photo refs, URL → [REDACTED:<type>] tokens).
2. Redact common quasi-identifiers (provider names, exact dates of service → year only, exact ages >89 → [AGE:90+], ZIP → first 3 digits, rare diagnoses → category only).
3. NO verbatim source excerpts in notes — paraphrase only.
4. Final cross-artifact scrub: after all writes, re-scan every file in .context/ for any pattern matching the direct/quasi-identifier regex set; fail the run if anything matches.

Override options:

• Default (recommended): full redaction + scrub as above — best-effort only, NOT certified
• Keep direct identifiers (per-file notes only; DIGEST/GLOSSARY/CONFLICTS/RED_TEAM/SELF_TEST/index.json/OMISSIONS still redact regardless)
• Keep verbatim excerpts (allows quoted source text in per-file notes; same shareable-artifact restriction)
• Disable scrub (NOT recommended — disables the final safety net)"

Default = full redaction + scrub. Even with overrides, DIGEST.md, GLOSSARY.md, CONFLICTS.md, RED_TEAM.md, SELF_TEST.md, OMISSIONS.md, and index.json MUST still redact at the strongest level — those are the most likely artifacts to be shared, pasted, or committed.

Mandatory final scrub — atomic write protocol (cannot be disabled if default policy chosen):

⚠️ Scope of protection: this scrub covers only the files written to .context/. It does NOT protect model inference transcripts, tool call logs, editor history, OS filesystem journals, cloud sync, backup systems, or any storage path outside .context/. If your runtime or storage is not isolated, PHI may have already escaped before the scrub runs. For regulated medical data (HIPAA, GDPR health data), do not use this skill without a fully isolated and compliant runtime — this scrub is a best-effort artifact check, not a compliance boundary.

1. Write ALL output files to a temp directory .context/.tmp-<runid>/ instead of directly to .context/.
2. Run the full regex scrub over .context/.tmp-<runid>/ (every file, direct + quasi-identifier patterns).
3. On PASS: atomically promote by renaming .context/.tmp-<runid>/ → .context/ (or merging into it if .context/ already exists from a prior run, overwriting only changed files).
4. On FAIL: immediately delete .context/.tmp-<runid>/ in its entirety. Abort with error: "Redaction scrub found PHI in <file>: <masked snippet>. Run aborted; temp directory deleted. Note: PHI may still exist in model transcripts or tool logs outside .context/ — check your runtime."
5. Never leave .context/.tmp-<runid>/ behind — delete it on failure, success, or interruption (record cleanup obligation at start of run).

This reduces the window during which unredacted content exists in .context/ artifacts, but makes no claims about other persistence paths.

Record the policy choice + scrub result in .context/REDACTION.md with timestamp, chosen overrides, scrub pass/fail, and the disclaimer above.

0.5. Pre-build token estimation (interactive gate)

Ordering: this step runs AFTER a lightweight metadata-only pre-scan (described below) and BEFORE step 1 (full inventory with SHA-256 hashing). Do a metadata-only walk to get counts; step 1 does the expensive hash-and-cache-diff pass.

1. Metadata-only walk (no file reads, no hashing — e