Add machine-readable onboarding fingerprint (.agents/code-mint-status.json)

jacob-pattern · jacob-pattern · commit bdd2e3fbc5e4 · 2026-04-02T12:59:45.000-06:00
Introduce a committed JSON file that tracks which north-star outcomes
have been proven in a target repository, enabling quick cross-repo
scanning of code-mint onboarding status.

Changes:
- New template: .agents/code-mint-status.json
- meta--onboarding: initialize fingerprint in Prepare Directories,
  update at Phase 1 and Phase 5 boundaries, serialize parallel writes
- All 10 auditor/creator skills: update fingerprint alongside checklist
- meta--skill-creator: new skills inherit the fingerprint convention
- docs/skill-development.md: Status Fingerprint section with update
  rule, scoping, create-if-missing, parallel writes, and vocabulary
- docs/outcomes.md, framework.md, adoption-guide.md,
  onboarding-checklist.md: reference the fingerprint
- AGENTS.md, README.md, CONTRIBUTING.md: repo map and copy commands

Made-with: Cursor
diff --git a/.agents/code-mint-status.json b/.agents/code-mint-status.json
@@ -0,0 +1,14 @@
+{
+  "code_mint": "1.0",
+  "scope": ".",
+  "onboarded_at": null,
+  "last_validated": null,
+  "outcomes": {
+    "validate_current_state": { "status": "Not Started", "date": null },
+    "navigate": { "status": "Not Started", "date": null },
+    "self_test": { "status": "Not Started", "date": null },
+    "smoke_path": { "status": "Not Started", "date": null },
+    "bug_reproduction": { "status": "Not Started", "date": null },
+    "sre_investigation": { "status": "Not Started", "date": null }
+  }
+}
diff --git a/.agents/skills/autonomy--env-auditor/SKILL.md b/.agents/skills/autonomy--env-auditor/SKILL.md
@@ -96,4 +96,4 @@ Write the report to `.agents/reports/autonomy--env-auditor-audit.md`:
 Run `autonomy--env-creator` to remediate findings.
 ```
 
-After writing the report, update `docs/onboarding-checklist.md`. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
+After writing the report, update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `smoke_path` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
diff --git a/.agents/skills/autonomy--env-creator/SKILL.md b/.agents/skills/autonomy--env-creator/SKILL.md
@@ -243,4 +243,4 @@ Update the project's AGENTS.md and/or README to include:
 4. If generation or startup verification fails, keep the old `.env` in place or restore it from the backup before trying again.
 5. If a `.env.example` file exists, keep it as a reference or compatibility file only. Point it to the primary bootstrap path if helpful.
 6. Archive the audit report to `.agents/reports/completed/autonomy--env-auditor-audit-{YYYY-MM-DD}.md`.
-7. Update `docs/onboarding-checklist.md`. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
+7. Update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `smoke_path` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
diff --git a/.agents/skills/autonomy--runtime-auditor/SKILL.md b/.agents/skills/autonomy--runtime-auditor/SKILL.md
@@ -193,4 +193,4 @@ Write the report to `.agents/reports/autonomy--runtime-auditor-audit.md`:
 Run `autonomy--runtime-creator` to remediate findings.
 ```
 
-After writing the report, update `docs/onboarding-checklist.md`. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
+After writing the report, update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `smoke_path` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
diff --git a/.agents/skills/autonomy--runtime-creator/SKILL.md b/.agents/skills/autonomy--runtime-creator/SKILL.md
@@ -124,4 +124,4 @@ If any step still depends on human approval or real cloud setup, document that b
 ## Step 7: Archive
 
 1. Archive the audit report to `.agents/reports/completed/autonomy--runtime-auditor-audit-{YYYY-MM-DD}.md`
-2. Update `docs/onboarding-checklist.md`. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
+2. Update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `smoke_path` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
diff --git a/.agents/skills/autonomy--sre-agent/SKILL.md b/.agents/skills/autonomy--sre-agent/SKILL.md
@@ -243,7 +243,7 @@ If the workflow above doesn't immediately surface the cause, form ranked hypothe
 
 Write a failing test case that reproduces the bug BEFORE proposing any fix. If you cannot reproduce the bug in a test, you do not understand it well enough to fix it.
 
-For onboarding proof, the failing test or deterministic repro recipe is itself the evidence artifact. Capture it in `docs/onboarding-checklist.md` before moving on.
+For onboarding proof, the failing test or deterministic repro recipe is itself the evidence artifact. Capture it in `docs/onboarding-checklist.md` and update `.agents/code-mint-status.json` with the current `bug_reproduction` and `sre_investigation` outcome statuses and dates before moving on.
 
 ## Fix and Confirm
 
