straymark charter list/audit/close: hardcoded docs/charters/ path breaks .straymark/charters/ layout

[montfort]

Summary

straymark charter list, straymark charter audit, and (by inference) straymark charter close (CLI v3.11.0) hardcode docs/charters/ as the Charter discovery path. Projects whose Charter files live under .straymark/charters/ — the layout this project (straylight, fw-4.11.0 / cli-3.11.0) carries — are silently invisible to those subcommands, even though the same .straymark/charters/ path is validated by straymark status as part of the canonical structure.

Hit while running /straymark-audit-review CHARTER-02: the Charter file exists, validates against charter.schema.v0.json, is referenced from active workflows, and yet straymark charter audit CHARTER-02 --merge-reports fails with error: Charter CHARTER-02 not found in docs/charters/, and straymark charter list returns No Charters in this project.

Reproduction

From this project's clean working tree:

$ ls .straymark/charters/
CHARTER-01.md  CHARTER-01.telemetry.yaml  CHARTER-02.md

$ straymark charter list
No Charters in this project. Run `straymark charter new` to create one.

$ straymark charter audit CHARTER-02 --merge-reports
error: Charter CHARTER-02 not found in docs/charters/

$ straymark --version
straymark 3.11.0

$ straymark status | sed -n '/Project/,/Structure/p'
Project
┌───────────┬─────────────────────────────────────────┐
│ Path      │ /E/Proyectos/StrangeDaysTech/straylight │
│ Framework │ fw-4.11.0                               │
│ CLI       │ cli-3.11.0                              │
│ Language  │ en                                      │
└───────────┴─────────────────────────────────────────┘

Structure
✓ All 17 items present

straymark status reports the structure as fully OK, indicating the framework treats .straymark/charters/ as canonical, but the charter subcommand uses a different (docs/charters/) discovery root.

Impact

• Blocks the v1 audit-skills flow. /straymark-audit-execute writes reports to .straymark/audits/CHARTER-NN/ correctly (the audits/ subtree the CLI does honor), but /straymark-audit-review cannot then run straymark charter audit CHARTER-NN --merge-reports for schema validation + external_audit: YAML emission. The calibrator agent has to construct the YAML by hand against audit-output.schema.v0.json (frontmatter validation of source reports) and charter-telemetry.schema.v0.json (external_audit array shape). It works, but it bypasses the CLI's validator path and is invisible to telemetry tooling that may expect the CLI as the canonical emitter.
• Blocks straymark charter close for these Charters under the same path mismatch — telemetry can never be persisted by the CLI; only hand-edited.
• Misleading error message (not found in docs/charters/) doesn't suggest the actual problem (path lookup convention mismatch) or any workaround.

Workaround applied

Constructed the external_audit: block manually following the schemas, then wrote it to .straymark/audits/CHARTER-02/external-audit-pending.yaml for the operator to paste during straymark charter close. Documented inline in the review document. Works for one Charter, doesn't scale, doesn't exercise the validator.

Discussion / recommended fix

Two design questions worth resolving in the same patch:

1. What is the canonical Charter location post-rebrand?

   • (a) docs/charters/ — Sentinel's pre-rebrand layout (Charters as docs, telemetry under .devtrail/charters/, see issue Charter flow telemetry from Sentinel CHARTER-02 — 8 frictions (F1-F8) + 3 observations (O1-O3) on fw-4.6.0/cli-3.7.0 #81 references).
   • (b) .straymark/charters/ — what straymark init and straymark status treat as canonical today.
   • (c) Both, with a documented search order (e.g. .straymark/charters/ first, docs/charters/ fallback).

   The framework appears to have picked (b) but the CLI still implements (a). Aligning the two — or formally documenting (c) — is the root fix.

