README.md

IMPLEMENTAUDIT.md

A self-correcting system of nested engineering loops:

plan & execute repo work; safely implement audit findings;

design greenfield & improve brownfield; learn from failures;

re-verify until closure.

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/implementaudit/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.

At its core, this is audit-governed agentic-engineering: it derives and governs the right work against the right current state, under the right authority, recovers proportionally when reality contradicts the plan, and moves “done” out of model self-assessment and into independently checkable evidence. Generated output, effort, and successful tool calls are insufficient evidence of completion by themselves. The system-state counts as complete when it survives audit; otherwise the run stops at an explicit audited handoff.

Instead of relying on model “willpower”, it externalises that discipline into persistent state, executable checks, bounded decomposition, independent re-verification, and evidence-backed completion.

It is reusable meta-engineering for sustained repository work:

engineering discipline for planning, designing, implementing, improving, reviewing, recovering, integrating, and closing work from intent → implementation → evidence-backed terminal state — not merely a one-off code audit.

IMPLEMENTAUDIT is the product of an autodidactic, research-guided accretion process rather than a single internally designed theory of agent workflow: established engineering traditions were progressively translated, recombined, tested and adapted to agentic-engineering workflows. Its architecture develops through repeat dogfooding and anomaly-responsive source refinement: retaining, changing, or discarding practices according to their demonstrated durability under real repository work.

IMPLEMENTAUDIT is therefore an agentic-engineering emergence through the convergence of auditing and implementing engineering ideas into IMPLEMENTAUDIT.

The method scales its ceremony to consequence. Small reversible work can stay compact; deeper planning, durable run state, independent review, package checks, or external readback activate only when scope, risk, dependencies, or the claimed evidence surface warrant them. Process volume alone is not engineering value.

It is not an ungated autonomous build loop, release bot, package publisher, or provenance system.

Its default authorisation stance is:

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

Each action requires separate explicit authorisation.

Contents

• Quick start
• Runtime at a glance
• Governor, specialised cognition, and work topology
• Why IMPLEMENTAUDIT is stronger than a bare /goal
• What it is
• Quick vocabulary, not authority
• How an audit input drives a run
• How IMPLEMENTAUDIT audits
• Invocation modes
• Native planner stages
• Default behavior
• Greenfield / brownfield routing
• Operating method
• Execution gates
• Loopability, Andon, and handoff states
• Artifacts and outputs
• Skill internals / repository layout
• Version and release notes
• Child-agent review loops
• Optional tooling
• Evidence boundaries
• Usage examples
• Install notes
• Upgrade / reinstall
• Release asset notes
• Validation and release evidence
• Safety defaults
• What this does not do
• Contributing and deeper documentation

Quick start

1. Choose the installation route in Install notes. The published public identity is v0.4.0.0; its host-facing runtime is 0.4.0. State Synthesis Substrate Engineering: Evolved-SSDDRFCSS (S³E) names one native state-synthesis substrate, not selectable lineage modes. The public release assets passed byte-for-byte download/readback; a checkout of main, a locally built archive, and those tagged assets remain distinct.

2. Invoke /implementaudit with a bounded repository target. Common shapes include:

   /implementaudit close the findings in AUDIT.md
   /implementaudit plan and execute this bounded repo change
   /implementaudit design this new governed capability
   /implementaudit improve this existing subsystem without regressions
   /implementaudit audit this repo and produce the next executable plan
   

   Unbounded or unsafe requests produce an explicit STOP or owner-decision boundary, not an uncontrolled build loop.

3. IMPLEMENTAUDIT classifies the work as greenfield, brownfield, or mixed; selects the warranted planning and improvement route; and then executes through its nested planner, run, phase, Andon, and audit-fix loops.

   Depending on the work, outputs may include owner/source discovery, acceptance and rollback planning, a findings ledger, Smoke A baseline evidence, bounded patches, Smoke B comparison, independent review, run-root state, and terminal transcript markers ending in AUDIT_COMPLETE plus IMPLEMENTAUDIT_RUN_COMPLETE—or an explicit audited handoff with the evidence and next actions needed to resume.

   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 package contents and shipped-scripts reference.

4. Nothing is committed, pushed, tagged, released, or published unless you explicitly authorise that action.

Runtime at a glance

goal / audit / plan / repo task
    ↓
bounded audit object
    ↓
live-repo Gemba + owner/source discovery
    ↓
greenfield / brownfield / mixed routing
    ↓
plan / design / improve / implement
    ↓
Smoke A/B + evidence + review
    ↓
Andon → evidence → Hansei → proportional 5 Whys → countermeasure
    ↓
re-verification
    ↓
AUDIT_COMPLETE or explicit audited handoff

IMPLEMENTAUDIT is not one flat retry loop. It is a system of nested engineering loops: the planner prepares and preflights the work; the run advances through resumable phases; each phase executes and verifies a bounded unit; Andon can stop and correct any other loop; and the final audit-fix loop alone can establish terminal closure.

