Skip to content

theislampill/IMPLEMENTAUDIT.md

BranchesTags

Repository files navigation

IMPLEMENTAUDIT.md

IMPLEMENTAUDIT.md names this repo and workflow: audited implementation driven by an AUDIT.md-style evidence/input artifact. The .md in the repo name is branding and lineage, not a required root behavior file.

skills/SKILL.md defines /implementaudit: a repo-generic method for turning audit findings, handoffs, checklists, reviews, goals, tasks, gaps, and implementation plans into bounded, verified repository changes. It plans deeply and executes repo work phase-by-phase until terminal audit closure or an explicit audited handoff.

It is for audit closure and repo hygiene: read the real repo, find the owner/source, make the smallest warranted change, prove only what the evidence supports, and close the ledger. Blocked work ends in an explicit audited handoff, not fake completion. It is not a release bot, package publisher, provenance system, or generic autonomous-build loop.

It does not assume a framework, language, CI system, release convention, package host, or optional toolchain. Its default authorization stance is:

No commit. No push. No tag. No release. No publication. No provenance.

Each action requires separate explicit authorization.

Contents

Quick start

  1. Install the skill (see Install notes for your host). The v0.2.9.0 public release carries the contract this README describes.
  2. In a repo you want governed, invoke it with a bounded target: /implementaudit close the findings in AUDIT.md — or just describe the work; unbounded asks get a STOP, not a build loop.
  3. What you will see: a findings ledger, Smoke A baseline evidence, bounded patches, Smoke B comparison, and transcript markers ending in AUDIT_COMPLETE + IMPLEMENTAUDIT_RUN_COMPLETE — or an explicit audited handoff with next actions. Phased runs write their plan and state under .IMPLEMENTAUDIT/runs/<task>-<id>/. The full loop structure is in Loopability, Andon, and handoff states; the shipped helper scripts are catalogued in the docs portal's Shipped Scripts Reference.
  4. Nothing is committed, pushed, tagged, or released unless you explicitly say so.

Runtime at a glance

Input artifact -> live repo inspection -> owner/source patch -> Smoke A/B -> trace -> final audit

The small loop closes one supplied audit/handoff/checklist/review/plan. The larger package loop can synthesize a bounded /goal handoff when the user gives only an idea, gap, or incomplete target.

What it is

/implementaudit is the officer/method layer for audit closure and repo hygiene. It is an audit-governed implementation skill: it plans deeply and executes repo work phase-by-phase until terminal audit closure or an explicit audited handoff. It makes repo changes that are auditable, bounded, owner/source-grounded, reversible, and not overclaimed — routing all work through owner/source discovery, acceptance criteria, rollback/evidence planning, fixtures/checkers, and smoke-before-claim closure. Blocked work ends in an explicit audited handoff, not fake completion. It is not a generic autonomous build runner, release bot, package publisher, or provenance system.

Current optional-tooling architecture:

flowchart LR
  I["ImplementAudit<br/>officer / method / standard"]
  G["Graphify<br/>optional terrain / repo map<br/>graphify-out/graph.json, agent-extracted<br/>orientation, not proof"]
  A["ActiveGraph<br/>optional custody / event evidence<br/>one store per run root: custody.db<br/>absent-safe custody-append.sh<br/>not correctness proof"]
  C["Capability Ledger<br/>derived work history"]
  M["Markdown fallback<br/>always valid when optional tools are absent"]
  L["Live files<br/>source of truth"]

  G -->|where to look| I
  I -->|must confirm in| L
  I -->|gate passages, smokes, Andons, closures| A
  A -->|what happened, not proof by itself| C
  I -->|competence standard| C
  I -->|when tools are absent| M
Loading

Two-tier policy: the sidecars are optional everywhere for users running the skill on their own repos — absence blocks nothing, /implementaudit remains fully usable with neither tool installed, and Markdown fallback is first-class — but canonical for maintaining IMPLEMENTAUDIT itself: dogfood and update rounds on this repo are expected to use Graphify terrain for orientation and ActiveGraph custody for gate-passage history (owner decision, recorded in AGENTS.md). Consumers never inherit the maintenance obligation. When present, Graphify improves orientation before mutation and ActiveGraph preserves custody after evidence is produced; neither replaces the gates, and neither output is proof.

Terminology

  • AUDIT.md: an audit input or evidence-implementation artifact that drives a dogfooded run. It may be a file, attachment, pasted audit, handoff, checklist, review, goal, task, gap, or implementation plan.
  • Greenfield: a new governed artifact or capability where owner/source, contract, acceptance, rollback, and evidence must be defined before implementation.
  • Brownfield: mutation or verification of an existing repo surface where owner/source, contracts, tests, generated artifacts, and regression surface must be inspected before change.
  • Mixed mode: brownfield outer repo work that creates a greenfield subartifact.
  • Owner/source: the canonical file, schema, script, fixture, or doc that owns a claim or behavior.
  • Generated artifact: derived output that must be regenerated from source, not hand-edited.
  • Smoke A / Smoke B: baseline or pre-change verification, then post-change verification compared against that baseline.
  • Andon: a visible abnormality or blocker signal. Failed, hung, substituted, or rerun release-gate commands count even if later contained.
  • 5 Whys: a root-cause drill for why an abnormality happened and what countermeasure prevents recurrence.
  • Hansei: structured reflection: gap, cause, countermeasure, and follow-up evidence.
  • Kaizen: durable process improvement folded back into the standard.
  • Gemba / Genchi Genbutsu: inspect the real repo artifact, output, or path; do not rely on memory or summaries when the live surface exists.
  • Graphify: optional terrain/orientation aid; not canonical proof.
  • ActiveGraph: optional custody/sidecar evidence substrate; not canonical proof.
  • Provenance/checksum manifest: bounded artifact integrity evidence. A checksum manifest is not a signature, SBOM, attestation, marketplace verification, or install proof.

