Skip to content

APG v0.4.0

Choose a tag to compare

View all tags
@lair001 lair001 released this 27 Jul 00:44
· 6 commits to main since this release
v0.4.0
d23a094

APG v0.4.0 — Manager Topology, Test Profiles, and Reproducible Evidence

Agentic Praxis Grimoire v0.4.0 expands APG from 19 to 28 public skills and strengthens the infrastructure used to select, test, report, validate, and publish them.

This release introduces a dedicated ChatGPT-manager topology, nine new provisional capabilities, a Python-first operational-reporting core, a pytest-based test architecture with explicit coverage gates, and version-aware public-release validation. It preserves APG's existing authority boundaries: skills provide bounded procedures and judgment, but do not grant permission, invent project policy, or silently expand a task.

Release snapshot

  • 28 canonical public skills
  • 28 catalog rows
  • 28 checked-in Codex discovery projections
  • 14 stable skills
  • 14 provisional skills
  • 26 general-router entries
  • 1 ChatGPT-local router entry
  • 27 mechanically checked route edges
  • 9 newly published skills
  • Deterministic single-parent release history rooted in the preserved v0.1.0–v0.3.0 public lineage

Release inclusion remains independent of maturity. All nine v0.4 additions are published as provisional, rather than being promoted simply because the release includes them.

ChatGPT-manager topology

v0.4.0 introduces chatgpt-manager-workflow, a dedicated subrouter for ambiguous ChatGPT-manager work.

The new topology separates general APG process selection from ChatGPT-specific management procedures:

  • general APG ambiguity continues through the public APG workflow router;
  • ChatGPT-manager ambiguity enters one checked local subrouter;
  • valid direct skill selection remains authoritative;
  • the router selects the smallest sufficient manager capability—or none;
  • routing does not authorize dispatch, execution, acceptance, publication, or destructive action.

composing-approved-roadmap-assignments now has a canonical owner under the nested skills/chatgpt/ namespace. Its procedure remains distinct from planning, ordinary worker-assignment composition, dispatch, review, and acceptance.

Codex discovery remains intentionally flat: all 28 public skills are still projected under .agents/skills/, even where their canonical ownership is nested.

Nine new public skills

Management and migration

chatgpt-manager-workflow

Routes ambiguous ChatGPT-manager work to the smallest sufficient manager-specific capability while preserving explicit selection, human authority, and ordinary prompting as valid outcomes.

It is not a universal session bootstrap, mandatory chain, general APG router, or source of action authority.

converting-bash-scripts-to-python

Provides a bounded procedure for migrating an existing Bash executable or script family to Python.

The skill begins with characterization of the observable contract and requires compatibility to be preserved—or any deliberate migration to be made explicit. Generic implementation, testing, review, publication, and lifecycle decisions remain with their existing owners.

Test-framework and test-tool profiles

pytest-test-profile

Adds pytest-specific judgment for:

  • discovery and collection;
  • fixtures and parametrization;
  • mocks;
  • xdist behavior;
  • coverage;
  • warnings and failure interpretation.

The profile does not choose pytest, plugins, Python versions, worker counts, coverage thresholds, project commands, or external actions on behalf of the repository.

minitest-test-profile

Adds Minitest-specific guidance for test and spec organization, assertions, lifecycle hooks, mocks, stubs, fixtures, isolation, parallelism, filtering, runners, plugins, reporters, and external boundaries such as subprocesses, filesystems, and databases.

go-test-profile

Introduces an independent owner for native Go testing judgment. It remains separate from the Go language profile and from third-party assertion or comparison libraries.

go-cmp-test-profile

Introduces a distinct profile for go-cmp comparison semantics and option use.

Native Go testing and go-cmp remain separate owners. v0.4.0 does not introduce a unified Go testing-stack skill.

nix-test-profile

Adds Nix-test-specific guidance while explicitly preserving the distinction between source-reviewed claims and behavior verified in a running Nix environment.

This profile complements the stable nix-language-profile; it does not replace it or imply broad runtime and platform compatibility.

Build and development-environment profiles

dockerfile-profile

Adds Dockerfile-specific judgment for build definitions while leaving image selection, registry policy, runtime orchestration, deployment, CI/CD, secrets management, host configuration, and destructive operations to the target repository and operator.

vagrantfile-profile

Adds Vagrantfile-specific judgment covering configuration loading, machines, boxes, providers, networks, synced folders, provisioners, triggers, Vagrant state, and host-dependent behavior.