2. Should straymark repair offer a migration path? If the canonical answer is (a), projects already on (b) need straymark repair --migrate-charters (or equivalent) to relocate .straymark/charters/*.{md,telemetry.yaml} → docs/charters/.

A cheap partial fix in the meantime: have charter list/audit/close enumerate the paths searched in the error, e.g.:

error: Charter CHARTER-02 not found
  searched: docs/charters/, .straymark/charters/
  hint: run `straymark charter list` to see discovered Charters

That alone would have saved the round-trip diagnosis here.

Versions

• cli-3.11.0
• fw-4.11.0
• Linux (Fedora 44, kernel 6.19)

References

• Issue Charter flow telemetry from Sentinel CHARTER-02 — 8 frictions (F1-F8) + 3 observations (O1-O3) on fw-4.6.0/cli-3.7.0 #81 — Sentinel's CHARTER-02 telemetry validation (closed) under the pre-rebrand DevTrail layout, where .devtrail/charters/ held telemetry alongside docs/charters/ for source. Useful precedent for the split-layout option (c).
• This project's consolidated audit review (where the workaround is documented inline): .straymark/audits/CHARTER-02/review.md in StrangeDaysTech/straylight.

🤖 Generated with Claude Code

[montfort]

Fix submitted in PR #121 (fix/charter-path-119).

Resolution summary:

• Single canonical Charter directory: .straymark/charters/ (matching straymark init and straymark status). Both declarative *.md and telemetry *.telemetry.yaml sidecars now share that directory.
• New charter::charters_dir(project_root) helper as the single source of truth — eliminates the 5 hardcoded docs/charters/ references across charter.rs, commands/charter/new.rs, audit.rs, close.rs, drift.rs.
• Error messages in audit/close/drift now name the searched path and hint at straymark charter list, exactly as the issue requested:

  error: Charter CHARTER-02 not found in .straymark/charters/.
    hint: run `straymark charter list` to see discovered Charters.
  

• dist/.straymark/scripts/check-charter-drift.sh updated to match .straymark/charters/* instead of docs/charters/*.
• All existing tests (cli/tests/charter_*.rs plus inline tests in charter.rs, tui/index.rs, commands/charter/{list,status}.rs) updated to the new path. 479 passed, 0 failed under cargo test --release.

Re: design question 1 (canonical location) — went with (b) (.straymark/charters/), aligning the CLI to what the framework already validated. Option (c) was rejected: the dual-search pattern would create a project-config-of-the-week situation as adopters chose between roots. One canonical location is simpler.

Re: design question 2 (migration helper) — no straymark repair --migrate-charters flag bundled. CLI is pre-1.0 (cli-3.11.0) so the breaking change is permitted; for projects on the legacy docs/charters/ layout, the migration is one command:

git mv docs/charters .straymark/charters

The improved error message points operators at this when they hit it.

Re: workaround invalidation — once #121 lands and a project upgrades, straymark charter close --merge-reports accepts the external_audit: block via the validator path that the manual workaround had to bypass. The straylight CHARTER-02 review can then re-emit telemetry through the CLI rather than the hand-edited yaml.

Will close once PR #121 merges to main.

[montfort]

Update — bug remains reproducible in cli-3.12.0 / fw-4.12.0 (tested today on the same project).

Same reproduction as the original report:

$ straymark --version
straymark 3.12.0

$ straymark status | sed -n '/Project/,/Structure/p' | head -8
Project
┌───────────┬─────────────────────────────────────────┐
│ Path      │ /E/Proyectos/StrangeDaysTech/straylight │
│ Framework │ fw-4.12.0                               │
│ CLI       │ cli-3.12.0                              │
│ Language  │ en                                      │
└───────────┴─────────────────────────────────────────┘

$ ls .straymark/charters/
CHARTER-01.md  CHARTER-01.telemetry.yaml  CHARTER-02.md  CHARTER-02.telemetry.yaml

$ straymark charter list
No Charters in this project. Run `straymark charter new` to create one.

charter list/audit/close still hardcode docs/charters/ discovery despite straymark status validating .straymark/charters/ as part of the canonical structure. The 3.11→3.12 bump didn't touch this code path.

For the CHARTER-02 closure work that originally hit this (now committed in this project at 45f6e9d), the manual-YAML workaround held: the external_audit: block was constructed from the validated frontmatter of each report-*.md against audit-output.schema.v0.json and then embedded directly into CHARTER-02.telemetry.yaml matching the charter-telemetry.schema.v0.json shape. Works, but bypasses the CLI's validator path, which is exactly what the upstream fix would unblock.

No new diagnostic information beyond the original report — flagging continued reproducibility so this doesn't get closed as "stale" before the path-discovery question is resolved.