sirmmo/podlike

Can another program use it through a documented, machine-readable surface?

• next: [cli] L3 Machine-readable output (--json/--format) and documented exit statuses. (no --json/--format option)
• next: [library] L4 An API reference is generated from the code (autodoc, mkdocstrings, typedoc, …). (no generated API reference)

cli ladder · level 2

• ✓ L1 Invocable non-interactively: no prompts, or prompts guarded by a TTY check or a --yes/--no-input option. no interactive prompts
• ✓ L2 --help documents every option (at least 90% of options have help text). pkg/flags/flags.go 7 matches
• ✗ L3 Machine-readable output (--json/--format) and documented exit statuses. no --json/--format option
• ✗ L4 The output format is specified by a JSON Schema. no JSON Schema for the output

library ladder · level 3

• ✓ L1 An importable, packaged API exists. go.mod Go module with exported packages
• ✓ L2 The public API is delimited (__all__, an exports map, exported identifiers). go.mod exported identifiers
• ✓ L3 The public API is statically typed (py.typed, type declarations, a typed language). go.mod statically typed language
• ✗ L4 An API reference is generated from the code (autodoc, mkdocstrings, typedoc, …). no generated API reference

Can integrators rely on it not changing under them?

• next: L1 Releases are versioned (semver tags or versioned changelog sections). (no semver tags or versioned releases)

all ladder · level 0

• ✗ L1 Releases are versioned (semver tags or versioned changelog sections). no semver tags or versioned releases
• ✗ L2 A changelog exists and marks breaking changes. no changelog
• ✗ L3 A deprecation mechanism is used in code (warnings, @deprecated, Deprecation/Sunset headers) or the API is versioned. no deprecation mechanism or API versioning
• ✗ L4 Across tagged releases, no OpenAPI operation, CLI option or __all__ symbol was removed without first being deprecated. fewer than two tagged releases to compare

Can others react to state changes without polling?

Can a machine act with its own revocable, least-privilege identity?

Can its data get in and out, in bulk, in open formats, with an explicit schema?

Can an automated caller use it without guessing, and recover from failure?

• next: [cli] L2 Data on stdout, diagnostics on stderr, non-zero exit on failure. (diagnostics aren't written to stderr)
• next: [library] L1 Errors are specific exception types, and library code never calls sys.exit. (no exception classes)

cli ladder · level 1

• ✓ L1 Never blocks on a prompt when stdin is not a TTY. no interactive prompts
• ✗ L2 Data on stdout, diagnostics on stderr, non-zero exit on failure. diagnostics aren't written to stderr
• ✗ L3 Documented exit statuses distinguish error classes, errors are JSON in JSON mode, and color is off when not a TTY. documented exit statuses don't distinguish error classes
• ✗ L4 --dry-run, limits for long or costly operations (timeouts, budgets), and agent docs. no --dry-run

library ladder · level 0

• ✗ L1 Errors are specific exception types, and library code never calls sys.exit. no exception classes
• ✗ L2 Inputs are validated with messages naming the bad argument. no input validation errors
• ✗ L3 Timeouts and retries are configurable. no timeout parameter
• ✗ L4 Agent docs, and examples that run as tests (doctests). no agent docs

Can another system run and compose it without a human?

• next: [cli] L3 Published to a public registry and run non-interactively in CI. (not published to a registry)
• next: [library] L3 Published to a public registry, with at most 10 runtime dependencies. (not published to a registry)

cli ladder · level 2

• ✓ L1 Runnable from source (a declared entry point). cmd/healthcheck/main.go go maincmd/podlike/main.go go main
• ✓ L2 Installable as a package that provides the command. cmd/healthcheck/main.go go maincmd/podlike/main.go go main
• ✗ L3 Published to a public registry and run non-interactively in CI. not published to a registry
• ✓ L4 Also shipped as a container image or a single binary. Dockerfileexamples/healthz/app/Dockerfile

library ladder · level 2

• ✓ L1 Importable from source. go.mod Go module with exported packages
• ✓ L2 Installable as a package (a package manifest). go.mod package manifest
• ✗ L3 Published to a public registry, with at most 10 runtime dependencies. not published to a registry
• ✗ L4 Optional features behind extras/features. no optional extras

Can behaviour be added without modifying the code?

• next: L1 Internal seams: a registry, registration function or plugin manager. (no registry or registration function)

all ladder · level 0

• ✗ L1 Internal seams: a registry, registration function or plugin manager. no registry or registration function
• ✗ L2 The docs show how to add behaviour through those seams (even in-tree). no registration functions to document
• ✗ L3 Out-of-tree extensions are discovered (entry points, a plugin directory, configuration) without editing the package. extensions must be added inside the package
• ✗ L4 The extension API is versioned, has lifecycle hooks, and has example extensions. no lifecycle hooks

Can an operator, or an orchestrating agent, tell whether it works and why not?

• next: [cli] L1 Meaningful exit statuses, and errors on stderr. (diagnostics aren't written to stderr)
• next: [library] L1 Logs through a standard logger namespace and never prints from library code. (no standard logger)

cli ladder · level 0

• ✗ L1 Meaningful exit statuses, and errors on stderr. diagnostics aren't written to stderr
• ✗ L2 Verbosity control for diagnostics (--quiet, --log-level, --debug). no --quiet or log-level control
• ✗ L3 Structured logs (e.g. --log-format json) or a machine-readable run summary. no structured diagnostics
• ✗ L4 Tracing hooks (OpenTelemetry). no tracing hooks

library ladder · level 0

• ✗ L1 Logs through a standard logger namespace and never prints from library code. no standard logger
• ✗ L2 Log levels are used meaningfully (at least two levels). fewer than two log levels used
• ✗ L3 Optional metrics or tracing hooks. no metrics or tracing hooks
• ✗ L4 OpenTelemetry instrumentation available. no OpenTelemetry instrumentation

Can an agent change it safely with limited context?

• next: L4 No import cycles, and agent docs (AGENTS.md, CLAUDE.md, llms.txt). (no agent docs (AGENTS.md, CLAUDE.md, llms.txt))

all ladder · level 3

• ✓ L1 A README and some tests. README.mdpkg/component/config_test.go 14 test files
• ✓ L2 CI runs the tests; applications pin dependencies (libraries and zero-dependency projects are exempt). .travis.yml library or zero-dependency project: lockfile not required
• ✓ L3 At least 90% of modules fit 32k tokens and no file exceeds 12k; test/source token ratio at least 0.3; at least 70% of the code is typed. pkg/component/config_test.go test ratio 0.76, 97% typed, modules fit
• ✗ L4 No import cycles, and agent docs (AGENTS.md, CLAUDE.md, llms.txt). no agent docs (AGENTS.md, CLAUDE.md, llms.txt)