patterninc · Jacob Miller (jacob-pattern) · Apr 3, 2026 · Apr 3, 2026
diff --git a/.agents/skills/autonomy--runtime-auditor/SKILL.md b/.agents/skills/autonomy--runtime-auditor/SKILL.md
@@ -130,7 +130,9 @@ Record which steps would succeed, which are blocked, and which require human dec
 
 ## Output
 
-Ensure the report directories exist: `mkdir -p .agents/reports .agents/reports/completed`
+Ensure the report directories exist: `mkdir -p .agents/reports/completed && touch .agents/reports/.gitkeep .agents/reports/completed/.gitkeep`
+
+Ensure `.gitignore` ignores generated report contents while preserving the directories with their `.gitkeep` files.
 
 Write the report to `.agents/reports/autonomy--runtime-auditor-audit.md`:
 

diff --git a/.agents/skills/meta--skill-creator/references/skill-template.md b/.agents/skills/meta--skill-creator/references/skill-template.md
@@ -53,7 +53,10 @@ Check against these criteria:
 {For auditors:}
 Write the report to `.agents/reports/{skill-name}-audit.md` using the format defined in `docs/skill-development.md`.
 
-Ensure `.agents/reports/` and `.agents/reports/completed/` exist with `.gitkeep` files, and ensure generated report files are ignored by `.gitignore`.
+Ensure the report directory exists: `mkdir -p .agents/reports/completed && touch .agents/reports/.gitkeep .agents/reports/completed/.gitkeep`
+
+Ensure `.gitignore` ignores generated report contents while preserving the directories with their `.gitkeep` files.
+
 Include `Next Skill / Step`.
 
 {For creators:}

diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md
@@ -0,0 +1,25 @@
+---
+name: Bug report
+about: Report incorrect guidance, broken references, or issues with the onboarding flow
+---
+
+## What happened?
+
+<!-- Describe the problem. What did you observe? -->
+
+## What did you expect?
+
+<!-- What should have happened instead? -->
+
+## Which skill, doc, or template is affected?
+
+<!-- For example: autonomy--runtime-auditor, docs/adoption-guide.md, Quick Start copy commands -->
+
+## Steps to reproduce
+
+<!-- If applicable, describe how to trigger the issue. -->
+
+## Notes
+
+- For **security-sensitive** concerns (unsafe guidance, secrets), use the process in `SECURITY.md` at the repository root instead of posting exploit details here.
+- See `CONTRIBUTING.md` at the repository root for conventions and review expectations.
diff --git a/.github/workflows/markdown-links.yml b/.github/workflows/markdown-links.yml
@@ -19,6 +19,7 @@ jobs:
       - name: Check links
         uses: lycheeverse/lychee-action@v2
         with:
+          fail: true
           args: >-
             --verbose
             --no-progress

diff --git a/README.md b/README.md
@@ -4,20 +4,6 @@ Code-mint is the **source repository** for harness-engineering documentation, sk
 
 This repository is reference material, not an application. The actual onboarding work happens inside the target repository that adopts these assets. Do not try to build or run code-mint itself.
 