It remains bounded by repository policy and does not grant infrastructure-mutation authority.

Python-first operational reporting

v0.4.0 introduces a shared, dependency-free Python reporting core with:

  • a common report model and envelope;
  • Git CLI adaptation;
  • rendering;
  • destination and locking ownership;
  • operational framing;
  • thin command-line entry points.

The existing git-show-report and append-operational-report command families were characterized and migrated through this shared architecture. The release also adds git-diff-report.

The migration preserves defined behavior where required and records deliberate differences rather than treating a language rewrite as self-validating.

Formal phase-commit validation

The new apg-check-phase-commit-message command mechanically validates formal APG phase commit messages.

A compliant formal-phase message must contain:

  • the exact canonical phase subject;
  • Scope;
  • Result;
  • Verification;
  • Not run;

in the required order.

The checker can validate a message file or an existing Git commit. It verifies the adopted structural contract only; it does not establish that the report is truthful or that the work deserves acceptance.

Pytest architecture and coverage gates

APG's own Python test architecture now provides three explicit modes:

unit
integration
unit-integration

The managed runner:

  • defaults to eight xdist workers;
  • disables worker restarts;
  • accounts for worker and Python child processes;
  • preserves deterministic artifact ownership and cleanup;
  • measures component coverage independently;
  • computes combined statement and branch coverage as a union rather than averaging reports;
  • treats missing children, worker crashes, incomplete artifacts, and malformed results as failures.

The accepted gates are:

  • unit: at least 80% statement and 80% branch coverage;
  • integration: at least 80% statement and 80% branch coverage;
  • combined: at least 85% statement and 85% branch coverage.

Bats remains in use where an exact Python supersession has not been established.

Focused corrections to the stable process core

The six stable process skills retain their maturity and trigger boundaries, but v0.4.0 incorporates reviewed corrections around:

  • coverage-remediation hierarchy and stop conditions;
  • proportionate expansion from focused tests;
  • truthful distinctions between mocks and real boundaries;
  • formal-phase and ordinary-work defaults;
  • Git and operational evidence;
  • compression of approved-roadmap manager assignments.

These corrections were exercised through 51 frozen cases. They introduce no new mandatory workflow chain and do not broaden any skill's authority.

Version-aware release validation

The public-release and lifecycle tooling now distinguishes historical and current release surfaces by semantic version.

That means:

  • v0.2.0 and v0.3.0 retain their immutable historical inventories;
  • v0.4.0 is validated against its own 28-skill policy;
  • unsupported, malformed, truncated, retagged, or mismatched identities fail closed;
  • a current source cannot silently redefine what an older release was required to contain;
  • deterministic candidate construction and checking remain separate from publication authority.

The final v0.4.0 publication is one intentionally squashed Release v0.4.0 commit whose sole parent is exact public v0.3.0, together with an annotated v0.4.0 tag.

Deliberately not included

This release does not publish every candidate investigated during v0.4 development.

In particular:

  • matryer-is-test-profile is absent after material defects remained unresolved;
  • go-testing-stack is absent, and the proposed unified-stack architecture remains rejected;
  • native Go testing and go-cmp remain independent provisional owners;
  • no skill is promoted merely to make the release matrix look cleaner.

Deferral and rejection are valid outcomes when available evidence does not support a bounded public capability.

Maturity and compatibility limits

The stable catalog remains at 14 skills. The other 14 skills are provisional, including every capability added in v0.4.0.

Provisional means that a skill is sufficiently bounded and useful to publish, but its evidence still requires explicit limitations and continued observation.

Compatibility is established only where it was:

  • exercised on the current macOS environment;
  • explicitly source-reviewed;
  • fixture-reviewed;
  • marked not run; or
  • marked not applicable.

Publication does not establish:

  • universal applicability;
  • automatic invocation;
  • production warranty;
  • comparative superiority;
  • cross-platform compatibility;
  • target-runtime compatibility;
  • permission to mutate a repository, service, environment, or host.

The human-authorized task and target repository continue to own exact scope, architecture, privacy, test commands, dependencies, coverage policy, branches, releases, rollback, and destructive actions.

Updating a managed user-scoped installation

Use a clean checkout at the exact public v0.4.0 tag:

bin/apg-user-skills update --source <v0.4.0-public-checkout>
bin/apg-user-skills check

The managed lifecycle computes the exact retained, added, and removed skill names for the selected release and preserves rollback to the previously recorded source identity.

A full Codex restart may be necessary when the updated discovery set does not appear automatically.

Documentation

Assets 2
Loading