Governor, specialised cognition, and work topology

/implementaudit remains the stable public/default governor. It derives the current condition, keeps authority and lifecycle control, and progressively loads at most one specialised child for that derivation when the extra cognition earns its context cost:

Child skill	Bounded question it helps answer
audit-state	What state is decision-usably current after restart, handoff, compaction, or identity ambiguity?
audit-assess	What does an independent, adversarial examination find about the work or evidence?
audit-implement	What implementation is actually realised for this exact candidate and claim across the applicable evidence surfaces?
audit-andon	What diagnosis, local-vs-systemic classification, countermeasure, and follow-up does an established abnormality warrant?

These are cross-cutting cognitive capabilities, not L1-L5 stages and not a child-to-child pipeline. Each returns a bounded result to the governor (or, for an explicit audit-andon cord-pull, to the actual caller) and cannot grant currentness, mutation authority, lifecycle progress, PASS, release, or terminal closure. The five L1-L5 loops remain the operational control system.

Work topology is a separate dimension. The state-derived DAG and child agents provide horizontal, dependency-correct work lanes; child skills provide vertical progressive cognitive disclosure inside one governor derivation. A JOIN belongs to the governor/DAG machinery. After evidence changes, the governor re-derives the current state and READY/BLOCKED frontier instead of blindly following a stale plan.

The canonical plugin exposes the four child skill files to a capable host. The generated standalone compatibility projection deliberately exposes only the governor SKILL.md; its exact resolver maps governed requests to the four non-discoverable internal-procedures/ projections and fails closed on a missing, extra, or ambiguous population. Where a host does not independently discover audit-andon, a cord-pull enters through /implementaudit; package structure and routing checks do not by themselves prove host activation.

Why IMPLEMENTAUDIT is stronger than a bare /goal

A bare /goal carries an intended end state.

For simple work, or when a highly capable model is already surrounded by a strong execution harness, that may be enough.

The goal itself, however, does not guarantee repository Gemba, owner/source discovery, bounded scope, durable state, rollback and evidence planning, failure-origin diagnosis, independent review, or proof of terminal closure.

IMPLEMENTAUDIT can run inside /goal; it supplies that engineering harness.

It normalises the request into a bounded audit object, routes greenfield and brownfield work through the warranted DMADV or DMAIC method, persists resumable phase state, and governs five nested loops from planning through audit-fix.

Those loops are corrective, not blind retries.

Contradictory evidence triggers Andon; Hansei and proportional 5 Whys identify what failed; the smallest owner/source countermeasure is applied; and Smoke A/B, readback, review, and final audit then re-establish—or refuse—closure. Repeated same-class failure must eventually cause the governing mechanism to be questioned rather than merely consuming another attempt.

A stronger model still helps.

IMPLEMENTAUDIT's advantage is that these disciplines are externalised, durable, and auditable instead of being left for the model to remember or reinvent.

For non-trivial repository work, /goal using /implementaudit ... is therefore more reliable than a bare /goal: /goal carries the destination; IMPLEMENTAUDIT governs and proves the route.

What it is

/implementaudit is an audit-governed planning, design, implementation, improvement, review, recovery, integration, and closure system for repository work.

It accepts bounded audits, findings, handoffs, checklists, reviews, goals, tasks, gaps, plans, and natural-language repo-build requests. It plans deeply, routes greenfield, brownfield, and mixed work through the warranted quality method, and proceeds phase by phase until verified terminal closure or an explicit audited handoff.

It does not trust a plan merely because it survived in chat. After restart, handoff, or compaction, it re-establishes repository identity, owner and authority, currentness, and relevant evidence before acting.

Read-only planning, audit, review, direction, and handoff modes may produce artifacts without mutating source. When implementation is authorized, changes must remain auditable, bounded, owner/source-grounded, reversible, and non-overclaimed, with acceptance criteria, rollback and evidence planning, fixtures or checkers where warranted, and smoke-before-claim closure.

The system does not treat effort, generated deliverables, or a successful tool invocation as proof that the intended outcome was reached. It is not a generic autonomous build runner, release bot, package publisher, or provenance system.

The current runtime combines repository Gemba, risk-proportional planning, resumable phase state, baseline/post-change comparison, independent review, failure-family convergence, evaluator integrity, package semantic preservation, and public-projection checks. These are engineering controls, not a promise that every task needs every control: the method selects and records only the work justified by the live risk and evidence gap.

Release chronology and exact campaign accounting belong in CHANGELOG.md and the v0.4.0.0 release report. The optional dashboard remains outside the shipped .skill package.

The current bootloader architecture keeps weak-executor safeguards in progressive references/templates: final reports, optional Graphify-assisted Gemba, first-run tooling onboarding, commit granularity, broad rewrite thresholds, and 5-Whys loop exit. Read-only audit/plan/review/direction work may write human-readable plans/ outputs, but that lane does not authorise source mutation and does not replace .IMPLEMENTAUDIT/runs/ for implementation.

