CLI improvements from img-forge hardening: surface schema parsing, doctor module detection, stamp-policies ergonomics

[stackbilt-admin]

Summary

While hardening downstream emission contracts in img-forge, we used Charter CLI (v0.15.0) and found several improvement opportunities that affect real repo workflows.

Repo where observed: Stackbilt-dev/img-forge
Date observed: 2026-05-20

Findings

1) surface --format json schema parser mis-parses SQL columns/types

Observed output from npx charter surface --format json included malformed schema fields, for example:

• jobs table contained {"name":"ephemeral","type":"ERROR_MESSAGE"}
• audit_logs included {"name":"quota_reset","type":"RESOURCE_TYPE"}
• created_at defaults were truncated ("(datetime('now')")

This appears to be tokenization/parsing drift in SQL column extraction, which weakens downstream contract reliability for agent consumers.

2) doctor false-negative/lag on newly-created on-demand module until adf sync --write

Sequence:

1. npx charter adf create frontend --triggers "React,CSS,UI" reported success and file existed.
2. Immediate npx charter doctor --ci --format json still warned:
   • adf on-demand modules: Missing or unparseable: frontend.adf (missing)
3. Running npx charter adf sync --write then re-running doctor resolved it.

Expected: doctor should recognize freshly created modules without requiring a separate sync step (or at minimum produce a clearer stale-state hint).

3) stamp-policies --dry-run hard-fails on unresolved HEAD SHA without actionable fallback

Running npx charter stamp-policies --dry-run --format json failed with:

• Could not resolve Stackbilt-dev/stackbilt_llc HEAD SHA. Pass --policy-repo-ref <sha> to override.

After manually resolving a commit SHA and passing --policy-repo-ref, command succeeded. Suggestion: optionally auto-fallback to a pinned known-safe ref or emit a machine-readable error payload with a one-command recovery hint.

Suggested fixes

• Harden SQL schema extraction in surface:
  • Add tests covering CHECK (...), defaults like datetime('now'), and multi-token constraints.
  • Ensure column name/type/default are preserved exactly.
• Make doctor consume current filesystem/module state directly (or invalidate manifest cache) after adf create.
• Improve stamp-policies failure ergonomics:
  • Return structured JSON error in --format json mode.
  • Include explicit recovery command template with --policy-repo-ref.

Repro commands

npx charter surface --format json
npx charter adf create frontend --triggers "React,CSS,UI"
npx charter doctor --ci --format json
npx charter adf sync --write
npx charter stamp-policies --dry-run --format json