docs: restructure documentation, add CLI reference and workflows#4
Merged
Conversation
Decouple framework and CLI release cycles so each component can evolve independently. Framework uses `fw-*` tags, CLI uses `cli-*` tags, with separate GitHub Actions workflows for each. - Reset CLI version to 1.0.0, bump framework manifest to 2.1.0 - Add `get_latest_release_by_prefix()` to filter releases by tag prefix - Add `strip_tag_prefix()` helper for fw-/cli-/v- prefixes - Rename `update` command to `update-framework`, create combined `update` - Add `update-framework` subcommand to CLI router - Show both framework and CLI versions in `status` and `about` - Split release.yml into release-framework.yml and release-cli.yml - Update install scripts to fetch `cli-*` releases Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…rsion fixes Add CLI-REFERENCE.md and WORKFLOWS.md for adopters (EN + ES), update all docs to reflect independent fw-*/cli-* versioning, fix broken cookbook.md link, remove hardcoded v2.0.0 from dist files, and update releases/latest references to point to fw-* releases. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
|
montfort
added a commit
that referenced
this pull request
May 2, 2026
Editorial-only pass on Propuesta/devtrail-design-principles.md to remove internal-language phrases that confuse readers who don't know Sentinel (the project that produced the empirical evidence). All decisions and commitments preserved; only language generalized. Specific changes: - Version metadata now names the editorial pass and dates it. - v0.2 anotaciones intro: glosses Sentinel as "un sistema Go backend" on first mention, drops references to /plan-audit and PLAN-NN that cold readers can't anchor to anything. - Principle #6 anotación (virtud-vs-ceremonia): replaces specific artifact IDs (AILOG-020, AILOG-022, PLAN-05.telemetry.yaml) with abstracted descriptions of the empirical findings. The decisions about what counts as virtud vs ceremonia stay identical. - Principle #9 anotación (bash before framework): drops the script filename and AILOG ref, keeps the ~145-line metric and the three-property justification (zero-build, no deps, in-situ inspection). - Principle #12 anotación (N≥3 spirit): "Sentinel es un solo proyecto..." → "La evidencia empírica disponible proviene de un solo proyecto adoptante..."; specific scores (9.25/9.5) generalized to "scores similares"; supuesto #4 named as "supuesto de aprobaciones condicionales" instead of by number alone. - Meta-meta paragraph: drops Sentinel-specific framing while keeping the auto-evolución insight intact. Prerequisite for D4 of the README repositioning plan: link the design principles from the public README. Cold readers (a developer landing on GitHub, not someone who read all the propuesta docs) need to grasp each principle without first decoding internal artifacts. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
5 tasks
montfort
added a commit
that referenced
this pull request
May 2, 2026
Reframes DevTrail's canonical English surface from "AI Governance Platform" to engineering-discipline-first, with compliance positioned as a side effect. Aligns the README, DEVTRAIL.md, and DOCUMENTATION-POLICY.md with Principle #4 (compliance is a side effect, not the product) and Principle #2 (primary user is the senior engineer orchestrating agents). Spanish and zh-CN translations deferred to a follow-up i18n release. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
montfort
added a commit
that referenced
this pull request
May 9, 2026
… (#122) * fix(cli): align charter subcommand path to .straymark/charters/ The `straymark charter list/audit/close/drift/new` subcommands hardcoded `docs/charters/` as the discovery root, while `straymark init` and `straymark status` already validated `.straymark/charters/` as the canonical structure. Projects on the post-rebrand layout (fw-4.11.0) were silently invisible to the CLI: charters created with `charter new` landed in `docs/charters/` but `straymark status` only looked under `.straymark/`, and reciprocally `charter list/audit/close` could not see charters living under `.straymark/charters/`. This change unifies on `.straymark/charters/` (the canonical post-rebrand location), where declarative `*.md` and telemetry `*.telemetry.yaml` sidecars now share one directory. The drift bash script and its documentation are updated to match. Changes: - New `charter::charters_dir(project_root)` helper as the single source of truth for the Charter discovery path. - `discover_charters` and `commands/charter/new.rs` now route through it; previously they constructed `docs/charters/` directly. - `commands/charter/close.rs` reuses the same helper for telemetry destination — declarative + telemetry are no longer split. - Error messages in `audit/close/drift` now name the path that was searched and hint at `straymark charter list` (per the Issue #119 workaround request). - `dist/.straymark/scripts/check-charter-drift.sh` matches against `.straymark/charters/*` instead of `docs/charters/*`. - All existing tests (`cli/tests/charter_*.rs`, inline tests in `charter.rs`, `tui/index.rs`, `commands/charter/list.rs`, `commands/charter/status.rs`) updated to the new path. Tested: `cargo test --release` (479 passed); smoke test (`charter new` → `charter list` round-trip on `.straymark/charters/`). Closes #119 * docs(framework): surface Charter as top-level concept Address the discoverability gap reported in #113: STRAYMARK.md and QUICK-REFERENCE.md (EN/ES/zh-CN) did not name Charters anywhere, so agents onboarding via canonical entry points built binary mental models (SpecKit = planning, StrayMark = audit-trail) and silently dropped the third layer where Charters live. - STRAYMARK.md §6: add Charter trigger ("multi-session implementation block, >1 day, >5 tasks") to the When-to-Document table. - STRAYMARK.md §9: add Charter row to the Autonomy Limits table. - STRAYMARK.md §10: add charters/ to the documentation map tree. - STRAYMARK.md §11: add Charter rows to the When-to-Load table (template path + how to list existing Charters + bridge doc). - STRAYMARK.md §13: add Charter to the Quick Type Reference, noting the NN-slug.md filename divergence from TYPE-YYYY-...-NNN-*. - STRAYMARK.md §15 (new): dedicated section explaining what a Charter is, when to declare one, the lifecycle (declared → in-progress → closed), and how it relates to AILOG/ADR/SpecKit. - QUICK-REFERENCE.md (×3 langs): add "Bounded Units of Work — Charter" subsection alongside the doc-type tables, charters/ entry in the folder tree, Charter trigger row in When-to-Document, and /straymark-charter-new in the skills table. * docs(directives): add Charter trigger to pre-commit checklist Inject the Charter declaration trigger into the directive templates (CLAUDE.md, GEMINI.md, copilot-instructions.md) that `straymark init` fans out to adopting projects. Now agents reading the local CLAUDE.md / GEMINI.md / .github/copilot-instructions.md see Charter in their pre-commit checklist alongside AILOG / AIDEC / ADR / ETH triggers, instead of having to hunt for it in STRAYMARK.md §15. Trigger wording: "Starting a multi-session implementation block (>1 day, >5 tasks, multi-phase)? → Declare a Charter via `straymark charter new` (see STRAYMARK.md §15)". Closes the second contributing factor of #113 (root cause #2: "CLAUDE.md Pre-commit Checklist has no Charter trigger"). * feat(cli): scan .straymark/charters/ in straymark status Surface Charters in the canonical health view. Until now `straymark status` enumerated only the 12 governance doc types — Charters were structurally invisible to the compliance-observability tool, even when present. That blind spot is the fifth contributing factor of #113 ("/straymark-status excludes Charters from its scan"). The new "Charters" block sits below "Documentation": - When the project has no Charters yet: a single dimmed line pointing at `/straymark-charter-new` and STRAYMARK.md §15. - When Charters exist: a status-keyed table (declared / in-progress / closed / TOTAL), with declared in normal weight, in-progress in yellow, closed in green — matching the colorize_status convention already used by `charter list`. - Unparseable Charter files (Charter-shaped filename, schema mismatch) are surfaced as a warning row so the operator knows to fix them. Counts come from `charter::discover_and_parse(project_root)` — the same source of truth that `straymark charter list` uses, ensuring the two commands cannot disagree about what's in the project. * feat(skills): add /straymark-charter-new + Charter mentions in status/new Add a dedicated /straymark-charter-new skill across the three skill surfaces (Claude Code, Gemini, agnostic) so Charter declaration is discoverable through skill autocomplete and through any "what slash commands exist?" exploration. Previously Charter creation was only reachable via the bare `straymark charter new` CLI invocation, which the issue (#113 root cause #4) flagged as the reason agents miss the concept entirely. The new skill drives the existing CLI — slug derivation, sequential numbering and template substitution stay server-side; the skill's job is to gather title/effort/origin (--from-ailog vs --from-spec vs none), confirm with the operator, then run `straymark charter new` with the right flags. The skill explicitly does NOT flip status, run drift, or run audit — those have their own skills / CLI surfaces and shouldn't be conflated with declaration. Also amend the existing skills: - /straymark-status (×3): scan `.straymark/charters/` after the doc-type prefixes, surface "no Charters yet but the work fits the trigger → recommend /straymark-charter-new" as a gap. - /straymark-new (×3): add Charter as a *redirect* row (not a doc type that `straymark new` can produce) — the skill recognizes "create a Charter" / "declare a Charter" intent and points at /straymark-charter-new instead of trying to handle it inline. Closes the third, fourth, fifth and sixth contributing factors of #113 (no charter-new skill, /straymark-status excludes Charters, audit-* skills' framing). * refactor(framework): wire CLI to charter templates' new subdirectory Templates were moved to `dist/.straymark/templates/charter/` in the preceding "surface Charter as top-level concept" commit so that the charter-* templates are visually distinguishable from auxiliary doc templates (root cause #7 of #113: "charter-template.md and charter-telemetry-template.yaml are listed in `.straymark/templates/` but indistinguishable from auxiliary templates"). This commit wires the CLI and tests to the new layout: - `commands/charter/new.rs` resolves the declarative template through `templates/charter/charter-template.md` (with i18n fallback via `templates/charter/i18n/<lang>/`). - `commands/charter/close.rs` reads the telemetry template from `templates/charter/charter-telemetry-template.yaml`. - `cli/tests/charter_{test,drift,close}.rs` build their fixtures under `templates/charter/` and create the subdir explicitly. `utils::resolve_localized_path` already handles arbitrary base directories, so no change was needed there. * docs(governance): add SPECKIT-CHARTER-BRIDGE.md (EN/ES/zh-CN) Close root cause #8 of #113: "no documented bridge between SpecKit and StrayMark Charters". The Charter frontmatter has had `originating_spec: specs/NNN-feature/spec.md` from day one — the schema slot was the bridge, but nothing told operators or agents *when* a SpecKit feature should yield a Charter, *how granular* it should be (1 per feature? 1 per phase? 1 per User Story?), or *who triggers the creation* (after `/speckit-tasks`? before `/speckit-implement`?). Without that, agents formed the binary mental model the issue flagged — "SpecKit = planning, StrayMark = audit-trail" — and silently dropped the Charter layer. The new doc: - Names the three layers (specification → Charter → AILOG/AIDEC/ADR) and the handoff pattern between them. - Lists four "yes-Charter" conditions (≥5 tasks across sessions, multi-phase, audit-worthy, telemetry-worthy) and three "no-Charter" conditions (single-session, planning-only, ad-hoc maintenance). - Gives four granularity heuristics with the rule "one Charter per shippable cut" — explicitly NOT per User Story, NOT per feature. - Anchors the creation timing to the SpecKit pipeline: /speckit-tasks → declare Charter → /speckit-implement → drift → audit (optional) → close. - Documents the frontmatter linkage in both directions (Charter.originating_spec, AILOG.originating_charter). - Lists five anti-patterns (Charter "to be safe", per-US, missing origin, premature close, audit without auditors). - Names five cases where the pattern doesn't apply (single-session, arch-only, pure refactor, incident response, compliance refresh). Cited in STRAYMARK.md §11 ("SpecKit user — when does a feature yield a Charter?"), STRAYMARK.md §15 ("Charters as bounded units of work"), and the QUICK-REFERENCE Charter subsection. Skill `/straymark-charter-new` also points to it. Translations follow the same patterns established for `docs/i18n/{es,zh-CN}/` — preserve technical terms (Charter, SpecKit, drift, scope), localize narrative.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
v2.0.0across 5 dist files and brokencookbook.mdlink in QUICK-REFERENCE.mdfw-*/cli-*versioning schemereleases/latestreferences to point users tofw-*tagged releasesupdate_framework.rs,status.rs)Test plan
v2.0.0in dist/ — 0 matchesreleases/latestacross repo — 0 matchescookbook.mdacross repo — 0 matches🤖 Generated with Claude Code