diff --git a/AGENTS.md b/AGENTS.md index f7610d1..da381f0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -This repository follows Tinman Doctrine. +This repository follows project doctrine. ## Agent Operating Rules diff --git a/AI_CONTEXT.md b/AI_CONTEXT.md index b2f74c8..65f7388 100644 --- a/AI_CONTEXT.md +++ b/AI_CONTEXT.md @@ -1,34 +1,33 @@ # AI Context Status: Stable -Last Reviewed: 2026-02-28 +Last Reviewed: 2026-06-04 -Purpose: Provide consistent context to AI tools about identity, naming, and engineering practices. +Purpose: Provide contributor-neutral context to AI tools about repository standards, engineering practices, and safe public project defaults. --- -## Identity +## Public Context Boundary -Primary engineering identity: TinMan -Real/legal identity: George Gil +This file is safe to copy into public repositories. -Public authorship should default to TinMan unless explicitly personal/legal. +Do not add maintainer-private identity, legal identity, account ownership details, private contact details, credentials, private infrastructure names, or recovery information here. ---- +Maintainer-specific preferences belong in a private/local overlay that is not copied into public templates or generated repositories. + +## Authorship and Identity -## Naming Tiers +Follow the repository's visible author, license, contribution, and ownership metadata. -Use `usernames.md` as source of truth. +AI tools must not infer, invent, or add personal maintainer identity information. If authorship or account identity is ambiguous, leave it unchanged and ask a maintainer through the normal project workflow. -Choose identity first: +--- -- TinMan ladder for engineering/public technical authorship. -- TinkerSpace ladder for studio/environment/workspace contexts. +## Naming -Then apply sequential fallback within that ladder only. -Avoid unrelated suffixes. +Follow `naming.md` for repository, code, module, and project naming. ---- +Use project-local naming rules when they are more specific than doctrine defaults. ## Repository Standards @@ -42,7 +41,7 @@ Follow: ## Technology Orientation -Primary domains: +Common domains in this ecosystem include: - Systems programming - Robotics diff --git a/CHANGELOG.md b/CHANGELOG.md index 0b2d7b2..3f1d89c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,15 @@ All notable changes to this template are documented here. +## [Unreleased] + +### Changed +- Refreshed the doctrine snapshot to the contributor-neutral public baseline. +- Added validation that rejects maintainer identity content in public template exports. + +### Removed +- Maintainer identity and username-ladder doctrine files from the public snapshot. + ## [0.1.0] - 2026-02-28 ### Added diff --git a/docs/doctrine/README.md b/docs/doctrine/README.md index 0c02d6c..b9aecb6 100644 --- a/docs/doctrine/README.md +++ b/docs/doctrine/README.md @@ -1,98 +1,16 @@ -# Doctrine +# Doctrine Snapshot -Status: Stable -Last Reviewed: 2026-02-28 +This folder contains a local doctrine snapshot copied from the Doctrine repository. -Centralized engineering doctrine defining identity, naming, coding philosophy, and project standards. +## Source of Truth -This repository acts as a persistent reference for engineering decisions and conventions. +The canonical source remains the Doctrine repository. ---- +## Refresh -## Navigation +Re-run bootstrap when doctrine updates are needed. -### Identity +## Export Boundary -- [Identity Structure](identity.md) -- [Username System](usernames.md) - -### Naming - -- [Naming Conventions](naming.md) - -### Engineering - -- [Coding Principles](coding.md) -- [Project Standards](project-standards.md) -- [C/C++ Template Family Doctrine](cpp-template-family.md) - -### Repository Governance - -- [Repo Governance Doctrine](repo-management.md) -- [Doctrine Governance](doctrine-governance.md) -- [Repo Visibility Note Template](templates/repo-visibility-note-template.md) -- [Doctrine Change Record Template](templates/doctrine-change-record-template.md) - -### AI Usage - -- [AI Context](AI_CONTEXT.md) - -### Meta - -- [Release Notes](RELEASE_NOTES.md) -- [Bootstrap Scripts](tools/README.md) - ---- - -## How To Use Doctrine - -Doctrine is not meant to be read sequentially. - -Use it as a reference: - -- Starting a project → check Project Standards -- Naming something → check Naming -- Writing code → check Coding -- Building template ecosystems → check C/C++ Template Family Doctrine -- Setting identity → check Identity/Usernames -- Using AI → provide AI Context -- Changing policy → check Doctrine Governance + DCR Template -- Preparing repo visibility decision → use Visibility Note Template - ---- - -## Purpose - -Doctrine exists to: - -- Reduce decision fatigue -- Maintain consistency -- Preserve engineering identity -- Standardize project structure -- Improve long-term maintainability - ---- - -## Bootstrap Any Repository - -Use the bootstrap scripts in [`tools/`](tools/) to copy doctrine files into any project repo. - -### macOS / Linux - -```bash -./tools/doctrine-bootstrap.sh /path/to/target-repo -``` - -### Windows PowerShell - -```powershell -.\tools\doctrine-bootstrap.ps1 -TargetRepo C:\path\to\target-repo -``` - -### Windows CMD - -```cmd -tools\doctrine-bootstrap.cmd C:\path\to\target-repo -``` - -Use `--force` (Bash) or `-Force` (PowerShell) to overwrite existing doctrine files. +This snapshot contains the public doctrine baseline only. +Identity-specific files and maintainer-local overlays are intentionally not copied by default. diff --git a/docs/doctrine/doctrine-governance.md b/docs/doctrine/doctrine-governance.md index 6c1dc30..3c93048 100644 --- a/docs/doctrine/doctrine-governance.md +++ b/docs/doctrine/doctrine-governance.md @@ -1,7 +1,7 @@ # Doctrine Governance Status: Draft -Last Reviewed: 2026-02-28 +Last Reviewed: 2026-08-19 ## Purpose @@ -19,10 +19,9 @@ When two doctrine rules conflict, resolve in this order: 1. `repo-management.md` 2. `project-standards.md` 3. `coding.md` -4. `naming.md` -5. `identity.md` -6. `usernames.md` -7. `AI_CONTEXT.md` +4. `export-policy.md` +5. `naming.md` +6. `AI_CONTEXT.md` Conflict handling: @@ -36,6 +35,7 @@ Conflict handling: 2. Edit doctrine files and update `Last Reviewed`. 3. Add a Doctrine Change Record from template: - `templates/doctrine-change-record-template.md` + - Store records under `change-records/`. 4. If the change affects existing repositories, include migration steps and deadline. 5. Update `RELEASE_NOTES.md` for the release that introduces the change. 6. Merge into `develop`, then release using the repo workflow in `repo-management.md`. diff --git a/docs/doctrine/export-policy.md b/docs/doctrine/export-policy.md new file mode 100644 index 0000000..9f0e8e4 --- /dev/null +++ b/docs/doctrine/export-policy.md @@ -0,0 +1,46 @@ +# Doctrine Export Policy + +Status: Stable +Last Reviewed: 2026-08-19 + +## Purpose + +Defines which doctrine files are safe to copy into public repositories, templates, and generated project snapshots. + +## Default Export Rule + +Default doctrine exports must be contributor-neutral and public-safe. + +Exported files must not contain: + +- maintainer legal identity or private account ownership details +- private contact, recovery, credential, infrastructure, or endpoint details +- personal notes that are not required for outside contributors +- project-specific decisions from an unrelated repository + +## Public Export Allowlist + +The default bootstrap tools may export: + +- `templates/AGENTS.md` as `AGENTS.md` +- `AI_CONTEXT.md` +- `coding.md` +- `doctrine-governance.md` +- `export-policy.md` +- `naming.md` +- `project-standards.md` +- `repo-management.md` +- `templates/repo-visibility-note-template.md` +- `templates/doctrine-change-record-template.md` + +## Non-Exported Identity Overlay + +Identity-specific files, account naming ladders, and maintainer-local preferences belong only in a private maintainer overlay. + +They must not be committed to public doctrine, copied into public templates, or generated into downstream repositories by default. If a downstream repository needs such material, document that decision locally and keep it out of reusable public template baselines unless it is contributor-neutral. + +## Contamination Guard + +Bootstrap and CI checks should fail when a public export contains maintainer-private identity markers or other explicitly non-exportable content. + +When a guard fails, remove the non-exportable content from the exported file rather than weakening the guard. diff --git a/docs/doctrine/identity.md b/docs/doctrine/identity.md deleted file mode 100644 index 579cd27..0000000 --- a/docs/doctrine/identity.md +++ /dev/null @@ -1,110 +0,0 @@ -# Identity Structure - -Status: Draft -Last Reviewed: 2026-02-27 - -## Scope - -Defines how identity layers are used across platforms, projects, accounts, environments, and digital infrastructure. - -## Overview - -Three identity layers exist with distinct responsibilities. -They represent role separation, not different personas. - ---- - -## George Gil - -Used for: -- Legal matters -- University / academic systems -- Employment / contracts -- Financial accounts -- Government services -- Personal infrastructure accounts -- Social life platforms -- Official registrations -- Account ownership where legal identity matters - -Personal infrastructure includes: -- Apple ID -- Google personal account -- Microsoft personal account -- Streaming services -- Banking -- Insurance -- Shopping platforms -- Cloud storage accounts -- Domain ownership -- GitHub account ownership/login - -Rule: -If the platform represents the real person legally, financially, personally, or for long-term account ownership/security, use George Gil. - ---- - -## TinMan - -Used for: -- Software authorship -- GitHub and development platforms -- Engineering discussions -- Technical communities -- Package authorship -- Commit authorship -- Technical branding -- Public engineering presence - -Rule: -If the context represents engineering output or technical authorship, use TinMan. - -Notes: -- GitHub public identity uses TinMan. -- Git commit identity uses TinMan. -- Account ownership may still belong to George Gil internally. - ---- - -## TinkerSpace - -Used for: -- Creative environments -- Studio-like systems -- Home automation naming for TinkerSpace-related physical spaces -- Workshop naming -- Content creation spaces -- Project ecosystems - -Rule: -If referring to a space, environment, or studio context, use TinkerSpace. - ---- - -## Email Usage - -Private email: -- Personal infrastructure -- Account ownership -- Security and recovery -- Financial/legal services -- GitHub account login - -Public email: -- Developer/public contact -- Open source contact -- Technical communication - -Commit email: -- Prefer GitHub noreply -- Otherwise public developer email -- Never private email - ---- - -## Separation Rule - -Do not mix identity layers unnecessarily. - -Each platform must clearly map to one primary identity layer, -even if legal ownership differs internally. \ No newline at end of file diff --git a/docs/doctrine/naming.md b/docs/doctrine/naming.md index ff07ec6..bcf29bf 100644 --- a/docs/doctrine/naming.md +++ b/docs/doctrine/naming.md @@ -1,7 +1,7 @@ # Naming Conventions Status: Draft -Last Reviewed: 2026-02-27 +Last Reviewed: 2026-06-04 ## Scope @@ -13,7 +13,7 @@ Applies to repositories, code, modules, and project naming. - Avoid randomness. - Avoid numbers unless technically required. - Prefer clarity over cleverness. -- Avoid mixing identity layers in names. +- Avoid mixing unrelated brand, product, account, and environment naming scopes. --- @@ -25,9 +25,9 @@ Applies to repositories, code, modules, and project naming. - Avoid vague names. Examples: -tinman-portfolio -frmakekit-engine -trenex-runtime +- example-cli +- render-core +- workflow-service --- @@ -52,7 +52,7 @@ SharedMemoryPort --- -## Studio / Space Naming +## Product / Space Naming -- Use TinkerSpace only for environments. -- Do not combine TinMan and TinkerSpace in the same naming scope. \ No newline at end of file +- Use environment or workspace names only for environment/workspace repositories. +- Do not combine product, organization, maintainer, and workspace names in the same naming scope unless the repository explicitly documents that convention. diff --git a/docs/doctrine/project-standards.md b/docs/doctrine/project-standards.md index e5784f8..a04f9d9 100644 --- a/docs/doctrine/project-standards.md +++ b/docs/doctrine/project-standards.md @@ -1,11 +1,11 @@ # Project Standards Status: Stable -Last Reviewed: 2026-02-28 +Last Reviewed: 2026-06-04 ## Purpose -Defines structural standards applied to all personal engineering repositories. +Defines structural standards applied to project repositories. These standards reduce decision fatigue and ensure consistency across projects. These are not suggestions — they are defaults unless a project has a strong reason to differ. diff --git a/tools/validate-template.sh b/tools/validate-template.sh index 41860b2..72d027e 100755 --- a/tools/validate-template.sh +++ b/tools/validate-template.sh @@ -79,7 +79,7 @@ check_required_files() { "docs/doctrine/README.md" "docs/doctrine/coding.md" "docs/doctrine/doctrine-governance.md" - "docs/doctrine/identity.md" + "docs/doctrine/export-policy.md" "docs/doctrine/naming.md" "docs/doctrine/project-standards.md" "docs/doctrine/repo-management.md" @@ -122,6 +122,15 @@ check_markdown_parse_sanity() { done < <(cd "$ROOT_DIR" && rg --files -g '*.md') } +check_public_export_boundary() { + local matches + matches="$(cd "$ROOT_DIR" && rg -n -i '(TinMan|LooseWire|TinkerSpace|George Gil|Primary engineering identity|Real/legal identity)' AGENTS.md AI_CONTEXT.md docs/doctrine 2>/dev/null || true)" + if [[ -n "$matches" ]]; then + core_fail "Public doctrine snapshot contains maintainer identity content" + printf '%s\n' "$matches" + fi +} + check_local_markdown_links() { local rel while IFS= read -r rel; do @@ -268,6 +277,7 @@ run_core() { check_required_files check_doc_structure check_markdown_parse_sanity + check_public_export_boundary run_python_core_checks if [[ $core_errors -gt 0 ]]; then