How an audit input drives a run

An AUDIT.md-style input names the work to close and the evidence expected for closure. /implementaudit normalizes that input into ledger items, classifies priority, finds owner/source, records Smoke A, patches only warranted surfaces, records Smoke B, and closes each item as done, changed, blocked, deferred, or unverified.

The input does not authorize hidden side effects. Tool install, indexing, event-store setup, local commit, push, tag, release, publication, and provenance remain separate gates even when the audit asks for implementation.

How IMPLEMENTAUDIT audits

IMPLEMENTAUDIT uses audit in two linked senses:

  • tdqyq-audit-object: the audit-as-noun surface. It is the evidence-bearing record or state for the run: scope, owner/source, claims, changed files, checks, marker state, unresolved gaps, and terminal closure. In a planned run it may be represented by a namespaced .IMPLEMENTAUDIT/runs/<task-slug>-<id>/ root containing PROTOCOL.md, STATE.md, THINKING.md, ROADMAP.md, phases/*, transcript markers, release/package evidence, and closure tables.
  • ydqyq-audit-action: the audit-as-verb operation. It inspects, classifies, verifies, authorizes or rejects mutation, closes findings, or produces a handoff against the live tdqyq-audit-object.

Implementation is allowed only against a live tdqyq-audit-object. AUDIT_COMPLETE means that object reached terminal verified closure. IMPLEMENTAUDIT_RUN_COMPLETE is invalid before that closure.

The double-audit loop is: first ydqyq-audit-action inspects and produces or updates the tdqyq-audit-object; second ydqyq-audit-action acts against that object to close findings; final ydqyq-audit-action verifies terminal closure of the object.

Invocation modes

/implementaudit has three invocation shapes:

flowchart TB
  Final["Terminal audit-object closure<br/>AUDIT_COMPLETE before<br/>IMPLEMENTAUDIT_RUN_COMPLETE"]:::success

  subgraph Direct["Direct governance"]
    DIn["Input<br/>/implementaudit + bounded audit<br/>handoff / checklist / review"]:::input
    DObj["tdqyq-audit-object<br/>user supplies or implies it"]:::artifact
    DLoop["ydqyq-audit-action<br/>inspect -> classify -> patch -> verify"]:::loop
    DArt["Artifacts<br/>findings ledger<br/>source patches<br/>Smoke A/B evidence"]:::artifact
    DGoal["Second /goal<br/>not needed"]:::boundary
    DIn --> DObj --> DLoop --> DArt --> DGoal
  end

  subgraph Embedded["Embedded governance"]
    EIn["Input<br/>/goal already owns the run<br/>using /implementaudit"]:::input
    EObj["tdqyq-audit-object<br/>owned by outer /goal"]:::artifact
    ELoop["ydqyq-audit-action<br/>govern inside supplied target"]:::loop
    EArt["Artifacts<br/>active goal evidence<br/>ledger updates<br/>repo-local checks"]:::artifact
    EGoal["Second /goal<br/>forbidden"]:::blocker
    EIn --> EObj --> ELoop --> EArt --> EGoal
  end

  subgraph Synthesis["Goal synthesis / phased handoff"]
    SIn["Input<br/>idea / gap / incomplete target"]:::input
    SObj["tdqyq-audit-object<br/>created or normalized first"]:::artifact
    SLoop["ydqyq-audit-action<br/>Gemba + route + Stage 0-7 planning"]:::loop
    SArt["Artifacts<br/>.IMPLEMENTAUDIT/runs/slug-id/<br/>ROADMAP · STATE · THINKING<br/>PROTOCOL · sidecars · applied-context<br/>repo-map · phases/phase-N.md"]:::artifact
    SGoal["Second /goal<br/>produced once when not embedded"]:::handoff
    SIn --> SObj --> SLoop --> SArt --> SGoal
  end

  subgraph Casual["Governed casual-build intake"]
    CIn["Input<br/>natural-language repo-build intent<br/>no audit artifact yet"]:::input
    CObj["tdqyq-audit-object<br/>synthesized by 5-step intake<br/>owner/source · criteria · rollback"]:::artifact
    CLoop["ydqyq-audit-action<br/>route greenfield / brownfield / mixed<br/>then govern as direct"]:::loop
    CArt["Artifacts<br/>bounded intake record<br/>STOP on unbounded / unsafe /<br/>non-repo input"]:::artifact
    CGoal["Second /goal<br/>not needed"]:::boundary
    CIn --> CObj --> CLoop --> CArt --> CGoal
  end

  DGoal --> Final
  EGoal --> Final
  SGoal --> Final
  CGoal --> Final

  classDef input fill:#eff6ff,stroke:#2563eb,color:#111827
  classDef loop fill:#ecfdf5,stroke:#059669,color:#111827
  classDef artifact fill:#f5f3ff,stroke:#7c3aed,color:#111827
  classDef boundary fill:#f8fafc,stroke:#64748b,color:#111827
  classDef handoff fill:#fff7ed,stroke:#ea580c,color:#111827
  classDef blocker fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
  classDef success fill:#d1fae5,stroke:#059669,color:#064e3b
Loading
  • Embedded governance mode: a host goal/task/plan already exists, such as /goal using /implementaudit .... The outer goal owns the tdqyq-audit-object; ImplementAudit performs ydqyq-audit-action inside that object and does not print a second /goal.
  • Direct governance mode: the user supplies a concrete audit, handoff, checklist, review, or bounded implementation plan. The user supplies or implies the tdqyq-audit-object; ImplementAudit performs ydqyq-audit-action and implementation against it.
  • Goal-synthesis mode: the user supplies an idea, gap, incomplete target, or request for the next best implementation prompt. ImplementAudit creates or normalizes the tdqyq-audit-object, writes phase artifacts, and may print one ready-to-paste /goal Using /implementaudit ... line only when not already embedded.
  • Governed casual-build intake: the user describes repo-build intent in natural language. ImplementAudit first synthesizes a bounded tdqyq-audit-object (owner/source, acceptance criteria, rollback path) from that description before routing to the appropriate governance mode. Unbounded, unsafe, or non-repo intent is rejected with an explicit STOP. This is not ungated autonomous build execution.

Native planner stages

When goal synthesis or phased audit closure is needed, skills/SKILL.md defines a native Stage 0-7 planner contract:

Stage 0 - Context/tool/repo-state detection
Stage 1 - Audit-governed intake and routing
Stage 2 - Recon / Gemba
Stage 3 - Deep think / risk and dependency analysis
Stage 4 - Phase decomposition
Stage 5 - Write .IMPLEMENTAUDIT/runs/<task-slug>-<id> runtime artifacts
Stage 6 - Plan review and self-critique
Stage 6.5 - Pre-flight smoke
Stage 7 - One ready-to-paste /goal handoff when not already embedded

The stage contract is audit-governed: it preserves owner/source patching, Smoke A/B, generated-artifact discipline, final audit before completion, and the separate commit/push/tag/release/provenance gates. It does not turn IMPLEMENTAUDIT into open-ended software-builder automation.

When phased planning is selected, new runtime artifacts live under a namespaced run root such as .IMPLEMENTAUDIT/runs/<task-slug>-<id>/. The package includes skills/scripts/claim-run.sh to claim that directory atomically. A run root may contain ROADMAP.md, STATE.md, THINKING.md, PROTOCOL.md, context.md, tools.md, sidecars.md, applied-context.md or applied-memories.md, repo-map.md, and phases/phase-N.md. Flat .IMPLEMENTAUDIT/* artifacts are legacy resume/audit compatibility, not the preferred new-run target. THINKING.md is reviewable planning evidence for route, risks, dependencies, rollback, and evidence strategy; it is not proof by itself.

Why one /goal, not a chain

A generated /goal should carry the bounded end-state and audit completion condition. Phase specs live under .IMPLEMENTAUDIT/runs/<task-slug>-<id>/phases/ (flat .IMPLEMENTAUDIT/* is legacy resume/audit compatibility, not the preferred target for new runs); the run progresses through files, checks, and markers rather than a fragile sequence of user-pasted commands. Final completion still requires AUDIT_COMPLETE before IMPLEMENTAUDIT_RUN_COMPLETE.

Inside embedded governance, another /goal already owns the run, so /implementaudit must not emit a nested goal. In goal-synthesis mode, it may produce one ready-to-paste /goal Using /implementaudit ... handoff after Gemba, phase planning, self-critique, and pre-flight.

Default behavior

The default small audit implementer mode works on one audit, handoff, checklist, review, or implementation plan.

It:

  • validates that the input is a recognizable audit artifact
  • normalizes findings into a ledger
  • classifies items as P0, P1, P2, OWNER DECISION, DEFERRED, or OUT OF SCOPE
  • processes work in P0 -> P1 -> P2 order
  • patches owner/source, not nearest symptom
  • requires evidence for every claim
  • closes every item as done, changed, blocked, deferred, or unverified

No ledger item may remain open at final response.

Greenfield / brownfield routing

ImplementAudit classifies work before planning or mutation:

  • Greenfield: a new governed artifact, fixture family, checker, reference, workflow, runtime capability, sidecar contract, or validation surface is being introduced and has no established repo owner/source yet.
  • Brownfield: an existing repo artifact, owner/source, generated output, fixture, checker, contract, or documented invariant is being repaired, verified, or closed.
  • Mixed: a new artifact is introduced inside an established repo. The outer shell is brownfield; the new artifact receives greenfield intake after the existing repo surface is inspected.

Greenfield work must define owner/source, scope and non-scope, constraints, acceptance criteria, rollback/removal path, evidence plan, generated-artifact plan, sidecar status, and canonical-vs-sidecar boundaries before implementation.

Brownfield work must inspect existing owner/source, contracts, tests, smokes, checkers, generated artifacts, optional sidecars, regression surface, and rollback path before mutation.

Graphify may orient brownfield terrain when available and fresh, but live files remain source of truth. ActiveGraph may preserve custody when configured, but Markdown ledgers and final reports remain valid fallback. Neither optional sidecar replaces repo-local owners, fixtures, checkers, smoke output, or audit ledgers.

Operating method

The method combines:

  • PDCA: plan the smallest safe change, do it, check evidence, then standardize or revise.
  • Gemba: inspect the real place of work, not summaries when live artifacts exist.
  • Smoke Before Claim: tag every behavior claim with the smallest meaningful evidence.
  • Smoke A / Smoke B: capture the pre-change baseline, then compare post-change checks to detect regressions.
  • Andon: surface blockers, failures, unclear ownership, or unsafe conditions immediately.
  • Hansei: reflect after gaps, regressions, false passes, or failures.
  • 5 Whys: trace symptoms to root cause when the situation warrants it.
  • Plan Closure: map every item to a terminal status.
  • Lean operating discipline: Lean/TPS terms map to auditable runtime behavior documented in skills/references/lean-operating-discipline.md. Brownfield improvement routes through DMAIC (Define→Measure→Analyze→Improve→Control); greenfield or replacement routes through DMADV (Define→Measure→Analyze→Design→Verify). A quality route is declared per phase. 5S gates apply to run roots, package payloads, and generated artifacts. Jidoka means stop-the-line when evidence fails. Lean terms are not decorative labels.

Static checks, local generated-runtime evidence, manual inspection, browser evidence, package-bound checks, unit tests, and live runtime checks are not interchangeable. Proof claims must not exceed the evidence type.

Execution gates

The gate diagram shows the normal path and the places where the method must stop, recover, or hand off instead of pretending the run is complete.

flowchart TD
  Input(["Audit-style input / handoff / goal / gap"]):::human
  Route["Route before mutation<br/>greenfield / brownfield / mixed<br/>brownfield recon is read-only"]:::audit
  OwnerDecision(["OWNER DECISION<br/>unsafe request or AGENTS/policy conflict"]):::blocker

  Graphify["Graphify optional terrain<br/>orientation only, not proof"]:::optional
  Gemba["Live-file Gemba<br/>confirm owner/source before mutation"]:::source
  SmokeA["Smoke A<br/>baseline before change"]:::checker
  Patch["Patch owner/source<br/>bounded P0 -> P1 -> P2"]:::source
  Generated["Refresh generated artifacts<br/>from source/generator"]:::generated
  SmokeB["Smoke B + complete<br/>working-tree-vs-baseline check"]:::checker

  ActiveGraph["ActiveGraph optional custody<br/>after evidence exists<br/>not correctness proof"]:::optional
  Ledger["Capability Ledger or<br/>Markdown final report fallback"]:::audit

  Andon["Andon / handoff loop<br/>abnormality -> 5 Whys -> Hansei<br/>countermeasure -> rerun"]:::blocker
  Final["Final audit<br/>criteria, boundaries, evidence"]:::audit
  AuditDone(["AUDIT_COMPLETE"]):::success
  RunDone(["IMPLEMENTAUDIT_RUN_COMPLETE"]):::success
  NoRelease["Ordinary completion default<br/>No tag, release, publication, or provenance"]:::audit
  ReleaseGate{"Separate release/provenance gate<br/>explicitly authorized?"}:::release
  Release["Tag / release / asset<br/>checksum manifest only if produced and verified"]:::release
  Legend["Legend: amber human/owner; blue owner/source; purple generated;<br/>green checks; dashed green optional; red blocker; orange release"]:::audit

  subgraph PhasedRun["Phased planned run — goal synthesis path"]
    RunRoot["Run-root claim<br/>claim-run.sh<br/>.IMPLEMENTAUDIT/runs/slug-id/"]:::source
    Stage6["Stage 6<br/>plan review + self-critique<br/>revision menu"]:::audit
    Stage65["Stage 6.5 preflight smoke<br/>PREFLIGHT_GREEN / PREFLIGHT_RED"]:::checker
    Stage7["Stage 7 handoff<br/>one-paste /implementaudit<br/>omitted if embedded"]:::audit
    PhaseSpec["validate-phase.sh<br/>each phase spec<br/>exit 0 required"]:::checker
    PhaseLoop["16-step phase loop<br/>Smoke A -> execute -> cmds<br/>criteria -> cleanliness -> Smoke B"]:::source
    Recovery["Andon escalation, no try cap<br/>ANDON_PROBE -> ANDON_ESCALATE<br/>-> ANDON_HANDOFF only when blocked"]:::blocker
    AuditFix["Final audit + audit-fix rounds<br/>loop until closed or audited handoff<br/>AUDIT_GAPS -> fix -> re-round"]:::audit
    RunRoot --> Stage6 --> Stage65 --> Stage7 --> PhaseSpec --> PhaseLoop
    PhaseLoop -->|criterion fails| Recovery
    PhaseLoop -->|all phases done| AuditFix
  end

  Input --> Route
  Route -->|unsafe / conflict| OwnerDecision
  Route -->|authorized scope| Gemba
  Route -. phased planning .-> RunRoot
  AuditFix --> Final
  Graphify -. optional query before touching scene .-> Gemba
  Gemba --> SmokeA --> Patch --> Generated --> SmokeB
  SmokeB -. custody sidecar .-> ActiveGraph --> Ledger
  SmokeB --> Final
  SmokeA -->|unclear baseline| Andon
  SmokeB -->|regression / failed gate| Andon
  Final -->|gap remains| Andon
  Andon -->|fixable rerun| Gemba
  Final -->|all findings closed| AuditDone --> RunDone --> NoRelease
  RunDone -. separate explicit gate only .-> ReleaseGate
  ReleaseGate -->|authorized + evidence| Release
  ReleaseGate -->|not authorized| NoRelease
  Legend -. explains classes .-> Route

  classDef human fill:#fef3c7,stroke:#d97706,color:#111827
  classDef source fill:#e0f2fe,stroke:#0284c7,color:#111827
  classDef generated fill:#ede9fe,stroke:#7c3aed,color:#111827
  classDef checker fill:#dcfce7,stroke:#16a34a,color:#111827
  classDef audit fill:#f1f5f9,stroke:#475569,color:#111827
  classDef optional fill:#f0fdf4,stroke:#65a30d,color:#111827,stroke-dasharray: 4 3
  classDef release fill:#fff7ed,stroke:#ea580c,color:#111827
  classDef success fill:#d1fae5,stroke:#059669,color:#064e3b
  classDef blocker fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
Loading
Gate Purpose
Safety read Read repo instructions, safety defaults, authorization gates, and AGENTS.md conflict rules.
Input gate Confirm the input is a valid audit artifact.
Pre-flight Detect optional tooling, confirm write access, source/generator ownership, authorization chain, repo constraints, and prior run state.
Smoke A Run and classify baseline checks before mutation.
Implement Patch items atomically in priority order and guard scope creep.
Smoke B Compare post-change checks against Smoke A and trigger regression protocol when needed.
Trace Preserve causal history in commit body or proposed commit body, ledger, optional Capability Ledger, and AGENTS.md only when warranted.
Self-check Verify quality-bar invariants before final response.

If an audit finding contradicts repo-local AGENTS.md or policy, the conflict becomes OWNER DECISION. The agent does not silently choose which instruction wins.

Loopability, Andon, and handoff states

An IMPLEMENTAUDIT run is loopable. It can end in AUDIT_COMPLETE plus IMPLEMENTAUDIT_RUN_COMPLETE, or it can end in AUDIT_HANDOFF, blocked, deferred, or unverified states with enough evidence for a later agent to resume, audit, or repair the work.

Completion is not "deliverables exist." Completion means owner/source changes, generated outputs, smoke/check evidence, final audit, ledger closure, and terminal markers all align.

Andons are loop points, not just errors:

record abnormality -> 5 Whys -> Hansei -> countermeasure -> rerun relevant checks -> close/defer/block with evidence

Nested loop model

A full IMPLEMENTAUDIT run is five concentric loops. Each has its own entry, exit, and evidence currency:

Loop Scope Exit condition Markers / currency
L1 Planner Stage 0–7 goal synthesis; PREFLIGHT_RED re-enters Stage 6 PREFLIGHT_GREEN + one-paste handoff, or embedded continuation Self-critique:, PREFLIGHT_GREEN / PREFLIGHT_RED
L2 Run phases 1→N from ROADMAP.md, sequential, resumable every phase terminal, or audited handoff STATE.md, IMPLEMENTAUDIT_PAUSE on interruption
L3 Phase 16 steps: Smoke A → work → commands → criteria → 5S → Smoke B IMPLEMENTAUDIT_PHASE_DONE with terminal status IMPLEMENTAUDIT_PHASE_START / _VERIFY, AGENTS_UPDATE_DECISION
L4 Andon abnormality handling; may interrupt any other loop countermeasure passes rerun evidence, or a genuine blocking condition ANDON_PROBE → ANDON_ESCALATE → ANDON_HANDOFF, classed Andon log rows
L5 Audit-fix final audit rounds, uncapped AUDIT_COMPLETE, or AUDIT_HANDOFF on a blocking condition AUDIT_START / _VERIFY / _GAPS, coverage math

L4 is the only loop that can interrupt any other loop (Jidoka stops the line anywhere). L5 is the only loop that can end the run. No loop carries an arbitrary try or round cap: L4 escalates on repeated same-class abnormality with new evidence, and hands off only when closure is blocked by an owner decision, unsafe scope, missing authorization, an external dependency, irreproducibility, missing tooling or access, or no bounded countermeasure.

If a checker, shell command, diagram generator, package validator, release-gate command, or provenance command fails, hangs, shell-errors, or is replaced by a rerun/substitute path, record the abnormal path as an Andon before closing it as blocking or non-blocking.

Post-release corrections patch forward. If a release is already out, do not pretend the gate is still pre-release; record the post-release audit status, make a follow-up source-owned correction when warranted, and propose any release notes correction before editing release metadata.

Release and checksum-manifest provenance are a separate gated loop after ordinary audit completion. Ordinary success does not imply tag, release, publication, asset upload, checksum publication, signature, attestation, SBOM, marketplace verification, or install verification.

Artifacts and outputs

Typical run outputs are a normalized findings ledger, changed owner/source files when authorized by the audit, regenerated artifacts when their source changed, Smoke A/B evidence, an AGENTS update decision, a final report, and terminal markers. Large or phased runs also claim a namespaced run root under .IMPLEMENTAUDIT/runs/<task>-<id>/ holding the full substrate — ROADMAP.md, STATE.md (status enum, ledger, classed Andon log), THINKING.md, PROTOCOL.md, sidecars.md, tools.md, context.md, applied-context.md, repo-map.md, and phases/phase-N.md — instantiated from the packaged templates and structurally checkable with the shipped validate-run-root.sh. A completed continuity writeback prints IMPLEMENTAUDIT_CONTINUITY_SAVED with its six fields (Target, Reason, Evidence, Boundary, Authorization, Not saved). Run roots are run artifacts, not package source, and are excluded from evidence scans and commits.

The packaged skill payload lives under skills/. GitHub release assets, when separately authorized, are built from the repo-supported release-asset script and validated by extraction. Release artifacts and checksum manifests are not ordinary audit outputs.

The .skill release archive contains only the runtime skill payload (SKILL.md, references/, scripts/, templates/) and plugin metadata (.claude-plugin/). Repo docs, tests, fixtures, release tooling, audit ledgers, run roots, and sidecar stores are excluded from the archive. As of v0.2.6.0 all archive entries are ZIP_DEFLATED; compression is validated by tests/release-asset.test.sh as an asset-integrity hardening measure.

Skill internals / repository layout

This repo uses the flat package layout declared by AGENTS.md:

skills/SKILL.md
skills/references/
skills/scripts/
skills/templates/

skills/SKILL.md is the canonical behavior source and packaged skill entry. There is intentionally no tracked root IMPLEMENTAUDIT.md file; validators fail if one is recreated. Audit handoff inputs named AUDIT.md remain valid.

Package metadata lives under .claude-plugin/:

.claude-plugin/plugin.json
.claude-plugin/marketplace.json

The manifest JSON is validated by scripts/verify-package.sh. This README does not claim that Claude Code marketplace behavior, Codex installation, release, publication, or provenance has been verified.

Version and release notes

Current project milestone: v0.2.9.0. Plugin manifest version: 0.2.9. No local schema evidence proved four-component plugin manifest versions are accepted, so the manifest uses host-conservative package metadata while the project milestone is recorded in docs and changelog. This is not a tag, release, publication, or provenance claim by itself.

See CHANGELOG.md and the GitHub Releases page for release notes. Release notes may document release assets and checksum manifests only after those artifacts exist and are verified.

There is no LICENSE file in this repo yet. License selection remains an owner decision.

Child-agent review loops

/implementaudit may use child agents or subagents as bounded review loops when the host supports them, or may simulate the same pattern as separate written read-only audit passes.

The package includes skills/references/child-agents.md and skills/templates/child-agent-report.md as explanatory/reference material. Instruction precedence remains with the repo's AGENTS.md hierarchy. Root AGENTS.md holds repo-wide child/subagent rules; scoped AGENTS.md or AGENTS.override.md is used only for subtree-specific guidance when that host/repo convention is available.

Child-agent reports do not prove correctness and do not authorize edits, commits, pushes, installs, indexing, exports, releases, publication, or provenance. The main /implementaudit agent must normalize reviewer findings into the ledger and inspect live files before patching or closing them.

Optional tooling

Optional tooling can improve orientation and custody, but it does not change /implementaudit safety rules.

Tool installation, Graphify indexing, ActiveGraph event-store setup, ActiveGraph export, local commit, push, tag, release, publication, and provenance are separate gates. Installing a tool does not authorize any later action.

First-run onboarding

On first runs, /implementaudit may detect Graphify and ActiveGraph availability. Missing tools are not errors.

Default behavior:

  • detect and record availability
  • continue safely without optional tooling when absent
  • print install/configure commands as documentation when useful
  • install or configure tools only with explicit authorization such as /implementaudit --onboard-tools or a direct user instruction

Documented onboarding commands:

uv tool install graphifyy
graphify install --platform codex
graphify install --project --platform codex

pip install activegraph
activegraph quickstart

These commands are documentation only in this repo state. Running them requires explicit authorization. Installation does not authorize indexing, event-store setup, export, commit, push, tag, release, publication, or provenance.

Graphify-assisted Gemba

Graphify is the optional catalog / terrain map. When available and fresh, or when indexing/querying is explicitly authorized, /implementaudit can query it before touching the scene.

Graphify can help identify:

  • owner/source candidates
  • dependency paths
  • generated-artifact hints
  • impact surfaces
  • smoke/test candidates
  • scope-creep signals
  • stale assumptions
  • source/generated output relationships

Graphify output is orientation evidence, not proof. It does not prove correctness, decide closure, authorize mutation, replace live-file inspection, override repo instructions, or weaken AGENTS.md.

Graphify terrain tagged INFERRED or AMBIGUOUS requires live-file confirmation before implementation, closure, or proof claims. Live files win over graph output. If Graphify is absent or stale, /implementaudit falls back to ordinary Gemba.

ActiveGraph-backed Capability Ledger

ActiveGraph is the optional evidence locker / custody substrate. When configured, ActiveGraph-backed /implementaudit runs may derive Capability Ledger entries as the natural custody-backed output of the run.

The Capability Ledger / Officer CV is ImplementAudit-derived. It is not an upstream ActiveGraph built-in feature. ActiveGraph provides the event custody substrate; ImplementAudit derives capability entries from recorded gate passages and evidence.

Entries may include:

  • run id
  • repo identity
  • finding class
  • owner/source
  • countermeasure
  • Graphify terrain context, if available
  • ActiveGraph custody events, if available
  • authorization gates respected
  • Smoke A and Smoke B
  • regression / Andon / Hansei trail, if any
  • final status
  • remaining risk

When ActiveGraph is absent, the ordinary Markdown ledger and final report remain first-class fallback. The run is not blocked merely because ActiveGraph is unavailable.

When custody is configured and authorized, the conventions are concrete: one store per run root (<run-root>/custody.db, or custody-trace.jsonl as an append-only fallback), written with the packaged absent-safe custody-append.sh helper; Andon escalation mirrors into the store as andon.probe.recorded / andon.escalated / andon.handoff.recorded events carrying the abnormality class; later runs preload prior per-run stores read-only for cross-run continuity; and reconstructed history must be labeled custody_mode: historical_backfill with source, backfill time, original event time, and evidence boundary, so live and backfilled custody never blur. Run-level sidecar status lives in <run-root>/sidecars.md, instantiated from the packaged template.

Evidence boundaries

Interop boundaries are explicit:

  • Graphify-supported behavior must be distinguished from ImplementAudit heuristics.
  • Graphify summaries and graph output are not proof.
  • ActiveGraph custody is not correctness proof.
  • ImplementAudit custom adapter events are not upstream ActiveGraph built-ins unless explicitly identified as such.
  • ActiveGraph policies gate graph object proposals, graph patches, and wrapped behaviors/tools/proposals.
  • ActiveGraph does not inherently gate shell commands, git commit, git push, tag, release, publication, or provenance unless those actions are modeled through wrapped ActiveGraph behavior/tool/proposal semantics.
  • Object/relation mappings are ImplementAudit-specific or Diligence-style adapter mappings, not upstream ActiveGraph base types.
  • Release and provenance claims require separate authorization and evidence.

Usage examples

/implementaudit < audit.md
/implementaudit implement these findings
/implementaudit --onboard-tools
/goal using /implementaudit, close the findings in AUDIT.md
/implementaudit add a login page to this app        # governed casual-build intake
/implementaudit audit this repo and give me the next best goal   # goal synthesis

Natural-language requests such as "implement these findings", "act on this audit", "close these items", or "work through this handoff" also invoke the method when the input is a valid audit artifact.

Governed casual-build intake accepts plain-language repo-build intent:

/implementaudit make the docs portal generated by CI and prove it is fresh
/implementaudit fix this repo bug safely and keep the diff reviewable
/implementaudit build the requested repo feature, but route it through /implementaudit governance
/implementaudit plan deeply and build until done or audited handoff

The skill synthesizes a bounded audit object from the description before routing. To choose the right invocation shape, see the chooser table in skills/references/goal-format.md and the onboarding portal generated by scripts/build-docs-portal.py.

Install notes

Install flows are evidence-bounded. This repo can locally validate the release asset-to-Codex-install path into a temporary Codex home. It does not claim passive auto-update, universal host support, marketplace verification, or public GitHub release download verification unless those checks are run and recorded.

Release/contract alignment: the latest public release is v0.2.9.0 (verified against the live release list at the release gate), which carries the Andon/Jidoka failure contract, helper-path resolution, run-root validation, and custody tooling described in this README. Installing from the public release gives you the documented behavior. Re-verify this paragraph at every release gate; if a future README documents behavior newer than the latest release, restore the staleness disclosure.

What each install source carries:

Source Failure contract Helper resolution Run-root / custody tooling
Public release v0.2.9.0 (latest) / built from source ANDON_PROBE / ANDON_ESCALATE / ANDON_HANDOFF, classed Andon log, no try caps IMPLEMENTAUDIT_SKILL_DIR resolution run-root validator; sidecars/tools/context templates; absent-safe custody helper
Older public release v0.2.8.0 pre-Andon (older recovery semantics) bare paths (pre-skill-dir) none

Install / update for Codex

Codex manual installs copy the packaged skill payload into a Codex-style skill directory. A public GitHub release by itself cannot update a local copied skill.

From a repo checkout, the simplest manual copy is:

mkdir -p ~/.codex/skills/implementaudit
cp -R skills/* ~/.codex/skills/implementaudit/

PowerShell equivalent:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\skills\implementaudit" | Out-Null
Copy-Item -Recurse -Force .\skills\* "$env:USERPROFILE\.codex\skills\implementaudit\"

For a local release asset, build the asset, write checksums, and install with checksum verification:

bash scripts/build-release-asset.sh
bash scripts/write-release-checksums.sh dist/IMPLEMENTAUDIT.skill dist/CHECKSUMS.txt
bash scripts/install-codex-from-release.sh \
  --asset dist/IMPLEMENTAUDIT.skill \
  --checksum dist/CHECKSUMS.txt \
  --codex-home "$HOME/.codex" \
  --version 0.2.9

After a public release exists, the same installer can be pointed at an explicit tag or asset URL from a source checkout:

bash scripts/install-codex-from-release.sh --tag v0.2.9.0 --version 0.2.9

That public-download path is a claim only after the release exists and the download/checksum/install smoke is actually run. If it cannot be run, treat it as unverified or handoff evidence, not as install proof.

Install / update for Claude Desktop

Claude Desktop (v0.2.5.0 tested target) stores session-managed skills in a session-specific directory. The stable public path to the session skill store is:

  • Windows: %APPDATA%\Claude\local-agent-mode-sessions\skills-plugin\
  • macOS: ~/Library/Application Support/Claude/local-agent-mode-sessions/skills-plugin/
  • Linux: ~/.config/Claude/local-agent-mode-sessions/skills-plugin/

Under that root, locate the subtree containing skills/implementaudit/ (the session UUID path is unique per installation). Pass that directory as --claude-skills-dir to the install script.

From a local release asset:

bash scripts/install-claude-from-release.sh \
  --asset dist/IMPLEMENTAUDIT.skill \
  --checksum dist/CHECKSUMS.txt \
  --claude-skills-dir "<claude-session-path>/skills/implementaudit"

From the live public v0.2.9.0 release:

bash scripts/install-claude-from-release.sh \
  --tag v0.2.9.0 \
  --claude-skills-dir "<claude-session-path>/skills/implementaudit"

After the script completes, restart Claude Desktop for the changes to take effect.

Boundaries: scripts/install-claude-from-release.sh copies files only. It does not prove the skill loads or runs in Claude Desktop. No install proof is claimed here. Verify in Claude Desktop after restart. The session-managed path may change between Claude Desktop versions; if the path structure differs, use Claude Desktop's built-in skill management UI to update the skill.

This repo does not claim marketplace auto-update, passive install, universal host support, or Claude Desktop behavior beyond what is empirically recorded as evidence.

Install / update for Claude Code (plugin path)

Claude Code plugin consumers should use the host's current plugin instructions with .claude-plugin/plugin.json as package metadata. This repo validates the JSON shape only; it does not claim host install or marketplace behavior was tested.

For public clone/plugin setup, an HTTPS repository URL is usually the simplest path because it does not require local SSH key configuration. SSH URLs are fine when the user already has working GitHub SSH authentication in that host.

Upgrade / reinstall

After a release, reinstall or update the skill in the host you use. Do not assume a local copied skill has updated just because the GitHub repo has a new release.

For Codex manual installs, there is no marketplace auto-update path documented in this repo. Repeat the documented copy step or release-asset install step after each release:

mkdir -p ~/.codex/skills/implementaudit
cp -R skills/* ~/.codex/skills/implementaudit/

PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\skills\implementaudit" | Out-Null
Copy-Item -Recurse -Force .\skills\* "$env:USERPROFILE\.codex\skills\implementaudit\"

Claude Desktop users: locate the session skill directory (see Install notes above) and re-run scripts/install-claude-from-release.sh with the new asset. Restart Claude Desktop after the script completes.

Claude Code/plugin users should use the host's documented plugin update or reload flow when available. This repo does not claim that plugin update, marketplace refresh, install, release, publication, or provenance behavior has been verified.

Release asset notes

For package release gates, including v0.2.5.0, the GitHub release asset name is IMPLEMENTAUDIT.skill.

No local evidence proves .skill is a universal host-standard archive format. In this repo, IMPLEMENTAUDIT.skill is the GitHub release artifact name. It is a ZIP-format archive containing the installable skill payload:

skills/
.claude-plugin/

The release asset intentionally excludes repo-maintenance material such as README generation sources, audit ledgers, release-candidate notes, fixtures, tests, CI config, Git metadata, and root validation scripts. Those remain repo-side evidence and maintenance surfaces, not installed runtime payload.

Build and validate it locally with:

bash scripts/build-release-asset.sh

scripts/verify-package.sh also runs the builder in --check mode and validates the extracted package shape.

When provenance is explicitly authorized for a release gate, this repo may publish a checksum manifest such as CHECKSUMS.txt for IMPLEMENTAUDIT.skill. A checksum manifest is not a signature, attestation, SBOM, license, marketplace verification, or install verification.

The artifact must not include .IMPLEMENTAUDIT/ run artifacts, local smoke debris, Graphify outputs, ActiveGraph stores, secrets, git metadata, or untracked diagnostics. Attaching IMPLEMENTAUDIT.skill to GitHub Releases is a separate release-gate action. Ordinary audits, local commits, and push-only gates do not authorize upload, release, publication, marketplace verification, or provenance claims.

Validation and release evidence

Repo-native validation includes README diagram freshness, ToC anchor checks, host-claim and claim-boundary checks, root behavior-file absence, package contract validation, routing fixtures, marker-order checks, repo-state checks, audit-spec checks, release-asset extraction checks, release-asset Codex install smoke, stale-checksum failure smoke, and checksum-manifest checks.

Run the package validator before local commit or release-gate claims:

bash scripts/verify-package.sh

When release assets are mentioned, validate the release asset locally:

bash scripts/build-release-asset.sh
bash scripts/write-release-checksums.sh dist/IMPLEMENTAUDIT.skill dist/CHECKSUMS.txt
bash scripts/write-release-checksums.sh --check
bash tests/release-asset-install.test.sh

For release gates since v0.2.5.0, the intended GitHub release assets are IMPLEMENTAUDIT.skill and CHECKSUMS.txt. The checksum manifest is bounded artifact-integrity evidence only; it is not a signature, attestation, SBOM, marketplace verification, license claim, or install proof.

Safety defaults

Never do these unless explicitly authorized and allowed by repo policy:

  • commit
  • push
  • tag
  • publish
  • create or update releases
  • delete data
  • alter credentials or secrets
  • rewrite history
  • commit raw diagnostic outputs
  • hand-edit generated artifacts when a source generator exists
  • claim proof without evidence

Local commit authorization does not imply push authorization. Push authorization does not imply tag, release, publication, or provenance authorization.

If local commits are authorized, commit bodies carry the causal trace: finding, owner/source, root cause when relevant, Andon/Hansei/5 Whys when triggered, countermeasure, changed files, Smoke A/B, boundaries preserved, and deferred follow-up.

If local commits are not authorized, the final report includes a proposed commit message/body instead.

What this does not do

/implementaudit does not:

  • make Graphify or ActiveGraph hard dependencies
  • silently install tools
  • silently run indexing
  • silently create ActiveGraph config or event stores
  • silently export custody events
  • treat install success as audit proof
  • treat Graphify output as correctness proof
  • treat ActiveGraph custody as correctness proof
  • push, tag, release, publish, or make provenance claims without explicit authorization
  • resolve audit-vs-AGENTS.md conflicts by agent judgment
  • use AGENTS.md as a raw evidence dump

Development / maintenance notes

AGENTS.md is the authoritative repository contract. skills/SKILL.md is the canonical skill behavior source under the current flat package contract.

README Mermaid diagrams are generated from docs/diagrams/*.mmd; do not edit diagram blocks by hand. Refresh or check them with:

bash scripts/generate-readme-diagrams.sh
bash scripts/generate-readme-diagrams.sh --check

Validation scripts are POSIX shell scripts. On Windows, run them from Git Bash or WSL. The repo pins *.sh files to LF line endings for shell portability.

Before committing package changes, run:

git diff --check
python -m json.tool .claude-plugin/plugin.json
python -m json.tool .claude-plugin/marketplace.json
bash scripts/verify-package.sh

Also run:

bash skills/scripts/validate-phase.sh skills/templates/phase-goal.txt

Preserve the distinction between:

  • upstream-supported behavior
  • ImplementAudit custom extension
  • repo-local heuristic
  • unsupported or uncertain behavior

Detailed evidence belongs in commit bodies, orchestrator/audit ledgers, ActiveGraph custody events when configured, or final reports. Durable anti-repeat rules may belong in repo-local AGENTS.md when they would prevent future agents from repeating the same mistake.

Native harness discipline now includes helpers/checkers for environment and repo-contract discovery, brownfield repo summaries, complete baseline-vs-working tree evidence, structural audit-spec validation, transcript marker order, routing fixtures, release-asset checks, and added-line cleanliness/overclaim scans. Complete repo-state checks compare the baseline to the working tree so staged, unstaged, deleted, and untracked work cannot disappear from final audit evidence.

About

A loop skill to implement audit findings safely

Topics

skills audit developer-tools codex kaizen ai-agents gemba graphify llm-tools repo-hygiene activegraph claude-code

Resources

Readme

Contributing

Contributing
Activity

Stars

5 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 12

v0.2.9.0 — No-cap Andon/Jidoka runtime, validated run roots, and install-safe helpers Latest
Jun 10, 2026
+ 11 releases

Packages

 
 
 

Contributors

Languages