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

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 and enforced by 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 – Core curriculum vitae data
• article-digest.md – Published content and thought leadership
• config/profile.yml – Structured profile configuration
• modes/_profile.md – Profile-specific mode instructions
• writing-samples/ – Portfolio pieces
• modes/_custom.md – Custom mode definitions (style only)
• 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 – 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 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 carry headers like:

**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. 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. 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, *.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 file contains the evaluation logic that respects the Source-of-Truth Boundary. When processing files, scripts use layer detection functions:

// 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:

# 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:

# 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	Core specification of layers, trust levels, and prohibited actions	Defines the Source-of-Truth Boundary and UX invariants
DATA_CONTRACT.md	Authoritative layer mapping for all scripts	Lists which files belong to User vs. System layers
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	Primary user-authored CV file	Full-trust source for all factual content
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, config/profile.yml, etc.) enjoy full trust and serve as the canonical source for quantitative claims.
• Derived files (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 mandates user intervention before unverified claims enter generated output.
• System files (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 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, 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.

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 explicitly maps which files belong to each layer, ensuring that git pull operations only modify safe system logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}