diff --git a/.agents/skills/autonomy--sre-auditor/SKILL.md b/.agents/skills/autonomy--sre-auditor/SKILL.md
@@ -172,4 +172,4 @@ Write the report to `.agents/reports/autonomy--sre-auditor-audit.md`:
 Address findings to enable `autonomy--sre-agent` to operate effectively. If tooling or auth is missing, complete the manual install/authentication work first, then re-run `autonomy--sre-auditor`.
 ```
 
-After writing the report, update `docs/onboarding-checklist.md`. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
+After writing the report, update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `sre_investigation` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
diff --git a/.agents/skills/autonomy--test-readiness-auditor/SKILL.md b/.agents/skills/autonomy--test-readiness-auditor/SKILL.md
@@ -131,7 +131,7 @@ Write the report to `.agents/reports/autonomy--test-readiness-auditor-audit.md`:
 Run `autonomy--test-readiness-creator` to remediate findings.
 ```
 
-After writing the report, update `docs/onboarding-checklist.md`. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
+After writing the report, update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `self_test` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
 
 ## Detailed Criteria
 
diff --git a/.agents/skills/autonomy--test-readiness-creator/SKILL.md b/.agents/skills/autonomy--test-readiness-creator/SKILL.md
@@ -107,4 +107,4 @@ Before changing CI behavior, ask for explicit approval if the change will block
 2. Verify per-file test execution works with the documented command.
 3. Confirm test speed meets benchmarks where practical.
 4. Archive the audit report to `.agents/reports/completed/autonomy--test-readiness-auditor-audit-{YYYY-MM-DD}.md`.