-## Instructions To Use
-
-Navigate to your target codebase, and tell an agent operating within that codebase:
-
-```text
-Use https://github.com/patterninc/code-mint as the canonical source for onboarding this repository for AI-first development. Follow its instructions, do not overwrite existing agent instructions blindly, start in assessment-first mode, keep `docs/onboarding-checklist.md` updated as the system of record, and stop for approval before remediation.
-```
-
-If you are applying it to a directory within a larger repository, also specify the onboarding scope:
-
-```text
-Onboarding scope: [path relative to repo root, for example `apps/my-service`]. Treat onboarding paths as relative to that directory, and also read the repo root `README.md` plus any `README.md` files along the path to that scope.
-```
-
 ## Three pillars
 
 Harness work here is organized around three ideas. The [six outcomes](#outcome-map) below are the concrete proof model.
@@ -64,16 +50,21 @@ flowchart TD
     Activate[ActivateOngoingSkills]
 
     StartHere --> SeeOutcomes --> CopyAssets --> Baseline --> Checklist
-    Checklist --> NavigateProof
-    Checklist --> TestProof
-    Checklist --> RuntimeProof
-    Checklist --> BugProof
-    Checklist --> SreProof
-    NavigateProof --> Activate
-    TestProof --> Activate
-    RuntimeProof --> Activate
-    BugProof --> Activate
-    SreProof --> Activate
+    Checklist --> NavigateProof --> TestProof --> RuntimeProof --> BugProof --> SreProof --> Activate
+```
+
+## Instructions To Use
+
+Navigate to your target codebase, and tell an agent operating within that codebase:
+
+```text
+Use https://github.com/patterninc/code-mint as the canonical source for onboarding this repository for AI-first development. Follow its instructions, do not overwrite existing agent instructions blindly, start in assessment-first mode, keep `docs/onboarding-checklist.md` updated as the system of record, and stop for approval before remediation.
+```
+
+If you are applying it to a directory within a larger repository, also specify the onboarding scope:
+
+```text
+Onboarding scope: [path relative to repo root, for example `apps/my-service`]. Treat onboarding paths as relative to that directory, and also read the repo root `README.md` plus any `README.md` files along the path to that scope.
 ```
 
 ## Quick Start

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,14 @@
+# Docs
+
+These files support the code-mint onboarding framework. Read them in this order:
+
+| File | Purpose | When to read |
+|---|---|---|
+| [`outcomes.md`](outcomes.md) | North-star outcomes and evidence model | First — understand what onboarding proves |
+| [`onboarding-checklist.md`](onboarding-checklist.md) | Canonical outcome tracker template | Copy into target repo; update throughout onboarding |
+| [`adoption-guide.md`](adoption-guide.md) | Detailed operator workflow | When you need step-by-step onboarding guidance |
+| [`framework.md`](framework.md) | Founding principles and mechanical standards | When you need the conceptual foundation |
+| [`skills-status.md`](skills-status.md) | Skill-to-outcome compatibility matrix | When you need a skill-level activity view |
+| [`skill-development.md`](skill-development.md) | How to create and maintain skills | When contributing new skills |
+
+The root [`README.md`](../README.md) is the primary entry point. Start there if you have not read it yet.
diff --git a/docs/adoption-guide.md b/docs/adoption-guide.md
@@ -25,9 +25,11 @@ Before asking the user to do much setup work, the onboarding flow should make th
 Open the folder that matches your onboarding scope when you can. If you work from the git repository root instead, state the scope in the prompt so paths for `docs/`, `.agents/`, and `AGENTS.md` stay unambiguous. Example:
 
 ```text
-Use the meta--onboarding skill to assess this repository for AI-first development, keep docs/onboarding-checklist.md updated as the system of record, summarize the findings, and wait for approval before making changes.
+Use the meta--onboarding skill to onboard this repository for AI-first development, keep docs/onboarding-checklist.md updated as the system of record, summarize the findings, and wait for approval before making changes.
 ```
 
+The prompt says "wait for approval before making changes" to reinforce assessment-first mode. Phase 1 runs read-only auditors; remediation begins only after the user reviews the baseline.
+
 When onboarding only a package or subdirectory, add a line such as: `Onboarding scope: [path relative to repo root]. Treat paths as relative to that directory. Also read the git repository root README.md and any README.md files along the path from the repo root to that scope for repo-wide setup, deploy, CI, or environment notes that may not exist under the scope.`
 
 ## Outcome-Driven Sequence

diff --git a/docs/onboarding-checklist.md b/docs/onboarding-checklist.md
@@ -24,30 +24,90 @@ This file is intended to be copied into the target repository and updated there
 
 ## Outcome Tracker
 
-| Outcome | Why It Matters | Status | Evidence | Exact Check | Last Validated | Notes |
-|---|---|---|---|---|---|---|
-| `Validate Current State` | The agent can assess the repo before making changes. | Not Started | applicable audit reports plus `.agents/reports/onboarding-summary.md` | Run all applicable Phase 1 auditors and summarize what is working, blocked, risky, and next to prove. | — | Establish this first. |
-| `Navigate` | The agent can explain where to work and why modules exist. | Not Started | `AGENTS.md`, subdirectory `AGENTS.md`, sample repo explanation | Ask the agent to explain the repo map and target module for a sample task, then record the grounded answer. | — | Favor durable repo-local docs over chat-only explanations. |
-| `Self-Test` | The agent can run the smallest relevant automated checks and trust the result. | Not Started | exact test command, test file, CI reference | Run one targeted test path for a real module or behavior change and capture the pass/fail signal. | — | Record what is still manual or flaky. |
-| `Smoke Path` | The agent can prove the runtime is meaningfully usable. | Not Started | runtime guide, screenshot, log excerpt, curl output | Execute one trusted, non-destructive smoke path with documented prerequisites, steps, stop conditions, and success signal. | — | Smallest safe check wins. |
-| `Bug Reproduction` | The agent can reproduce a reported issue before proposing a fix. | Not Started | failing test, script, or repro recipe linked to the issue | Turn one real bug report into a deterministic failing case another person or agent can rerun. | — | The repro is the proof. |
-| `SRE Investigation` | The agent can inspect logs, metrics, traces, CI, or infra evidence. | Not Started | investigation note, query output, linked dashboard/log command | Gather operational evidence, produce a ranked hypothesis, and record the next actions or `N/A` reason. | — | Mark `N/A` only when no operational tooling exists. |
-
-## Evidence Log Template
-
-Copy one section per outcome as it moves forward.
-
-```markdown
-### Outcome: [name]
-- Status: [Not Started / Blocked / In Progress / Proven / N/A]
-- Date: [YYYY-MM-DD]
-- Owner: [human or agent]
-- Exact Check: [command, prompt, walkthrough, or scenario]
-- Evidence: [report path, screenshot path, failing test, notes]
-- What Passed: [short summary]
-- What Is Still Missing: [short summary]
-- Next Action: [single next step]
-```
+| Outcome | Status | Last Validated |
+|---|---|---|
+| `Validate Current State` | Not Started | — |
+| `Navigate` | Not Started | — |
+| `Self-Test` | Not Started | — |
+| `Smoke Path` | Not Started | — |
+| `Bug Reproduction` | Not Started | — |
+| `SRE Investigation` | Not Started | — |
+
+## Outcome Details
+
+Copy one section per outcome as it moves forward. Each section is the detailed evidence record for that outcome.
+
+### Validate Current State
+
+The agent can assess the repo before making changes.
+
+- **Status:** Not Started
+- **Date:** —
+- **Evidence:** applicable audit reports plus `.agents/reports/onboarding-summary.md`
+- **Exact Check:** Run all applicable Phase 1 auditors and summarize what is working, blocked, risky, and next to prove.
+- **What Passed:** —
+- **What Is Still Missing:** —
+- **Next Action:** Establish this first.
+
+### Navigate
+
+The agent can explain where to work and why modules exist.
+
+- **Status:** Not Started
+- **Date:** —
+- **Evidence:** `AGENTS.md`, subdirectory `AGENTS.md`, sample repo explanation
+- **Exact Check:** Ask the agent to explain the repo map and target module for a sample task, then record the grounded answer.
+- **What Passed:** —
+- **What Is Still Missing:** —
+- **Next Action:** Favor durable repo-local docs over chat-only explanations.
+
+### Self-Test
+
+The agent can run the smallest relevant automated checks and trust the result.
+
+- **Status:** Not Started
+- **Date:** —
+- **Evidence:** exact test command, test file, CI reference
+- **Exact Check:** Run one targeted test path for a real module or behavior change and capture the pass/fail signal.
+- **What Passed:** —
+- **What Is Still Missing:** —
+- **Next Action:** Record what is still manual or flaky.
+
+### Smoke Path
+
+The agent can prove the runtime is meaningfully usable.
+
+- **Status:** Not Started
+- **Date:** —
+- **Evidence:** runtime guide, screenshot, log excerpt, curl output
+- **Exact Check:** Execute one trusted, non-destructive smoke path with documented prerequisites, steps, stop conditions, and success signal.
+- **What Passed:** —
+- **What Is Still Missing:** —
+- **Next Action:** Smallest safe check wins.
+
+### Bug Reproduction
+
+The agent can reproduce a reported issue before proposing a fix.
+
+- **Status:** Not Started
+- **Date:** —
+- **Evidence:** failing test, script, or repro recipe linked to the issue
+- **Exact Check:** Turn one real bug report into a deterministic failing case another person or agent can rerun.
+- **What Passed:** —
+- **What Is Still Missing:** —
+- **Next Action:** The repro is the proof.
+
+### SRE Investigation
+
+The agent can inspect logs, metrics, traces, CI, or infra evidence.
+
+- **Status:** Not Started
+- **Date:** —
+- **Evidence:** investigation note, query output, linked dashboard/log command
+- **Exact Check:** Gather operational evidence, produce a ranked hypothesis, and record the next actions or `N/A` reason.
+- **What Passed:** —
+- **What Is Still Missing:** —
+- **Next Action:** Mark `N/A` only when no operational tooling exists.
 
 ## Suggested Evidence Patterns
 

diff --git a/docs/skill-development.md b/docs/skill-development.md
@@ -170,6 +170,8 @@ The reports directory itself should stay in version control, but generated repor
 | `autonomy--test-readiness-auditor` | `autonomy--test-readiness-creator` |
 | `legibility--auditor` | `legibility--enhancer` |
 
+`autonomy--sre-auditor` is intentionally not paired with a creator. Its remediation path routes to `autonomy--sre-agent`, an operational investigation tool rather than a remediation workflow. The auditor verifies tooling access; the agent uses that access to investigate real issues.
+
 ### Report Format
 
 Auditor reports should follow this structure:

diff --git a/docs/skills-status.md b/docs/skills-status.md
@@ -15,6 +15,8 @@
 | `Needs Refresh` | The repo changed enough that the prior result may be stale. |
 | `N/A` | The skill does not apply to this repository. |
 
+This status vocabulary is intentionally different from `docs/onboarding-checklist.md`. The checklist tracks **outcome-level** progress (`Proven`, `Blocked`), while this file tracks **skill-level** activity (`Audited`, `Complete`, `Needs Refresh`). The two files serve different purposes and should not be forced into a single vocabulary.
+
 ## Skill-To-Outcome Map
 
 | Skill | Category | Supports Outcome | Status | Last Run | Notes |