# Understanding the Source-of-Truth Boundary in CareerOps: A Technical Trust Model Guide

> Explore the Source-of-Truth Boundary in CareerOps. Learn how this technical trust model separates user data from system files to ensure verified output and enhance platform integrity.

- Repository: [Santiago Fernández de Valderrama/career-ops](https://github.com/santifer/career-ops)
- Tags: architecture
- Published: 2026-08-22

---

**The Source-of-Truth Boundary in CareerOps is a strict architectural layer that separates user-authored primary files (full trust) from derived system files (partial trust), ensuring only verified personal data generates user-facing output.**

CareerOps implements a novel **Source-of-Truth Boundary** that protects personal data integrity by strictly separating every file into distinct trust layers. This boundary, defined in [`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/AGENTS.md) and enforced by [`DATA_CONTRACT.md`](https://github.com/santifer/career-ops/blob/main/DATA_CONTRACT.md), guarantees that quantitative claims only propagate from verified user-authored sources. Understanding this trust model is essential for safely extending the repository without corrupting factual content.

## The Two-Layer Architecture

CareerOps organizes data into two distinct layers that determine how content feeds into generated CVs, cover letters, and interview preparations.

### Primary / User-Authored Layer

The **Primary layer** contains full-trust ground truth for all factual claims. Files in this category are considered canonical sources, and statements written here are taken as verified fact.

**Files with Full Trust:**
- [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) – Core curriculum vitae data
- [`article-digest.md`](https://github.com/santifer/career-ops/blob/main/article-digest.md) – Published content and thought leadership
- [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml) – Structured profile configuration
- [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) – Profile-specific mode instructions
- `writing-samples/` – Portfolio pieces
- [`modes/_custom.md`](https://github.com/santifer/career-ops/blob/main/modes/_custom.md) – Custom mode definitions (style only)
- [`voice-dna.md`](https://github.com/santifer/career-ops/blob/main/voice-dna.md) – Voice and tone specifications (style only)

Quantitative data originating in these files—such as salary figures, employment dates, or project metrics—flows directly into generated output without verification overhead.

### Derived / Accumulated Layer

The **Derived layer** contains narrative-only content where numbers are **not** automatically trusted. These files accumulate interview preparation materials and narrative adaptations.

**Files with Partial Trust:**
- [`interview-prep/story-bank.md`](https://github.com/santifer/career-ops/blob/main/interview-prep/story-bank.md) – STAR method stories
- `interview-prep/{company-role}.md` – Role-specific interview notes

Any quantified claim in derived files must carry an explicit provenance marker. Without this marker, the claim receives the **`derived-unverified`** status and will not emit as solid fact.

## How the Trust Model Works

The CareerOps trust model operates through five strict enforcement mechanisms that prevent data corruption during repository updates.

### Primary Files as the Sole Source of Truth

Only **Primary layer** files serve as the canonical source for quantitative claims. When `story-provenance-check.mjs` encounters a numeric assertion, it traces the claim to its origin. If the source resolves to [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) or another primary file, the system treats the statement as verified and copies it verbatim into generated documents.

### Derived Files and Provenance Markers

Derived files contribute narrative phrasing and qualitative content, but quantified claims require **provenance markers**. The `story-provenance-check.mjs` utility validates that numeric claims in [`interview-prep/story-bank.md`](https://github.com/santifer/career-ops/blob/main/interview-prep/story-bank.md) carry headers like:

```markdown
**Provenance:** source: cv.md | user-stated 2024-08-22 | derived-unverified

```

When `hasProvenanceMarker(filePath)` returns true, the system safely includes the quantified claim with attribution. Without this marker, the claim remains flagged.

### Confirmation UX for Unverified Claims

When workflows encounter `derived-unverified` claims, CareerOps surfaces the discrepancy to the user according to the "Confirmation UX invariant" specified in [`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/AGENTS.md). The system presents four resolution options:

1. Confirm the number as accurate
2. Provide the correct figure
3. Mark the content as narrative-only
4. Select "I don't know," which appends a `user-cannot-confirm` tag

This invariant ensures that no unverified numeric claim silently enters generated application materials.

### Auto-Memory Limitations

The hidden auto-memory store (located at `~/.claude/...`) maintains style preferences and process state but **never stores factual claims**. All factual content must reside in the user-layer files listed in [`DATA_CONTRACT.md`](https://github.com/santifer/career-ops/blob/main/DATA_CONTRACT.md). This architectural constraint prevents "drift" where system-generated summaries might be mistaken for primary source material.

### System File Safety

**System files**—including [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md), `*.mjs` scripts, and documentation—are safe to overwrite during repository updates. These files never contribute directly to user-facing content; they provide only the logic that reads primary and derived layers. This separation ensures that `git pull` operations cannot accidentally corrupt personal career data.

## Implementing the Boundary in Code

The [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) file contains the evaluation logic that respects the Source-of-Truth Boundary. When processing files, scripts use layer detection functions:

```javascript
// In a mode (e.g., oferta.md) you might see:
if (isPrimaryFile(filePath)) {
  // use the fact as-is
  output += readFile(filePath);
} else if (hasProvenanceMarker(filePath)) {
  // safe to include the quantified claim
  output += annotateWithProvenance(readFile(filePath));
} else {
  // flag for user confirmation
  output += "[UNVERIFIED NUMERIC CLAIM – please confirm]";
}

```

To verify that numeric claims in your story bank carry proper provenance:

```bash

# Example: Verify that a numeric claim in story-bank.md is trusted

node story-provenance-check.mjs --summary

```

Adding a new STAR story with proper provenance tracking:

```bash

# Adding a new STAR story (derived) with provenance:

echo "**Provenance:** source: cv.md | user-stated 2024-08-22 | derived-unverified" >> interview-prep/story-bank.md

```

## Key Files Defining the Boundary

| File | Role in the Boundary | Trust Function |
|------|----------------------|----------------|
| [`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/AGENTS.md) | Core specification of layers, trust levels, and prohibited actions | Defines the Source-of-Truth Boundary and UX invariants |
| [`DATA_CONTRACT.md`](https://github.com/santifer/career-ops/blob/main/DATA_CONTRACT.md) | Authoritative layer mapping for all scripts | Lists which files belong to User vs. System layers |
| [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) | System-layer evaluation logic | Provides the validation code that respects the boundary |
| `story-provenance-check.mjs` | Provenance enforcement utility | Implements verification steps for derived numeric claims |
| [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md) | Primary user-authored CV file | Full-trust source for all factual content |
| [`interview-prep/story-bank.md`](https://github.com/santifer/career-ops/blob/main/interview-prep/story-bank.md) | Derived story repository | Narrative source requiring provenance for numeric claims |

## Summary

- The **Source-of-Truth Boundary** strictly separates CareerOps files into Primary (user-authored) and Derived (system-accumulated) layers.
- **Primary files** ([`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md), [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml), etc.) enjoy full trust and serve as the canonical source for quantitative claims.
- **Derived files** ([`interview-prep/story-bank.md`](https://github.com/santifer/career-ops/blob/main/interview-prep/story-bank.md), etc.) require explicit provenance markers for numeric data or receive `derived-unverified` status.
- The **Confirmation UX invariant** in [`AGENTS.md`](https://github.com/santifer/career-ops/blob/main/AGENTS.md) mandates user intervention before unverified claims enter generated output.
- **System files** ([`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md), `*.mjs` scripts) are stateless logic providers that can be safely updated without risking personal data integrity.
- The `story-provenance-check.mjs` utility automates compliance verification for the trust model.

## Frequently Asked Questions

### What happens if I don't add a provenance marker to a number in my story bank?

Without a provenance marker, any numeric claim in a derived file like [`interview-prep/story-bank.md`](https://github.com/santifer/career-ops/blob/main/interview-prep/story-bank.md) is automatically classified as `derived-unverified`. The system will flag this claim for user confirmation before including it in generated CVs or cover letters, displaying "[UNVERIFIED NUMERIC CLAIM – please confirm]" in the output.

### Can I store factual claims in the auto-memory or system modes?

No. According to the CareerOps trust model, the auto-memory store (`~/.claude/...`) and system files ([`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md), etc.) are explicitly prohibited from storing factual claims. These locations may only hold style preferences, process state, and execution logic. All factual content must reside in the Primary layer files listed in [`DATA_CONTRACT.md`](https://github.com/santifer/career-ops/blob/main/DATA_CONTRACT.md).

### How does CareerOps prevent repository updates from corrupting my personal data?

CareerOps enforces a strict separation between **User layer** files (containing your personal career data) and **System layer** files (containing executable scripts and documentation). System files are designed to be overwritten during updates, while User layer files are protected by the Source-of-Truth Boundary. The [`DATA_CONTRACT.md`](https://github.com/santifer/career-ops/blob/main/DATA_CONTRACT.md) explicitly maps which files belong to each layer, ensuring that `git pull` operations only modify safe system logic.