From bdd2e3fbc5e44e7285a126f3d88d4e1b28874bd7 Mon Sep 17 00:00:00 2001 From: jacob-pattern Date: Thu, 2 Apr 2026 12:59:45 -0600 Subject: [PATCH] Add machine-readable onboarding fingerprint (.agents/code-mint-status.json) 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 --- .agents/code-mint-status.json | 14 +++++ .agents/skills/autonomy--env-auditor/SKILL.md | 2 +- .agents/skills/autonomy--env-creator/SKILL.md | 2 +- .../skills/autonomy--runtime-auditor/SKILL.md | 2 +- .../skills/autonomy--runtime-creator/SKILL.md | 2 +- .agents/skills/autonomy--sre-agent/SKILL.md | 2 +- .agents/skills/autonomy--sre-auditor/SKILL.md | 2 +- .../autonomy--test-readiness-auditor/SKILL.md | 2 +- .../autonomy--test-readiness-creator/SKILL.md | 2 +- .agents/skills/legibility--auditor/SKILL.md | 2 +- .agents/skills/legibility--enhancer/SKILL.md | 2 +- .agents/skills/meta--onboarding/SKILL.md | 16 +++-- .agents/skills/meta--skill-creator/SKILL.md | 4 +- AGENTS.md | 1 + CONTRIBUTING.md | 2 +- README.md | 1 + docs/adoption-guide.md | 3 +- docs/framework.md | 2 +- docs/onboarding-checklist.md | 3 +- docs/outcomes.md | 2 +- docs/skill-development.md | 59 ++++++++++++++++++- 21 files changed, 105 insertions(+), 22 deletions(-) create mode 100644 .agents/code-mint-status.json diff --git a/.agents/code-mint-status.json b/.agents/code-mint-status.json new file mode 100644 index 0000000..2f10071 --- /dev/null +++ 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 index ce1c8da..eceaa9c 100644 --- 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 index 1e9e98a..2d62d51 100644 --- 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 index 7db0fb7..be94083 100644 --- 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 index 7b93379..402675c 100644 --- 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 index 8ab08ad..c1176a3 100644 --- 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 index 164a836..3dbc24c 100644 --- 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 index 812e846..fc00fd8 100644 --- 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 index 3c48ab0..db8cefb 100644 --- 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 index 6ee67b9..56b1a4d 100644 --- 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 index 02cc620..01f255a 100644 --- 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 index 05edf3f..a6b093f 100644 --- 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 index 9cc69cf..03e9aa3 100644 --- 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 index b44eb47..c05ad49 100644 --- 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 index bcd9876..12be9c5 100644 --- 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 index 60562b3..56f85f8 100644 --- 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 index c343a19..21ecf2c 100644 --- 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 index 0579a01..f933d44 100644 --- 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 index c96a3b3..0500a2a 100644 --- 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 index 02846f8..9e4bf6b 100644 --- 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 index 6ef05f9..bf81dd1 100644 --- a/docs/skill-development.md +++ b/docs/skill-development.md @@ -201,6 +201,63 @@ At minimum, every audit report should also make the next handoff obvious: --- +## Status Fingerprint + +Every onboarded repository contains a committed `.agents/code-mint-status.json` file that serves as the machine-readable fingerprint of code-mint onboarding. It is an index for quick scanning, not a replacement for the detailed evidence in `docs/onboarding-checklist.md`. + +### Template + +```json +{ + "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 } + } +} +``` + +### Update Rule + +Whenever a skill updates `docs/onboarding-checklist.md`, also update `.agents/code-mint-status.json` with the relevant outcome's current `status` and `date`. + +**Status values** must be copied exactly from the checklist Status Key — `Not Started`, `In Progress`, `Blocked`, `Proven`, or `N/A`. Case and spacing matter; cross-repo scanners use strict string equality. + +**Dates** must use date-only ISO format: `YYYY-MM-DD`. Never use datetime strings, locale dates, or timestamps. + +**For `N/A` outcomes**, `date` remains `null`. Scanners should not assume every non-`Not Started` row has a non-null date. + +**`Proven` means "last proven with recorded evidence"**, not a live guarantee. If the codebase drifts after proof, the fingerprint does not automatically invalidate. Use `last_validated` and periodic re-audits to detect staleness. + +The `meta--onboarding` skill owns the lifecycle fields: `onboarded_at` is set when Phase 1 completes, and `last_validated` is set when Phase 5 verification runs. + +### Scoping + +The file lives at `.agents/code-mint-status.json` **relative to the onboarding scope root**. For repo-root onboarding this is `./.agents/code-mint-status.json`. For monorepo package onboarding at `packages/api/`, this is `packages/api/.agents/code-mint-status.json`. Skills use bare relative paths and assume the agent's working directory is the scope root. + +### Create If Missing + +`meta--onboarding` initializes the file during its Prepare Directories step. When a skill runs **standalone** (outside the onboarding playbook) and `.agents/code-mint-status.json` does not exist, the skill should create it from the template before updating. Set `scope` to `.` for repo-root or the appropriate path for scoped onboarding. + +### Parallel Writes + +When multiple skills run in parallel (for example Phase 1 auditors), do not have each skill update the JSON individually. Concurrent writes to a single JSON file lose data. Instead, defer fingerprint updates to a single step after all parallel skills complete. `meta--onboarding` handles this in its "After Phase 1" step. + +### Cross-Repo Scanning + +```bash +find . -name "code-mint-status.json" -exec jq '{path: input_filename, proven: [.outcomes[] | select(.status == "Proven")] | length}' {} \; +``` + +--- + ## Evaluating Skills Define success criteria before writing the skill. Evaluate across four dimensions: @@ -238,7 +295,7 @@ Skills rot when the underlying systems change and the instructions do not. - **PR rule:** Any PR that changes a workflow, tool, or convention covered by a skill must update the relevant SKILL.md. - **Version the skill:** Update the skill when the procedures it encodes change. -- **Track status:** After running an auditor or creator skill, update `docs/onboarding-checklist.md` with the evidence and current status. Optionally refresh `docs/skills-status.md` if the repository keeps the compatibility view. +- **Track status:** After running an auditor or creator skill, update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the evidence and current status. Optionally refresh `docs/skills-status.md` if the repository keeps the compatibility view. - **Periodic review:** Run auditor skills quarterly to identify drift. ---