-5. Update `docs/onboarding-checklist.md`. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
+5. Update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `self_test` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
diff --git a/.agents/skills/legibility--auditor/SKILL.md b/.agents/skills/legibility--auditor/SKILL.md
@@ -123,7 +123,7 @@ Write the report to `.agents/reports/legibility--auditor-audit.md` using this st
 Run `legibility--enhancer` to collaboratively remediate findings.
 ```
 
-After writing the report, update `docs/onboarding-checklist.md`. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
+After writing the report, update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `navigate` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
 
 ## Detailed Criteria
 
diff --git a/.agents/skills/legibility--enhancer/SKILL.md b/.agents/skills/legibility--enhancer/SKILL.md
@@ -156,7 +156,7 @@ Subdirectory `AGENTS.md` files **override** parent files — they do not merge.
 2. Confirm all build/test commands work by running them.
 3. Summarize which directories received local guidance, which were intentionally deferred as simple, and why.
 4. If a legibility audit report was used, archive it to `.agents/reports/completed/legibility--auditor-audit-{YYYY-MM-DD}.md`.
-5. Update `docs/onboarding-checklist.md`. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
+5. Update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `navigate` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view.
 
 ## Detailed Templates
 
diff --git a/.agents/skills/meta--onboarding/SKILL.md b/.agents/skills/meta--onboarding/SKILL.md
@@ -35,6 +35,7 @@ Use `docs/outcomes.md` for the glossary and `docs/onboarding-checklist.md` as th
 - Active audit reports live in `.agents/reports/*-audit.md`
 - Archived reports live in `.agents/reports/completed/`
 - Outcome tracking lives in `docs/onboarding-checklist.md`
+- Status fingerprint lives in `.agents/code-mint-status.json` (committed to git)
 - Optional skill-to-outcome compatibility lives in `docs/skills-status.md`
 - Phase decisions and approvals live in `.agents/reports/onboarding-summary.md`
 
@@ -85,6 +86,8 @@ Initialize `.agents/reports/onboarding-summary.md` if it does not exist. Use it
 - which proof should happen next
 - the next recommended PR or phase
 
+Initialize `.agents/code-mint-status.json` if it does not already exist. Copy it from the code-mint template and set `scope` to the onboarding scope path relative to the git root (`.` for repo-root onboarding, or the subdirectory path for scoped onboarding). This file is committed to git and serves as the machine-readable fingerprint for cross-repo scanning.
+
 Ensure `.gitignore` keeps the directories but ignores generated report files:
 
 ```gitignore
@@ -192,6 +195,8 @@ Run applicable auditors to understand the current state. These are non-destructi
 
 Once scope is known, Phase 1 auditors may run in parallel because they are read-only. Do not parallelize creator or remediation work in later phases unless the scopes are clearly independent and the user approves.
 
+When auditors run in parallel, **do not** have each auditor update `.agents/code-mint-status.json` individually — concurrent writes to the same file lose data. Instead, defer all fingerprint updates to the single "After Phase 1" step below, which writes all outcome statuses in one pass.
+
 ### After Phase 1
 
 Update `docs/onboarding-checklist.md` with:
@@ -200,6 +205,8 @@ Update `docs/onboarding-checklist.md` with:
 - each remaining outcome marked `Not Started`, `In Progress`, `Blocked`, or `N/A` based on the audit findings
 - the next proof to pursue
 
+Update `.agents/code-mint-status.json`: set `onboarded_at` to today's ISO date, and update each outcome's `status` and `date` to match the checklist.
+
 Present a concise summary to the user:
 
 ```text
@@ -365,10 +372,11 @@ Run each applicable auditor again and compare the new results against the Phase
 ### Step 5.3: Update Tracking
 
 1. Update `docs/onboarding-checklist.md` with final statuses, evidence, and dates.
-2. Optionally update `docs/skills-status.md` if the repo wants the compatibility view.
-3. Archive completed audit reports to `.agents/reports/completed/`.
-4. Update `.agents/reports/onboarding-summary.md` with what changed, what remains manual, unresolved risks, and the next recommended skill or proof.
-5. Ask whether the user wants to create a commit. Do not commit automatically.
+2. Update `.agents/code-mint-status.json`: set `last_validated` to today's ISO date, and update all outcome statuses and dates to their final values.
+3. Optionally update `docs/skills-status.md` if the repo wants the compatibility view.
+4. Archive completed audit reports to `.agents/reports/completed/`.
+5. Update `.agents/reports/onboarding-summary.md` with what changed, what remains manual, unresolved risks, and the next recommended skill or proof.
+6. Ask whether the user wants to create a commit. Do not commit automatically.
 
 ## Activate Ongoing Skills
 
diff --git a/.agents/skills/meta--skill-creator/SKILL.md b/.agents/skills/meta--skill-creator/SKILL.md
@@ -219,7 +219,7 @@ When creating a paired auditor and creator:
 - Report format: Summary, itemized findings with severity (Critical/High/Medium/Low), recommended actions
 - Include: `Next Skill / Step`
 - End with: "Run `{creator-skill-name}` to remediate findings."
-- Update `docs/onboarding-checklist.md` after completion. Optionally refresh `docs/skills-status.md` if the repository keeps the compatibility view.
+- Update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the relevant outcome status and date after completion. Optionally refresh `docs/skills-status.md` if the repository keeps the compatibility view.
 
 ### Creator Skills
 
@@ -228,7 +228,7 @@ When creating a paired auditor and creator:
 - Walk through findings collaboratively with the user (do not auto-generate without human input where domain knowledge is required)
 - Add approval checkpoints before any supervised, destructive, or hard-to-reverse action
 - After remediation, archive the report to `.agents/reports/completed/{name}-audit-{YYYY-MM-DD}.md`
-- Update `docs/onboarding-checklist.md` after completion. Optionally refresh `docs/skills-status.md` if the repository keeps the compatibility view.
+- Update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the relevant outcome status and date after completion. Optionally refresh `docs/skills-status.md` if the repository keeps the compatibility view.
 
 ---
 
diff --git a/AGENTS.md b/AGENTS.md
@@ -20,6 +20,7 @@ When working in this repo:
 | `AGENTS.md` | Concise agent-facing instructions for this repository (this file) |
 | `.agents/skills/` | Portable skills copied into target repositories |
 | `.agents/rules/` | Guidance on project-specific persistent rules |
+| `.agents/code-mint-status.json` | Machine-readable onboarding fingerprint (committed) |
 | `docs/framework.md` | Founding principles and mechanical standards |
 | `docs/outcomes.md` | North-star onboarding outcomes and evidence model |
 | `docs/onboarding-checklist.md` | Canonical outcome checklist template |
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -29,7 +29,7 @@ See `docs/skill-development.md` for the full guide on creating and maintaining s
 
 ## Documentation change checklist (maintainers)
 
-**Single source for outcome vocabulary:** `docs/outcomes.md` is the canonical glossary for outcome names, proof criteria, and primary skill mappings. When you change any of that, edit `docs/outcomes.md` first, then update pointers and checklists in `README.md`, `docs/framework.md`, `docs/onboarding-checklist.md`, `docs/skills-status.md`, and `.agents/skills/meta--onboarding/SKILL.md` as needed so they stay aligned.
+**Single source for outcome vocabulary:** `docs/outcomes.md` is the canonical glossary for outcome names, proof criteria, and primary skill mappings. When you change any of that, edit `docs/outcomes.md` first, then update pointers and checklists in `README.md`, `docs/framework.md`, `docs/onboarding-checklist.md`, `docs/skills-status.md`, `.agents/code-mint-status.json`, and `.agents/skills/meta--onboarding/SKILL.md` as needed so they stay aligned.
 
 After substantive edits to `README.md`, onboarding docs, or the copy bundle, quickly confirm:
 
diff --git a/README.md b/README.md
@@ -97,6 +97,7 @@ git checkout -b chore/code-mint-phase-1-assessment
 git clone https://github.com/patterninc/code-mint.git .code-mint-source
 mkdir -p "$TARGET_SCOPE/.agents/reports" "$TARGET_SCOPE/.agents/reports/completed" "$TARGET_SCOPE/docs"
 cp -RL .code-mint-source/.agents/skills "$TARGET_SCOPE/.agents/"
+cp .code-mint-source/.agents/code-mint-status.json "$TARGET_SCOPE/.agents/"
 cp .code-mint-source/docs/framework.md "$TARGET_SCOPE/docs/"
 cp .code-mint-source/docs/outcomes.md "$TARGET_SCOPE/docs/"
 cp .code-mint-source/docs/onboarding-checklist.md "$TARGET_SCOPE/docs/"
diff --git a/docs/adoption-guide.md b/docs/adoption-guide.md
@@ -14,7 +14,7 @@ The key idea: track progress by proven outcomes, not by how many procedural step
 
 ## Setup
 
-Copy the onboarding bundle into the target repo using the **Quick Start** in the root `README.md` (`TARGET_REPO` / `TARGET_SCOPE`, `git clone` of this library, `cp` of skills and core docs, `.gitignore` for reports). If the target repository already has `.agents/`, `AGENTS.md`, rules, or customized skills, merge deliberately rather than overwriting them.
+Copy the onboarding bundle into the target repo using the **Quick Start** in the root `README.md` (`TARGET_REPO` / `TARGET_SCOPE`, `git clone` of this library, `cp` of skills and core docs, `.agents/code-mint-status.json`, `.gitignore` for reports). If the target repository already has `.agents/`, `AGENTS.md`, rules, or customized skills, merge deliberately rather than overwriting them.
 
 ## What The User Should Understand Immediately
 
@@ -157,6 +157,7 @@ Preserve local `[CUSTOMIZE]` values when adopting upstream changes.
 Designate a Rule Steward or equivalent owner to review changes to:
 
 - `.agents/`
+- `.agents/code-mint-status.json`
 - `AGENTS.md`
 - `SKILL.md`
 - onboarding docs and checklist templates
diff --git a/docs/framework.md b/docs/framework.md
@@ -71,7 +71,7 @@ Work tickets are part of the harness. A vague ticket produces vague output. The
 
 ## Outcome Map
 
-Outcome names, proof criteria, and primary skill mappings are defined in `docs/outcomes.md`. Track progress and evidence in `docs/onboarding-checklist.md`.
+Outcome names, proof criteria, and primary skill mappings are defined in `docs/outcomes.md`. Track progress and evidence in `docs/onboarding-checklist.md`. `.agents/code-mint-status.json` provides a machine-readable index of outcome statuses for cross-repo scanning.
 
 ## Cross-Cutting Standards
 
diff --git a/docs/onboarding-checklist.md b/docs/onboarding-checklist.md
@@ -9,7 +9,8 @@ This file is intended to be copied into the target repository and updated there
 1. Start with `Validate Current State` so the repository has a baseline.
 2. Work toward one proof at a time. Do not try to unlock every outcome at once.
 3. Record evidence each time an outcome changes state.
-4. Revisit the file when the user comes back later. It should be obvious what is done, blocked, or still unproven.
+4. Keep `.agents/code-mint-status.json` in sync with this checklist. It is the machine-readable index; this file is the detailed evidence record.
+5. Revisit the file when the user comes back later. It should be obvious what is done, blocked, or still unproven.
 
 ## Status Key
 
diff --git a/docs/outcomes.md b/docs/outcomes.md
@@ -33,7 +33,7 @@ Every outcome should be tracked with the same evidence fields:
 - `Last Validated`: when the evidence was last refreshed
 - `Notes`: what is still manual, flaky, blocked, approval-gated, or intentionally marked `N/A`
 
-Use `docs/onboarding-checklist.md` as the canonical template for that evidence. For an optional skill-by-skill matrix aligned to outcomes, see [`docs/skills-status.md`](skills-status.md).
+Use `docs/onboarding-checklist.md` as the canonical template for that evidence. `.agents/code-mint-status.json` mirrors outcome statuses as a machine-readable index for cross-repo scanning. For an optional skill-by-skill matrix aligned to outcomes, see [`docs/skills-status.md`](skills-status.md).
 
 ## What "Done" Looks Like
 
diff --git a/docs/skill-development.md b/docs/skill-development.md