Warranted planning depth is not optional detail behind progressive disclosure. The action-selection contract in skills/implementaudit/references/planning-depth.md requires ordinary task-shaped invocations to derive the warranted ydqyq-audit-action set from scope, uncertainty, risk, dependencies, evidence gaps, authorisation state, and intended executor — recording both selected and omitted actions with reasons — with no activation keywords.

Phase reconstructibility is a native quality requirement (Rule P4-10 in skills/implementaudit/references/phase-design.md): newly authored phase specs carry ordered implementation steps with exact file/symbol targets and per-step verification, explicit scope boundaries, and plan-specific STOP conditions; validate-phase.sh rejects vague step language and boilerplate STOPs, and the read-only handoff lane aligns on the same bar.

Specialist fanout is binding where material coverage demands it (skills/implementaudit/references/child-agents.md): actual bounded lanes — parallel when the host supports subagents, serialised as separate bounded written passes when it does not — each dispatched under the per-lane prompt contract and recorded as coverage-lane records in the audit object. A coverage table documents executed lanes; it never substitutes for them, and a warranted lane is never silently dropped.

Executor-facing artifacts also pass an independent cold review (Stage 6.i) before preflight, dispatch, or handoff: a fresh-context reviewer — a separate child agent where the host supports subagents, otherwise a bounded serial fresh-context pass — records PASS / GAP-REVISE / BLOCKED / OWNER DECISION in the audit object. Self-critique is preserved, not replaced, and the roadmap execution index stays a derivative projection of the audit object, never canonical.

Current optional-tooling architecture:

