Portable Paths and Workstation Privacy¶

Parent contract: Bluefly Engineering Execution Contract

Document role: Human-readable explanation and portable-notation reference for an already-enforced rule. This file is not an independent policy authority.

Invariant¶

PERSONAL_FILESYSTEM_INFORMATION
MUST NOT CROSS
WORKSTATION -> GIT

A Git repository must never encode the developer's workstation filesystem topology. Local filesystem layout is runtime/operator context, not source-controlled project information.

There is no documentation exception.

Policy authority (enforcement)¶

Layer	Owner	Role
Enforcement (authoritative)	`blueflyio/security-policies`	Group-wide GitLab Security Policies — tracking issue #24
Active policy	`repository-portability-new-debt`	Pipeline execution policy; stage `.pipeline-policy-pre`; `allow_failure: false`
Implementation	`blueflyio/gitlab_components`	Shared checker script + reusable `repository-portability` component
This document	BluCity-Docs	Explanation and portable notation only — does not create a second control plane

Do not treat BluCity-Docs prose or per-repo convention as enforcement. The policy project blocks newly committed workstation-root violations estate-wide. CI does not print offending paths into logs.

Enforcement phases¶

Phase	Gate	Status
1 — New debt	Block newly introduced personal workstation paths in MR/default-branch commits	ACTIVE (pipeline 2798709723 / job 16162355786 verified)
2 — Zero HEAD	Entire tracked default-branch HEAD contains zero prohibited patterns	PENDING — issue #24 stays open until estate audit 524 → 0

When phase 2 closes, tighten from “block new violations” to “entire tracked HEAD must contain zero violations.”

Forbidden in Git¶

Any committed literal path that encodes personal workstation identity or layout, including shapes such as:

macOS personal home: Users/<real-operator-username>/...
macOS Sites topology: Users/<real-operator-username>/Sites/...
Linux personal home: home/<real-personal-user>/...
Windows personal home: Users\<name>\...

Write these as prose or split tokens so committed docs do not contain the absolute-root prefixes the portability checker blocks. Prefer naming the class (PERSONAL_HOME, PERSONAL_SITES_ROOT) rather than spelling a real filesystem root.

Also forbidden: any resolved value of a portable token (for example committing the output of echo "${HOME}/...").

Governed infrastructure exception (narrow)¶

Committed paths belonging to governed runtime identities on infrastructure hosts are allowed only when required by an infrastructure contract and documented as such. Example class: Oracle service paths under [ORACLE-HOME]/ or [ORACLE-OPT-ROOT]/ when the contract names that host role explicitly.

Personal Mac home directories are never in this exception class.

Required portable representation¶

Prose and committed documentation¶

Use square-bracket semantic tokens (canonical committed-doc notation):

[HOME]
[WORKSPACE-ROOT]
[PROJECT-ROOT]
[PROJECT-PATH]
[WORKTREE-ROOT]
[REPO-ROOT]
[CONFIG-ROOT]
[DATA-ROOT]
[CITY-ROOT]

Also allowed:

Repository-relative paths (no personal home prefix)
$HOME only where the location is genuinely a standard per-user or per-tool location

Examples:

[WORKSPACE-ROOT]/BluCity
[WORKSPACE-ROOT]/worktrees/<repo>
[PROJECT-ROOT]/deploy/mac
[REPO-ROOT]/.gc/site.toml
deploy/mac/site-rigs.toml
rigs/<name>

Do not commit literal personal-home or personal-Sites topology. Use [WORKSPACE-ROOT] / [HOME] tokens instead.

Executable shell examples¶

Use environment variables only where the text is meant to be run:

"${HOME}/${PROJECT_PATH}"
"${WORKSPACE_ROOT}/BluCity"
"${PROJECT_ROOT}/deploy/mac/install-site-bindings.sh"

Never commit the expanded result.

Mac / site binding model¶

Tracked source contains:

rig name
logical repository identity
relative or project-independent metadata

Tracked source must not contain:

personal absolute checkout path
username
home directory
developer-specific workspace root

Machine-local absolute paths belong in generated, untracked runtime projection (for example .gc/site.toml), resolved by deploy/bootstrap from portable source plus local environment:

TRACKED_SOURCE
        ↓
portable logical rig declaration
        ↓
environment resolver (CITY_ROOT, WORKSPACE_ROOT, …)
        ↓
UNTRACKED machine-local site binding
        ↓
absolute local path

Relative paths inside a city checkout (for example rigs/<name> under [CITY-ROOT]) are portable when they are relative to a declared root, not to a personal home directory.

Agent memory and continual learning¶

Agent memory, continual-learning exports, transcript processing, and generated organizational docs obey the same boundary.

A path may be used locally at runtime to locate files. It must not be promoted into Git-tracked shared knowledge.

Receipt fields¶

Population audits that certify estate-wide compliance must report:

PERSONAL_PATH_POLICY=ENFORCED
REPOS_SCANNED=
TRACKED_VIOLATIONS_FOUND=
TRACKED_VIOLATIONS_FIXED=
HISTORICAL_OCCURRENCES=
LITERAL_PERSONAL_HOME_PREFIX_IN_TRACKED_HEADS=

Acceptance for phase 2 (estate certification):

LITERAL_PERSONAL_HOME_PREFIX_IN_TRACKED_HEADS=0
INDEXED_EXISTING_OCCURRENCES=0

Coverage must be complete or the receipt must use certification: REFUSED_UNKNOWN_COVERAGE per Evidence Reporting Standard.