flowchart TB
  G["`Graphify
  optional scoped terrain
  orientation only`"]
  T["`TokenSave
  optional supported-code navigation
  derived evidence only`"]
  I["`IMPLEMENTAUDIT
  engineering and assurance method`"]
  L["`Live repository files
  authoritative state`"]
  R["`Run root and evidence
  authoritative run state`"]
  M["`Markdown evidence
  first-class fallback`"]
  A["`ActiveGraph
  optional checkpoint or mirror
  not lifecycle authority`"]
  C["`Capability Ledger
  derived history
  not proof by itself`"]

  G -.->|suggests where to inspect| I
  T -.->|maps supported code relations| I
  I -->|must verify claims against| L
  I -->|records governed execution in| R
  R -.->|may mirror when authorised| A
  R -->|supports derived entries| C
  I -->|uses when sidecars are absent| M

Loading

Progressive policy: optional tools are optional everywhere — absence blocks nothing, /implementaudit remains fully usable with none installed, and Markdown fallback is first-class. This repo is the dogfood evidence base, not a universal capability claim. Graphify is narrowed to first-contact terrain orientation when every trigger holds; TokenSave to derived supported-code navigation when the walk earns its cost; ActiveGraph to authorized fork / diff checkpoint assistance and an optional non-authoritative mirror. Consumers inherit no maintenance obligation. No optional tool replaces the run root, live-file gates, or proof.

Quick Vocabulary, Not Authority

This section is onboarding shorthand. Runtime authority lives in skills/implementaudit/references/routing.md, skills/implementaudit/references/lean-operating-discipline.md, and skills/implementaudit/references/plan-lifecycle.md; this README points to those owners instead of replacing them.

• 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.
• TokenSave: optional supported-code navigation; derived evidence only.
• ActiveGraph: optional fork/diff checkpoint aid or non-authoritative mirror; 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 govern and the evidence expected for closure or handoff. It may contain findings to close, a plan to produce, a greenfield design, a brownfield improvement, a review, a goal, a gap, or a bounded implementation task.

/implementaudit normalises that input into an audit object, selects the warranted route, finds owner/source, records the relevant baseline, performs authorized work, captures post-change evidence, and resolves every declared item as done, changed, blocked, deferred, or unverified.

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, authorises 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 four common invocation shapes:

flowchart TB
  Final["`Terminal audit-object closure
  AUDIT_COMPLETE before
  IMPLEMENTAUDIT_RUN_COMPLETE`"]:::success

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

  subgraph Embedded["Embedded governance"]
    EIn["`Input
    /goal already owns the run
    using /implementaudit`"]:::input
    EObj["`tdqyq-audit-object
    owned by outer /goal`"]:::artifact
    ELoop["`ydqyq-audit-action
    govern inside supplied target`"]:::loop
    EArt["`Artifacts
    active goal evidence
    ledger updates
    repo-local checks`"]:::artifact
    EGoal["`Continue inside outer goal
    a second /goal is not emitted`"]:::boundary
    EIn --> EObj --> ELoop --> EArt --> EGoal
  end

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

  subgraph Casual["Governed casual-build intake"]
    CIn["`Input
    natural-language repo-build intent
    no audit artifact yet`"]:::input
    CObj["`tdqyq-audit-object
    synthesized by 5-step intake
    owner/source · criteria · rollback`"]:::artifact
    CLoop["`ydqyq-audit-action
    route greenfield / brownfield / mixed
    then govern as direct`"]:::loop
    CArt["`Artifacts
    bounded intake record
    STOP on unbounded / unsafe /
    non-repo input`"]:::artifact
    CGoal["`Continue directly
    no second /goal`"]:::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 normalises 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 synthesises 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/implementaudit/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.i - Independent cold review
Stage 6.ii - 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>/. In a source checkout, the claim helper lives at skills/implementaudit/scripts/claim-run.sh; in the installed flat archive it loads as scripts/claim-run.sh under the active skill directory. 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 recognisable audit artifact
• normalises 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.

Default repo-audit and plan-synthesis work also applies the shipped audit category matrix unless the input narrows scope: correctness/bugs, security/privacy, performance/scale, tests/validation, architecture/tech debt, dependencies/migrations, DX/tooling, docs/handoff, and direction/design. Deep analysis and security review are pressures inside the audit object. Direction and roadmap candidates route through DMADV and stay separate from defect closure. Plan creation, review, dispatch, and reconciliation follow skills/implementaudit/references/plan-lifecycle.md; issue publication remains deferred.

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 first-contact terrain only for an unfamiliar, majority-code repo and a terrain-shaped question that deterministic search cannot answer. Reference-shaped questions use rg, git grep, git ls-tree, direct reads, or native Git. ActiveGraph may assist authorized fork / diff checkpoint work; event stores are optional mirrors. Markdown ledgers and final reports remain valid fallback. Neither optional sidecar replaces repo-local owners, fixtures, checkers, smoke output, the run root, or audit ledgers.

Operating method

The method combines these onboarding handles. The owning runtime contracts are the references named below, not this short README list:

• PDCA: plan the smallest safe change, do it, check evidence, then standardise 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 terminal status, plus sustain/control when recurrence is repaired.
• Lean operating discipline: Lean/TPS terms map to auditable runtime behavior documented in skills/implementaudit/references/lean-operating-discipline.md. Brownfield improvement routes through DMAIC (Define→Measure→Analyse→Improve→Control); greenfield or replacement routes through DMADV (Define→Measure→Analyse→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
  greenfield / brownfield / mixed
  brownfield recon is read-only`"]:::audit
  OwnerDecision(["`OWNER DECISION
  unsafe request or AGENTS/policy conflict`"]):::blocker

  Graphify["`Graphify qualified first-contact terrain
  freshness checked; not proof`"]:::optional
  Gemba["`Live-file Gemba
  confirm owner/source before mutation`"]:::source
  SmokeA["`Smoke A
  baseline before change`"]:::checker
  Patch["`Patch owner/source
  bounded P0 -> P1 -> P2`"]:::source
  Generated["`Refresh generated artifacts
  from source/generator`"]:::generated
  SmokeB["`Smoke B + complete
  working-tree-vs-baseline check`"]:::checker

  ActiveGraph["`ActiveGraph fork/diff checkpoint
  optional non-authoritative mirror`"]:::optional
  Ledger["`Capability Ledger or
  Markdown final report fallback`"]:::audit

  Andon["`Andon / handoff loop
  abnormality -> 5 Whys -> Hansei
  countermeasure -> rerun`"]:::blocker
  Final["`Final audit
  criteria, boundaries, evidence`"]:::audit
  AuditDone(["AUDIT_COMPLETE"]):::success
  RunDone(["IMPLEMENTAUDIT_RUN_COMPLETE"]):::success
  NoRelease["`Ordinary completion default
  No tag, release, publication, or provenance`"]:::audit
  ReleaseGate{"`Separate release/provenance gate
  explicitly authorized?`"}:::release
  Release["`Tag / release / asset
  checksum manifest only if produced and verified`"]:::release
  Legend["`Legend: solid arrows are governed flow; dashed arrows are conditional or optional;
  blue is authoritative source; purple is generated; green is evidence; red stops the line`"]:::audit

  subgraph PhasedRun["Phased planned run — goal synthesis path"]
    RunRoot["`Run-root claim
    claim-run.sh
    .IMPLEMENTAUDIT/runs/slug-id/`"]:::source
    Stage6["`Stage 6
    plan review + self-critique
    revision menu`"]:::audit
    Stage6i["`Stage 6.i independent cold review
    PASS / GAP-REVISE / BLOCKED / OWNER DECISION`"]:::audit
    Stage6ii["`Stage 6.ii preflight smoke
    PREFLIGHT_GREEN / PREFLIGHT_RED`"]:::checker
    Stage7["`Stage 7 handoff
    one-paste /implementaudit
    omitted if embedded`"]:::audit
    PhaseSpec["`validate-phase.sh
    each phase spec
    exit 0 required`"]:::checker
    PhaseLoop["`16-step phase loop
    Smoke A -> execute -> cmds
    criteria -> cleanliness -> Smoke B`"]:::source
    Recovery["`Andon escalation, no try cap
    ANDON_PROBE -> ANDON_ESCALATE
    -> ANDON_HANDOFF only when blocked`"]:::blocker
    AuditFix["`Final audit + audit-fix rounds
    loop until closed or audited handoff
    AUDIT_GAPS -> fix -> re-round`"]:::audit
    RunRoot --> Stage6 --> Stage6i --> Stage6ii --> 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 orientation; never proof .-> Gemba
  Gemba --> SmokeA --> Patch --> Generated --> SmokeB
  SmokeB -. optional mirror after evidence .-> ActiveGraph
  SmokeB --> Ledger
  ActiveGraph -. non-authoritative input .-> 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, authorisation 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, authorisation 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

IMPLEMENTAUDIT is a self-correcting system of nested engineering loops. A run can end in AUDIT_COMPLETE plus IMPLEMENTAUDIT_RUN_COMPLETE, or it can end in AUDIT_HANDOFF, blocked, deferred, or unverified with enough durable evidence for a later agent to resume, audit, or repair the work without pretending closure occurred.

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 -> preserve evidence -> classify 
-> Hansei -> proportional 5 Whys when warranted 
-> smallest countermeasure -> rerun relevant checks 
-> close/defer/block with evidence

Nested loop model

A full IMPLEMENTAUDIT run uses five nested, concentric loops. Each loop has its own entry condition, exit condition, responsibility, 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 authorisation, 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, Authorisation, Not saved). Run roots are run artifacts, not package source, and are excluded from evidence scans and commits.

The source skill payload lives under skills/implementaudit/. 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 canonical plugin archive contains both host manifests, package/inventory metadata, and the runtime tree under skills/implementaudit/. The standalone .skill compatibility archive contains the flattened runtime payload plus the same package/inventory metadata, but no host manifests. Repo docs, tests, fixtures, release tooling, audit ledgers, run roots, and sidecar stores are excluded from both projections.

Skill internals / repository layout

Source layout vs release package projections

This repo uses the conventional name-matched source skill layout:

skills/implementaudit/SKILL.md
skills/audit-state/SKILL.md
skills/audit-assess/SKILL.md
skills/audit-implement/SKILL.md
skills/audit-andon/SKILL.md
skills/implementaudit/references/
skills/implementaudit/scripts/
skills/implementaudit/templates/

skills/implementaudit/SKILL.md is the canonical source behavior entry and /implementaudit is the sole stable public/default governor. The v0.4 package contains exactly four child skills—audit-state, audit-assess, maintainer-only audit-implement, and dual-entry audit-andon—while keeping references, scripts, and templates as shared resources rather than duplicating deterministic substrate. Each internal skill returns bounded cognition and grants no lifecycle, mutation, release, closure, or AUDIT_COMPLETE authority. Governor-routed use returns to the governor; a directly discovered canonical audit-andon returns to the actual caller and grants no new authority. The standalone projection keeps only the governor discoverable and resolves cord-pull requests through its bounded internal procedure. Planning and execution/repair remain progressively loaded governor/reference cognition, not child skills.

package/implementaudit-package.json owns the single-package contract. The canonical IMPLEMENTAUDIT.plugin.zip projection preserves the conventional skills/implementaudit/ tree and both host manifests. The generated, checksummed IMPLEMENTAUDIT.skill compatibility projection alone flattens the runtime tree to archive-root SKILL.md, references/, scripts/, and templates/; it carries deterministic projections of the four internal procedures and package/inventory metadata but no plugin manifests, nested skills/ directory, or independently discoverable child packages. There is intentionally no tracked root IMPLEMENTAUDIT.md file; validators fail if one is recreated. Audit handoff inputs named AUDIT.md remain valid.

Host metadata is dual-host and version-coherent inside the one package:

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

Both plugin manifests point to ./skills/; the package contract and manifest JSON are validated by scripts/verify-package.sh. This README records the bounded historical v0.3.3.3 publication and the final corrected same-identity release below. It claims the in-place asset, checksum, body, and tag correction only after independent public readback, and does not claim Codex or Claude native plugin discovery, Claude Code marketplace behaviour, passive update, active-user installation, universal host loading, or provenance without the corresponding host or public evidence.

Version and release notes

Current project milestone: published v0.4.0.0; plugin/runtime version 0.4.0.

The canonical title is State Synthesis Substrate Engineering: Evolved-SSDDRFCSS. The protected compact label is S³E wherever used. The four-component public milestone maps to the three-component runtime family. The annotated tag, GitHub Release, three exact assets and Pages deployment are published and independently read back; source composition alone would not have established those effects.

The prior v0.3.3.3 tag and release remain append-only historical evidence. Qualification and authorised publication evidence belongs in the v0.4.0.0 release report; release chronology and user-visible changes belong in CHANGELOG.md. This README describes the current product and installation routes rather than duplicating either evidence record.

A source checkout may contain changes made after the release tag. A checkout, locally built asset, and published release asset are therefore distinct install sources and should not be treated as byte-identical without verification.

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.

In a source checkout, the child-agent reference lives at skills/implementaudit/references/child-agents.md and the report template lives at skills/implementaudit/templates/child-agent-report.md. In the installed flat archive, those load as references/child-agents.md and templates/child-agent-report.md under the active skill directory. 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 authorise edits, commits, pushes, installs, indexing, exports, releases, publication, or provenance. The main /implementaudit agent must normalise reviewer findings into the ledger and inspect live files before patching or closing them.

Optional tooling

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

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

First-run onboarding

On first runs, /implementaudit may detect Graphify and ActiveGraph availability. TokenSave is explicit, on-demand optional tooling; it is not automatically detected or routed. Missing tools are not errors.

Default behavior:

• detect and record availability only through shipped detector routes
• continue safely without optional tooling when absent
• print install/configure commands as documentation when useful
• install or configure tools only with explicit authorisation 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 authorisation. Installation does not authorise indexing, event-store setup, export, commit, push, tag, release, publication, or provenance. graphify install is not recommended until its isolated fake-home registration check passes across the intended platform targets.

Graphify-assisted Gemba

Graphify is an optional first-contact terrain map for an unfamiliar, majority-code repository when a terrain question is not answered cheaply by direct search. Its scope catalogue can select the smallest graph covering the named paths, check freshness only for that scope, and broaden to a recorded parent only for a named cross-scope need. Scope or freshness failure is distinct from an extractor/relation-model omission: when the graph does not represent the needed relation, return to deterministic live-file search rather than asking a model to invent it.

Graphify output is orientation evidence, not proof. It cannot decide closure, authorise mutation, replace live-file inspection, or override repo instructions. The qualified route is deterministic and does not qualify semantic/Luna behaviour; Ollama is explicitly unauthorized. Detailed scope, catalogue, freshness, privacy, and backend boundaries live in references/sidecars.md.

TokenSave-assisted code navigation

TokenSave is an optional deterministic navigation layer for supported code relations when a repeated or transitive dependency walk earns its indexing and query cost. Only an operator/checker-controlled adapter outside candidate authority can establish currentness; claim fields alone never do. The checker runs its fixed supported sync/reconnect route against the live checkout and compares the strict result with the claimed checkout/database expectation. An absent, failed, timed-out, malformed or mismatched execution is TOKENSAVE_FRESHNESS_UNVERIFIED, never derived-current, and routes to ordinary Gemba. A successfully established current result is derived evidence about the represented code, not complete program truth. Consequential symbol, caller/callee, impact, context or test-mapping findings still require live-source confirmation; stale, unsupported, extraction-failed or conflicting results route to ordinary Gemba.

Documentation, policy, public projection, arbitrary non-code artefacts, an exact file already supplied, and tiny reversible work are cheap NO TOKENSAVE paths. Installation, indexing and configuration require separate authorisation. Its repo-local database is a representation-specific storage exception that can retain source bodies and rendered-source cache, so it requires explicit retention/cleanup disclosure and stays untracked and outside packages. IMPLEMENTAUDIT does not adopt TokenSave's editing, test-running, session/memory tools, broad auto-approval, or discovery- interception hooks. Detailed evidence, privacy, freshness and authority limits live in references/sidecars.md.

ActiveGraph checkpoint assistance and optional mirror

ActiveGraph may assist an authorised fork/diff checkpoint or hold a separately authorised non-authoritative mirror. The run root and live files remain the authority; ActiveGraph custody is not correctness proof. Capability Ledger entries are derived from recorded gate passages, not from the existence of a mirror. When ActiveGraph is absent, Markdown state and final reports are the first-class fallback. The detailed event, backfill, and custody rules live in references/sidecars.md.

That is the generic product boundary: ActiveGraph is optional, non-authoritative, and not a package dependency. This repository's final governed self-dogfood is stricter by design. It must use an isolated, exact-state-bound ActiveGraph sidecar on the latest independently verified published release available when that gate executes. The self-dogfood requirement neither changes generic /implementaudit semantics nor permits ActiveGraph to replace live-file, run-root, package, test, or host evidence.

Evidence boundaries

Interop boundaries are explicit:

• Graphify-supported behaviour must be distinguished from ImplementAudit heuristics.
• Graphify summaries and graph output are not proof.
• TokenSave code relations are derived evidence, not repository completeness, mutation authority, or acceptance 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 authorisation 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 synthesises a bounded audit object from the description before routing. To choose the right invocation shape, see the chooser table in skills/implementaudit/references/goal-format.md and the onboarding portal generated by scripts/build-docs-portal.py.

Install notes

Install flows are evidence-bounded. The normal release/install unit is one atomic dual-host plugin artifact IMPLEMENTAUDIT.plugin.zip; the generated IMPLEMENTAUDIT.skill remains available only as a standalone compatibility projection. This repo can locally validate artifact shape, checksum identity, staged plugin copy, and standalone temporary-install paths. None of those alone proves native host discovery, invocation, passive update, universal host support, marketplace verification, or public GitHub release download.

Release/contract alignment: the published public identity is v0.4.0.0, with plugin/runtime version 0.4.0. Fresh public download/readback reproduced the frozen exact-tree asset bytes, inventories and SHA-256 values recorded in the release report. That does not establish native host loading or provenance.

A checkout of main may contain post-release source changes. Installing from a checkout or through a CLI that resolves current main uses source-checkout semantics; it is not automatically byte-identical to the tagged v0.4.0.0 assets. Re-verify this paragraph at every release gate.

Quick install via the skills CLI

The repo layout is compatible with the open skills CLI (verified 2026-08-05: source discovery finds the one skill implementaudit; both agent targets install the full runtime payload — SKILL.md + references/ + scripts/ + templates/ — plus a skills-lock.json):

That dated observation describes the prior source-discovery route; it neither describes the current canonical plugin population nor proves native host discovery or activation.

npx --yes skills add theislampill/IMPLEMENTAUDIT.md                              # interactive
npx --yes skills add theislampill/IMPLEMENTAUDIT.md --skill '*' --agent claude-code --copy -y
npx --yes skills add theislampill/IMPLEMENTAUDIT.md --skill '*' --agent codex --copy -y

Installs are project-level by default (./.claude/skills/ for claude-code, ./.agents/skills/ for codex); add -g for a user-level install. Note the evidence boundary above still applies: the CLI installs from the repo's current main (source checkout semantics — post-release repairs included), not from a verified release asset; the release-asset path with checksum verification remains the sections below. The directory page https://skills.sh/theislampill/IMPLEMENTAUDIT.md is populated by the ecosystem's install-telemetry index, not by this repo.

Choose the source deliberately:

• the published v0.4.0.0 artifacts were built, qualified, independently reviewed, downloaded, checksum-verified, and installed in isolated projections;
• the current source contains the packaged R001D correction and later native runtime countermeasures;
• a local archive is evidence only for the exact source tree from which it was built.

The current product surface includes shipped-helper reachability, executor-ready work orders, bounded state-space convergence, engineering-value and informational-independence controls, evaluator and candidate-controlled validation-policy integrity, package semantic preservation, public-projection discipline, and optional freshness-aware Graphify terrain. The canonical runtime references define those behaviours; the v0.4.0.0 release report keeps source, package, install, hosted and public evidence separate. /dashboard/ is not part of either generated package projection.

Install / update the canonical dual-host plugin

IMPLEMENTAUDIT.plugin.zip is the primary atomic package for Codex and Claude. It contains both host manifests, package/inventory metadata, one governor and exactly four child skills under skills/: implementaudit, audit-state, audit-assess, audit-implement, and audit-andon. Use the current native plugin installation route documented by the host, then verify that the host discovers /implementaudit from the expected version before claiming a loaded installation. The presence of a manifest or copied files is not host-load proof.

For a local candidate, build and checksum both generated projections:

bash scripts/build-release-asset.sh
bash scripts/write-release-checksums.sh --all dist dist/CHECKSUMS.txt
bash scripts/write-release-checksums.sh --check --all dist dist/CHECKSUMS.txt

The repository's plugin installer is deliberately an isolated staged-copy proof, not a native-host installer. Point it only at a disposable directory containing .implementaudit-isolated-host-root:

bash scripts/install-plugin-from-release.sh \
  --asset dist/IMPLEMENTAUDIT.plugin.zip \
  --checksum dist/CHECKSUMS.txt \
  --host codex \
  --host-root "<isolated-host-root>" \
  --version 0.4.0

Repeat with --host claude for the separate staged Claude projection check. Passing either command proves checked package copy, inventory, update, rollback, and post-readback behaviour only. Native discovery and invocation remain host evidence; the tagged public-download identity has independent readback, while native host discovery and invocation still require their own host evidence.

Standalone compatibility 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.

Do not copy only skills/implementaudit/ from the source tree: that subtree is the governor plus shared substrate and omits the four required child sources. Use the generated standalone artifact and installer below so the exact flattened population, package identity, update policy, readback, and rollback are checked as one transaction.

For the generated standalone compatibility artifact, build both projections, write the shared checksum manifest, and install .skill with checksum verification:

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

The published v0.4.0.0 public-tag command below installs the independently read-back standalone release asset. Use the local route above only when you deliberately want an exact locally built source projection instead:

bash scripts/install-codex-from-release.sh \
  --url https://github.com/theislampill/IMPLEMENTAUDIT.md/releases/download/v0.4.0.0/IMPLEMENTAUDIT.skill \
  --codex-home "$HOME/.codex" \
  --version 0.4.0

The compatibility archive is a flattened projection with package/inventory metadata and no plugin manifests. Its local install receipt does not claim canonical plugin installation, passive update, public availability, universal host support, or host-load behaviour. For local verification, download CHECKSUMS.txt alongside IMPLEMENTAUDIT.skill and use the --asset plus --checksum form shown above.

Standalone compatibility 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"

Install the independently read-back v0.4.0.0 release asset with:

bash scripts/install-claude-from-release.sh \
  --url https://github.com/theislampill/IMPLEMENTAUDIT.md/releases/download/v0.4.0.0/IMPLEMENTAUDIT.skill \
  --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.

Native Claude Code plugin path

Claude Code plugin consumers should use the host's current plugin instructions with canonical IMPLEMENTAUDIT.plugin.zip. Its .claude-plugin/plugin.json points to the same ./skills/ tree as the Codex manifest. Package validation and an isolated staged-copy receipt do not by themselves prove native host install, discovery, invocation, or marketplace behavior.

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 plugin in the host you use. Do not assume a local plugin or standalone compatibility copy has updated just because the GitHub repo has a new release.

No marketplace auto-update or passive auto-update is claimed for either host. Canonical plugin users should follow the host's current update/reload route and verify the loaded version. Standalone compatibility users must repeat the chosen copy or .skill install route; Claude Desktop users should then restart the application. Return to Install notes for the commands and evidence boundaries.

Release asset notes

The primary GitHub release asset name is IMPLEMENTAUDIT.plugin.zip. It is one atomic, version-coherent dual-host plugin package:

.codex-plugin/plugin.json  (skills: "./skills/")
.claude-plugin/
.claude-plugin/plugin.json  (skills: "./skills/")
.claude-plugin/marketplace.json
IMPLEMENTAUDIT_PACKAGE.json
IMPLEMENTAUDIT_INVENTORY.json
skills/implementaudit/SKILL.md
skills/audit-state/SKILL.md
skills/audit-assess/SKILL.md
skills/audit-implement/SKILL.md
skills/audit-andon/SKILL.md
skills/implementaudit/references/
skills/implementaudit/scripts/
skills/implementaudit/templates/

It exposes only /implementaudit as the stable public/default governor and has exactly four child skills in v0.4: audit-state, audit-assess, maintainer-only audit-implement, and dual-entry audit-andon. IMPLEMENTAUDIT.skill is generated and checksummed from the same source as a flattened standalone compatibility artifact. It is not the canonical topology, a second independently versioned package, or proof that .skill is a universal host-standard archive format.

Both release projections intentionally exclude repo-maintenance material such as README sources, audit ledgers, fixtures, tests, CI configuration, Git metadata, run roots, Graphify outputs, ActiveGraph stores, and root validation scripts. Those remain repository-side evidence or maintenance surfaces, not installed runtime payload.

A published CHECKSUMS.txt proves only the integrity of the named plugin and compatibility-asset bytes; it is not a signature, attestation, SBOM, licence, marketplace verification, install proof, or provenance claim. Building, uploading, or replacing an asset is a separate authorised release operation. Maintainer build and publication commands belong in CONTRIBUTING.md.

Validation and release evidence

Validation is layered. A source check, deterministic fixture, generated-doc check, package extraction, temporary-home install, live host run, hosted CI result, public deployment, and fresh download establish different properties; none silently substitutes for another. Claims must name the layer that actually ran and bind it to the relevant source, tree, package, or public bytes. When material meaning depends on rendered, generated, visual, layout-sensitive, or otherwise representation-dependent output, source and generator checks require both rendered-consumer validation and governed-detail preservation. Ordinary non-layout-sensitive prose stays on the cheaper content path.

The current evidence index is docs/audits/INDEX.md, with retention rules in docs/audits/RETENTION.md. The exact candidate qualification and any later publication readbacks belong in the v0.4.0.0 release report. Contributor checks, package validation, generated-doc regeneration, and release boundaries belong in CONTRIBUTING.md.

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 authorisation does not imply push authorisation. Push authorisation does not imply tag, release, publication, or provenance authorisation.

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 authorisation
• resolve audit-vs-AGENTS.md conflicts by agent judgment
• use AGENTS.md as a raw evidence dump

Contributing and deeper documentation

CONTRIBUTING.md is the maintainer and contributor entry point: it explains instruction precedence, canonical and generated owners, platform requirements, focused and package validation, contribution boundaries, and release-authority gates. The source skill contract remains skills/implementaudit/SKILL.md, with deeper runtime detail under its references/.

For current public documentation, use the repository docs portal. For release chronology use CHANGELOG.md; for exact qualification and publication evidence use the audit index and named release reports.

The repository's Research & Engineering Lineage source explains Evolved-LAW, Evolved-CSS, Evolved-SSD and Evolved-DRF at property level. The repository genealogy corpus is retained in the v0.4.0.0 source tree as exact research memory, remains excluded from both runtime package projections, and does not activate the deferred v0.4.1 reabsorption campaign. The integrated research route reports 658/658 property disposition accounting, not 658 source changes. It preserves rejected, unresolved and owner-decision evidence and adds no nine runtimes, lineage selector, methodology mode, or universal-effectiveness claim. Hosted-current status still requires separate Pages publication and readback. Research guided accretion only where dogfood, failure witnesses, or exact checks could change a decision; the retained lineage is context and genealogy, not implementation proof.