From 12c65c7db5676619850984903ebfa41ce2cc5f20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jose=20Villase=C3=B1or=20Montfort?= <195970+montfort@users.noreply.github.com> Date: Sun, 10 May 2026 12:57:29 -0600 Subject: [PATCH 1/3] docs: reorganize Propuesta/ into contributors docs + historical proposals + private notes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `Propuesta/` directory mixed canonical docs, implemented proposals, internal notes and competitive analysis. This commit splits them along purpose lines, so a contributor opening the repo finds public docs immediately and isn't exposed to material that should not be public. Public, atemporal — moved to `docs/contributors/` with full i18n: - `DESIGN-PRINCIPLES.md` (12 hierarchical principles, with v0.2 empirical annotations from Sentinel validation cycles) — EN translated, ES preserved as the original, zh-CN translated. - `WHAT-IS-A-CHARTER.md` (conceptual scope of the Charter artifact and its boundary with GitHub SpecKit's `plan.md`) — same i18n treatment. - New `docs/contributors/README.md` (×3 langs) is a categorized index with a one-line summary per document. Public, archival — moved to `docs/decisions/proposals/` with date prefix (no translation, these are historical artifacts): - `2026-04-30-thesis-validation.md` - `2026-04-30-charter-telemetry.md` - `2026-05-03-cli-roadmap.md` (Phases 1-3 shipped in cli-3.x) - `2026-05-03-audit-skills-design.md` (implemented in fw-4.8.0) - `2026-05-03-audit-skills-rollout.md` - `2026-05-04-audit-cli-flow.md` (implemented in cli-3.10+) Moved out of the repo (to ~/Documents/StrangeDaysTech/internal-notes/), not gitignored — internal-only material should not be in the public working tree at all (leak-by-mistake risk): - straymark-studio-vision.md (speculative product vision) - straymark-mapa-cognitivo.md (internal brainstorm + qualitative diagnosis) - straymark-telemetria-etapa2-sentinel.md (operational deliverable to one specific adopter) - sentinel-skill-prompt-audit.md, sentinel-skill-prompt-audit-review.md (Sentinel's pre-StrayMark methodology) - straymark-cloud-proposal.md (competitive analysis, monetization hypotheses — explicitly sensitive) Also fixes the broken link in all three READMEs line 90 — pointed at `Propuesta/straymark-design-principles.md` which was untracked, hence 404 on GitHub. Now points at `docs/contributors/DESIGN-PRINCIPLES.md` and its localized siblings. Finalizes the dangling deletes of the legacy `Propuesta/devtrail-*` files left over from the rebrand. `Propuesta/` directory is now removed. --- README.md | 2 +- docs/contributors/DESIGN-PRINCIPLES.md | 121 ++++ docs/contributors/README.md | 41 ++ docs/contributors/WHAT-IS-A-CHARTER.md | 134 ++++ .../proposals/2026-04-30-charter-telemetry.md | 211 ++++++ .../proposals/2026-04-30-thesis-validation.md | 44 +- .../2026-05-03-audit-skills-design.md | 358 +++++++++++ .../2026-05-03-audit-skills-rollout.md | 345 ++++++++++ .../proposals/2026-05-03-cli-roadmap.md | 124 ++-- .../proposals/2026-05-04-audit-cli-flow.md | 603 ++++++++++++++++++ docs/i18n/es/README.md | 2 +- .../i18n/es/contributors/DESIGN-PRINCIPLES.md | 29 +- docs/i18n/es/contributors/README.md | 41 ++ .../i18n/es/contributors/WHAT-IS-A-CHARTER.md | 53 +- docs/i18n/zh-CN/README.md | 2 +- .../zh-CN/contributors/DESIGN-PRINCIPLES.md | 121 ++++ docs/i18n/zh-CN/contributors/README.md | 41 ++ .../zh-CN/contributors/WHAT-IS-A-CHARTER.md | 134 ++++ 18 files changed, 2279 insertions(+), 127 deletions(-) create mode 100644 docs/contributors/DESIGN-PRINCIPLES.md create mode 100644 docs/contributors/README.md create mode 100644 docs/contributors/WHAT-IS-A-CHARTER.md create mode 100644 docs/decisions/proposals/2026-04-30-charter-telemetry.md rename Propuesta/devtrail-thesis-validation.md => docs/decisions/proposals/2026-04-30-thesis-validation.md (83%) create mode 100644 docs/decisions/proposals/2026-05-03-audit-skills-design.md create mode 100644 docs/decisions/proposals/2026-05-03-audit-skills-rollout.md rename Propuesta/devtrail-cli-roadmap.md => docs/decisions/proposals/2026-05-03-cli-roadmap.md (52%) create mode 100644 docs/decisions/proposals/2026-05-04-audit-cli-flow.md rename Propuesta/devtrail-design-principles.md => docs/i18n/es/contributors/DESIGN-PRINCIPLES.md (77%) create mode 100644 docs/i18n/es/contributors/README.md rename Propuesta/que-es-un-charter.md => docs/i18n/es/contributors/WHAT-IS-A-CHARTER.md (63%) create mode 100644 docs/i18n/zh-CN/contributors/DESIGN-PRINCIPLES.md create mode 100644 docs/i18n/zh-CN/contributors/README.md create mode 100644 docs/i18n/zh-CN/contributors/WHAT-IS-A-CHARTER.md diff --git a/README.md b/README.md index 09c3dfa..2b2d7d2 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,7 @@ StrayMark's product decisions are anchored in twelve explicit principles. They a 11. **The community takes care of the tool, not the other way around.** Contributions and feedback are taken seriously without becoming a democracy. 12. **The product's velocity is the velocity of learning.** No premature crystallization; schemas marked `v0` until validated against a second domain. -The full document, with empirical annotations from validation cycles, lives in [`Propuesta/straymark-design-principles.md`](https://github.com/StrangeDaysTech/straymark/blob/main/Propuesta/straymark-design-principles.md). +The full document, with empirical annotations from validation cycles, lives in [`docs/contributors/DESIGN-PRINCIPLES.md`](https://github.com/StrangeDaysTech/straymark/blob/main/docs/contributors/DESIGN-PRINCIPLES.md). --- diff --git a/docs/contributors/DESIGN-PRINCIPLES.md b/docs/contributors/DESIGN-PRINCIPLES.md new file mode 100644 index 0000000..44c532e --- /dev/null +++ b/docs/contributors/DESIGN-PRINCIPLES.md @@ -0,0 +1,121 @@ +# StrayMark — Design Principles + +**Version:** 0.2.2 (empirical annotations + editorial pass for public readability: internal references to Sentinel artifacts are generalized; Plan → Charter rename in going-forward vocabulary) +**Date:** 2026-05-02 +**Author:** Jose Villaseñor Montfort — StrangeDaysTech +**Purpose:** Articulate the product philosophy in compact form, to serve as a reference against design decisions and as a criterion for saying no to features that don't fit. +**Languages:** English | [Español](../i18n/es/contributors/DESIGN-PRINCIPLES.md) | [简体中文](../i18n/zh-CN/contributors/DESIGN-PRINCIPLES.md) + +--- + +## Why this document exists + +Software products drift, over time, toward whatever incentive pushes them hardest. If the pressure is revenue, they drift toward features that sell. If the pressure is adoption, they drift toward features that go viral. If the pressure is competition, they drift toward parity with the most visible competitor. Each of those drifts is individually rational and collectively destructive: the product loses its original shape and becomes another averaged-out point in the market. + +This document exists so StrayMark has an explicit anchor. Future decisions must be checkable against these principles. A feature that violates a principle may still be a good idea, but it requires a deliberate conversation about *which* principle is being relaxed and *why*. The existence of the document doesn't guarantee discipline; the conscious question it forces, does. + +The principles are ranked by hierarchy: when two conflict, the earlier one wins. + +**Version 0.2 — empirical annotations.** This version incorporates lessons from the first experiment that stresses the principles against evidence: six execution cycles on a real adopter project (Sentinel — a Go backend system), with three iterations of the Charter format (v1 → v2 → v3) and two dual external audits per cycle. The annotations per principle concentrate on the three the experiment exercised directly (#6, #9, #12); the hierarchy and the wording of the twelve principles do not change. The detailed evidence lives in `straymark-thesis-validation.md` (preserved in `docs/decisions/proposals/` for historical reference). + +--- + +## 1. The tool serves the craft, not the product + +StrayMark exists so that the engineer working with AI agents produces work they're proud of. That is the final metric. Any feature that improves adoption, retention, or revenue metrics at the cost of degrading the quality of the user's work is a feature that violates the foundational principle. + +In practice, this means decisions are made with the question *"does this help the engineer do better engineering?"*, not with the question *"does this grow the product?"*. The two questions sometimes converge and sometimes don't. When they diverge, the first wins. + +## 2. The primary user is the senior engineer orchestrating agents + +Not the VP Engineering. Not the CISO. Not the compliance officer. The primary user is the engineer with strong technical judgment who uses AI agents to work on projects they couldn't realistically tackle alone, and who needs externalized cognitive discipline so the agent doesn't introduce systemic chaos. + +Features are designed for that person. Flows are optimized for that person. Documentation is written for that person. When other people (compliance officers, managers, auditors) eventually use the product, they do so on a foundation that respects the engineer first. Inverting this hierarchy is the most common cause of developer-tooling products turning bad. + +## 3. Strict open source, no asterisks in the core + +The framework, the CLI, and the TUI are and always will be open-source under a permissive license. No capped features in the OSS to push toward paid tiers. No mandatory telemetry. No account requirement for full use. No "community edition" inferior in core capabilities to an "enterprise edition". + +When a commercial layer eventually exists (Cloud, hosting, services), it must offer genuinely additive value, not rescue functionality stripped from the OSS to manufacture demand. The difference between honest open-core and bait-and-switch open-core is honesty about what is added value vs. what is the tool itself. + +## 4. Regulatory compliance is a side effect, not the product + +ISO/IEC 42001, EU AI Act, NIST AI RMF, GDPR are useful frameworks that give structure to documentation. StrayMark supports them as an optional layer because they are valuable for users who need them. But the product is not "a compliance tool". The product is an engineering tool that produces, as a side effect, evidence compatible with those frameworks. + +This distinction matters because the compliance buyer and the engineer using the tool have different needs. When the product is positioned as compliance, design decisions skew toward the compliance buyer and degrade the engineer's flow. Keeping compliance as a side effect protects the quality of the primary flow. + +## 5. Schema-driven before feature-driven + +The product's central entities (Stage Closure Bundle, Charter, Document) are defined first as formal schemas with strict versioning. Features are built against those schemas. This has three structural benefits: it lets multiple implementations coexist without coordinating, it makes evolution controlled and reversible, and it forces thinking about the contract before the implementation. + +The practical consequences are that breaking schema changes are rare and deliberate, that schemas are first-class product documentation, and that features that require violating a schema must first propose the schema's evolution. + +## 6. Cognitive discipline over raw productivity + +StrayMark does not compete with tools that promise *"write code 10× faster with AI"*. It competes, if it competes with anything, against the chaos that fast AI code generates in serious projects. The metric that matters is not raw agent speed but sustained quality of the system produced. + +This means features that add justified friction (validations, gates, documentation requirements, pre-work before planning) are acceptable and sometimes desirable. Features that promise to remove friction at the cost of the agent's reasoning quality are suspect by default. + +**v0.2 annotation — virtue vs. ceremony distinction.** Empirical evidence revealed that not all friction in the flow has the same character. Friction is *virtuous* when it externalizes public signal verifiable by third parties: formally naming risks that emerge during execution makes heterogeneous external auditors capture them; a drift-check at work closure detects declared-vs-modified file mismatches with zero false positives in empirical validation; dual auditing with two heterogeneous models calibrates cross-model and catches gaps a single auditor misses. Friction is *attackable ceremony* when it only generates manual triage or prescribes without allowing context adaptation: a rigid template that clashes with the destination module's convention, or a drift-check alerting on divergences already documented elsewhere, are the two observed cases. The first is preserved; the second is a format bug, not a virtue of the principle. Detailed evidence and actionable criteria live in `straymark-thesis-validation.md` §5 (preserved in `docs/decisions/proposals/`). + +## 7. Local-first, Cloud as amplifier + +The CLI works completely, without network, in the local repo. That is the first experience and the foundation everything builds on. Cloud exists to amplify value (cross-repo aggregation, signed evidence, semantic historical search, team collaboration) but never to replace the CLI or turn it into a thin client. + +A user who never connects to Cloud must still get most of the product's value. This protects the tool against Cloud failure modes, against business-model changes, and against the classic drift of products that start local and end up requiring mandatory connection. + +## 8. Project memory lives in the repo, not in an external database + +AILOGs, ADRs, AIDECs, Charters, and bundles live as versioned files alongside the code. The reason is structural: project memory must outlive the product that generated it. If StrayMark disappears tomorrow, the `.straymark/` files remain readable, parseable, and useful because they are structured markdown and JSON conforming to public schemas. + +This decision gives up some capabilities that would be easier with a centralized backend (for example, instant full-text search without sync), but gains long-term reliability and user control over their own data. The asymmetry is deliberate and permanent. + +## 9. Simplicity over capability + +When two designs meet the same goal, the simpler one wins. When a feature is genuinely useful but requires significant complexity, it's better to wait until the usage pattern is validated in at least three real projects before crystallizing it into the product. + +This applies to both the product and the product's language. Command names, document types, and framework concepts are chosen to be immediately understandable, not to sound technically sophisticated. If a concept requires lengthy explanation for a new user, it's probably poorly designed. + +**v0.2 annotation — bash before framework when bash suffices.** Empirical evidence demonstrated that a ~145-line bash script (awk + grep + git) covers the "drift between declared and modified files" case with zero false positives across two tests. The conscious decision not to implement it initially in the CLI's language (Rust) is justified thus: bash is zero-build, no additional dependencies, inspectable in place; maintenance cost is low. When porting to the CLI in phase 2 of the roadmap (`straymark-cli-roadmap.md`, preserved in `docs/decisions/proposals/`), preserve the bash simplicity where possible — invoke the shell from Rust or reimplement carefully without inflating the logic. Complexity crystallizes only when the usage pattern demands it, not by default. + +## 10. Honesty about what the tool does not do + +StrayMark does not evaluate models. It is not an LLM gateway. It does not replace the engineer's judgment. It does not prevent all hallucinations. It does not automatically certify regulatory compliance. The product pages, documentation, and public communication are explicit about these limits. + +The reason is practical: users who adopt the tool with realistic expectations stick with it. Users who adopt it believing it does things it doesn't abandon it frustrated. Early honesty about the limits is a better marketing investment than broad promises. + +## 11. The community takes care of the tool, not the other way around + +StrayMark users are typically engineers who know more than the product team about their own use cases. Contributions, issues, and feedback are treated with professional respect, and roadmap decisions are made incorporating that view. Not democratically (the product needs a coherent vision), but as serious input. + +This does not mean doing everything the community asks. It means explaining when "no" is said and why, keeping the conversation visible and public, and accepting that the product will be better off from the intelligent pressure of those who use it seriously than from the team's isolated decisions. + +## 12. The product's velocity is the velocity of learning + +StrayMark must not advance faster than what we learn about how it is actually used. Crystallizing features prematurely, before having real usage data in at least three different projects, generates high maintenance costs over features that may be wrong. The patience to wait for evidence is discipline, not inaction. + +This translates into an explicit preference for: prototypes before features, observation before crystallization, stable schemas over changing features, and incremental evolution over large rewrites. + +**v0.2 annotation — the spirit of N≥3 facing limited initial evidence.** The empirical evidence available at the time of writing this version comes from a single adopter project, in a single domain (Go backend), with a single author. Applied literally, the principle would block any crystallization from that evidence. Applied in spirit — rigorous observation before crystallization, incremental evolution with real data — the available evidence covers three axes of structural diversity: (a) variable scale of the units of work (XS, S, M across five cycles), (b) format iteration under empirical pressure (v1 → v2 → v3, each derived from the previous cycle), (c) cross-model auditor calibration (two heterogeneous models converging to similar scores in the most stressed cycle). These six cycles × three formats × three scales are evidence equivalent to the N≥3 the principle aims to protect. + +What remains undiversified is the domain. To preserve the principle in its operational form: any schema that crystallizes from that evidence is published as `v0.json` with an *experimental* mark. The transition to stable `v1.0` requires validation with a second project in another domain (frontend, ML pipeline, infra-as-code). Any feature that depends on an assumption without evidence — like the conditional-approval assumption, which requires multi-actor flow that the available evidence did not exercise — is explicitly blocked until a project that does exercise it appears. See `straymark-thesis-validation.md` §6 and §8 (preserved in `docs/decisions/proposals/`) for the argument's development and the list of specific gaps per assumption. + +**Meta-meta pattern detected — format self-evolution.** Empirical evidence revealed that the format improves itself: each Charter (Plan in historical terminology) executed generates data that refines the next format. This suggests extending the principle in future versions: the tool evolves with itself; each use is input for the next version. For now this is documented as observation, not as an additional principle, until a second project confirms the pattern. + +--- + +## How to use this document + +When a non-trivial design decision arises, it is worth contrasting it explicitly against the twelve principles and recording the result. Three useful patterns: + +**Decisions that satisfy all principles**: proceed normally. + +**Decisions that conflict with one principle**: explicitly document which principle is being relaxed, why, and what evidence would lead to reverting the decision. This record should live in an AIDEC or ADR. + +**Decisions that violate foundational principles (1, 2, 3, 4)**: are not made without first reviewing whether the principle is still correct. If it is, the decision is discarded. If not, the principle is updated *before* making the decision, not after. + +The principles are formally reviewed every six months with the accumulated evidence. Changes between formal reviews are possible but must be deliberate and documented. + +--- + +*This document is a guardrail, not a manual. Its usefulness is measured in how many times it makes us pause before making a decision we would later have regretted.* diff --git a/docs/contributors/README.md b/docs/contributors/README.md new file mode 100644 index 0000000..51c5af2 --- /dev/null +++ b/docs/contributors/README.md @@ -0,0 +1,41 @@ +# Contributors documentation + +Resources for people contributing to StrayMark — whether reading the code, writing translations, proposing changes, or trying to understand the *why* behind the framework's shape. + +**Languages:** English | [Español](../i18n/es/contributors/README.md) | [简体中文](../i18n/zh-CN/contributors/README.md) + +--- + +## Concepts + +The atemporal material — read these to understand *what* StrayMark is and *why* it has the shape it has, before opening a PR that touches the framework's surface. + +| Document | What it covers | +|---|---| +| [`DESIGN-PRINCIPLES.md`](DESIGN-PRINCIPLES.md) | The twelve hierarchical principles that govern product decisions. Includes v0.2 empirical annotations from validation cycles on principles #6 (cognitive discipline), #9 (simplicity), and #12 (velocity = velocity of learning). | +| [`WHAT-IS-A-CHARTER.md`](WHAT-IS-A-CHARTER.md) | Conceptual scope of the Charter artifact: an ex-ante declaration of a unit of work with a verification contract and an audit anchor. Maps the boundary between what GitHub SpecKit's `plan.md` covers and what a StrayMark Charter covers — they are not the same thing. | + +## Workflow guides + +| Document | What it covers | +|---|---| +| [`TRANSLATION-GUIDE.md`](TRANSLATION-GUIDE.md) | Rules and conventions for translating StrayMark documentation into additional languages. Read before submitting a PR that adds or modifies an `i18n/` file. | + +## Historical proposals (archived) + +Proposals and roadmaps from the project's pre-CLI evolution, preserved for context — they explain how the current shape emerged. They are **not** maintained going forward; the canonical source for current behavior is the code, the schemas under `dist/.straymark/schemas/`, and the CHANGELOG. Browse them at [`docs/decisions/proposals/`](../decisions/proposals/): + +| File | Snapshot date | What it captured | +|---|---|---| +| `2026-04-30-thesis-validation.md` | 2026-04-30 | Empirical validation of the product thesis against six Sentinel cycles (Go backend) — the evidence body that motivated the v0.2 annotations of `DESIGN-PRINCIPLES.md`. | +| `2026-04-30-charter-telemetry.md` | 2026-04-30 | Telemetry instrumentation schema for observing Charter execution in real projects. The normative version now lives in `dist/.straymark/schemas/charter-telemetry.schema.v0.json`. | +| `2026-05-03-cli-roadmap.md` | 2026-05-03 | Three-phase implementation roadmap for the Rust CLI, with closure criteria. Phases 1–3 are now shipped in `cli-3.x`. | +| `2026-05-03-audit-skills-design.md` | 2026-05-03 | Design of the `/straymark-audit-prompt` and `/straymark-audit-review` skills as human-in-the-loop checkpoints. Implemented in `fw-4.8.0`. | +| `2026-05-03-audit-skills-rollout.md` | 2026-05-03 | Operational rollout plan for the audit skills (gating criteria, telemetry, phased shipping). | +| `2026-05-04-audit-cli-flow.md` | 2026-05-04 | Redesign of the external-audit flow after the first empirical encounter with a multi-commit L Charter (Sentinel CHARTER-07). Implemented in `cli-3.10+`. | + +Decision records (ADRs) for the live codebase live at [`docs/decisions/`](../decisions/) one level up. + +--- + +*See also: [`../adopters/`](../adopters/) for documentation aimed at teams adopting StrayMark in their own projects, including [`ADOPTION-GUIDE.md`](../adopters/ADOPTION-GUIDE.md), [`CLI-REFERENCE.md`](../adopters/CLI-REFERENCE.md), and [`WORKFLOWS.md`](../adopters/WORKFLOWS.md).* diff --git a/docs/contributors/WHAT-IS-A-CHARTER.md b/docs/contributors/WHAT-IS-A-CHARTER.md new file mode 100644 index 0000000..6b1f551 --- /dev/null +++ b/docs/contributors/WHAT-IS-A-CHARTER.md @@ -0,0 +1,134 @@ +# What is a "Charter" in StrayMark (and where it fits relative to GitHub SpecKit) + +**Version:** 0.2 (Plan → Charter rename) +**Date:** 2026-04-30 +**Author:** Jose Villaseñor Montfort — StrangeDaysTech +**Purpose:** Pin the conceptual scope of the **Charter** artifact as it emerges from the Sentinel experiment (where it was called *Plan*), and explain how it coexists with design and development flows already using SpecKit (spec → plan → tasks). +**Languages:** English | [Español](../i18n/es/contributors/WHAT-IS-A-CHARTER.md) | [简体中文](../i18n/zh-CN/contributors/WHAT-IS-A-CHARTER.md) +**Related documents:** `straymark-cli-roadmap.md` (§3 Phase 1, §6 Sentinel→CLI mapping), `straymark-thesis-validation.md`, `straymark-charter-telemetry.md` — all preserved in `docs/decisions/proposals/` for historical reference. + +--- + +## 1. What is a Charter in StrayMark + +**An ex-ante declaration of a unit of work, large enough to deserve a verifiable contract and an ex-post audit.** + +The Charter has three simultaneous faces: + +1. **Scope contract** (Context + Scope in/out + Files to modify + Risks): what will be touched and, deliberately, what will *not*. The `Out of scope` section exists specifically so external auditors don't classify it as a gap. +2. **Verification contract** (Local checks + Production smoke): literal executable commands, separated by *when they apply*. The Local/Prod split is not stylistic — it emerges from the fact that in 3/3 cycles external auditors classified prod-only failures as `real_debt`. +3. **Audit anchor** (frontmatter + Charter closure + drift check): the Charter is the subject on which `straymark charter drift` and `straymark charter audit` operate. Without a Charter there is nothing to audit. + +### 1.1 Not just technical debt + +Of the closed Plans from Sentinel (which are the empirical evidence for the Charter pattern), only one (`03-contract-bumps`) smells like debt. The rest are features (`02-admin-endpoint`, `05-per-service-anomaly-thresholds`), governance work (`01-deploy-governance`), or operational work (`06-baseline-recompute-job`). The README of `sentinel/docs/plans/` says it literally: *"Roadmap of work identified during the closing of the post-MVP backlog"* — backlog, not debt-log. + +### 1.2 When a Charter is warranted vs. just an AILOG + +Inferred from the corpus, not formally written: + +- **AILOG only**: a change that fits in a single session, without pre-declaring files, with low structural risk (typo, point fix, local refactor). +- **Charter + AILOG**: work that touches multiple files, has enumerable ex-ante risks, requires verification with executable commands, and benefits from external post-merge audit. Effort XS–L (minutes to days). +- **ADR + one or more Charters**: deep architectural decision, where each Charter executes a portion of the ADR. + +### 1.3 Atomic Charter closure (format v4) + +From fw-4.4.2 onward, the `charter-template.md` adopts **format v4**: when the pre-commit drift check (Tasks #7) reports drift between `## Files to modify` and the files actually modified, the implementer must update the Charter atomically — in the same commit/PR as the implementation — adding a `## Closing notes` block that documents what changed, why, and references the corresponding AILOG. **It is not deferred to a post-merge housekeeping PR.** + +The pattern emerged empirically from Sentinel's PLAN-07 (closed 2026-05-02), where a legitimate omission drift (a live test turned out to be agnostic to the change, so a file declared in §Files to modify was not touched) was documented late via a separate housekeeping PR, leaving the Plan-doc stale for days. Sentinel's AIDEC-2026-05-02-001 formalized the gap and proposed format v4; this document reflects the upstream evolution. PLAN-05 (`docs/plans/05-per-service-anomaly-thresholds.md`) and PLAN-07 itself are the canonical examples of the `## Closing notes` pattern applied retrospectively — both in Sentinel. + +--- + +## 2. Why it's called "Charter" and not "Plan" + +StrayMark originally called this artifact **Plan** during the Sentinel experiment (April 2026). The term was renamed to **Charter** before the CLI implementation for a pragmatic reason: GitHub SpecKit already uses the word "plan" (`/speckit.plan`, `plan.md`) for a different artifact, and the nominal collision generated friction in adopter docs that combine both flows. + +Sentinel's historical records (Plans 01–06, `sentinel/docs/plans/`, `sentinel/scripts/check-plan-drift.sh`, AILOGs and YAML telemetries `PLAN-NN.telemetry.yaml`) preserve the original name — they are empirical evidence of a specific moment in time, and rewriting history would falsify the record. References to those files in this document deliberately keep "Plan". + +The concept SpecKit calls "plan" and the one StrayMark calls "Charter" are distinct artifacts: + +| | **SpecKit `plan.md`** | **StrayMark Charter** | +|---|---|---| +| Granularity | Complete feature (weeks, several stories) | Bounded unit (hours to days, one branch) | +| Dominant content | Stack, dependencies, project structure, constitution gates | Concrete files to touch, verification commands, R risks | +| Sub-artifacts | Generates `research.md`, `data-model.md`, `quickstart.md`, `contracts/` | Generates (when executed) an AILOG | +| Validation | Constitution Check (ex-ante gate) | Drift-check + external audit (ex-post gates) | +| Optimization | *Upfront clarity* | *Ex-post traceability* | + +What SpecKit calls "plan" looks more like an **ADR + architectural skeleton**. What StrayMark calls "Charter" looks more like a **task-card with contractual verification and audit anchor**. + +--- + +## 3. The SpecKit flow, mapped piece by piece + +SpecKit is linear and top-down: `/speckit.specify` → `/speckit.plan` → `/speckit.tasks` → implement. + +| SpecKit | What it solves | Closest equivalent in StrayMark | +|---|---|---| +| `spec.md` (US, FRs, SCs) | *What* to build, tech-agnostic | `01-requirements/REQ-*.md` | +| `plan.md` (stack, structure) | *How* to architect it | `02-design/ADR-*.md` | +| `tasks.md` (T001..TNNN) | *In what order* to execute it | `## Tasks` section inside a StrayMark Charter | +| (does not exist) | Execution log | **AILOG** | +| (does not exist) | Declared vs. executed drift | **`straymark charter drift`** | +| (does not exist) | Multi-model ex-post audit | **`straymark charter audit`** | + +The last three rows are StrayMark's specific contribution. SpecKit ends when `tasks.md` is produced; what happens after doesn't matter to the framework — if implementation deviates from the plan, there is no mechanism to detect it. StrayMark enters precisely there. + +--- + +## 4. Three modes in which a StrayMark Charter can coexist with SpecKit + +### Mode A — Greenfield with SpecKit as driver + +``` +spec.md → plan.md → tasks.md → ┐ + ├→ Charter-NN (covers US1 + verification + risks) + ├→ Charter-NN+1 (covers US2 + verification + risks) + └→ Charter-NN+2 (covers US3 + verification + risks) + ↓ + AILOG per Charter + ↓ + drift-check + audit +``` + +Each StrayMark Charter takes a subset of tasks (typically a user story or a phase) and adds the three layers SpecKit doesn't provide: executable verification, file declaration to measure drift against, and AILOG/audit hookup. + +### Mode B — Maintenance / post-MVP (Sentinel's actual case) + +No SpecKit running. Sentinel's Plans 01–06 are born from AILOGs and post-MVP backlog, not from specs. The Charter's `Origen:` field points to an AILOG, not to a `specs/###-feature/`. Here the StrayMark Charter is freestanding. + +### Mode C — Hybrid (probably the most realistic) + +- Major features → full SpecKit flow + StrayMark Charters when executing tasks. +- Bug fixes, governance, debt, contract changes, small features → StrayMark Charter only. + +This is consistent with what Sentinel already shows: of the closed Plans, none had upstream SpecKit because the MVP was already spec'd and closed. What remained was evolutionary work, where the Spec→Plan→Tasks cycle is disproportionate. + +--- + +## 5. The underlying conceptual difference + +**SpecKit answers the question:** *"How do I decompose a product idea into executable work?"* — optimizes for upfront clarity and US parallelization. + +**StrayMark Charter answers the question:** *"How do I make a unit of work verifiable, auditable, and detectable when it deviates from what was declared?"* — optimizes for ex-post evidence. + +That's why they don't compete: they live in different moments of the cycle. SpecKit ends at `tasks.md`; StrayMark Charter starts there (when applied) or stands alone (when there is no prior spec). The Sentinel thesis is not "this replaces SpecKit" — it is "this covers the post-tasks phase that SpecKit doesn't, and covers it with a three-layer pattern (declaration + drift + heterogeneous audit) that has empirical evidence of catching gaps the implementer didn't document". + +--- + +## 6. Note on the Studio vision: "Stage" is not a synonym for Charter + +`straymark-studio-vision.md` (an internal-only document) introduces an additional term, **Stage**, which should not be confused with Charter. They are not synonyms: they live at different levels of the cycle. + +- **Stage** = a stage of work that traverses the six cognitive phases of the Studio (Spec → Implementation → Audit → Remediation → Governance → Closure & Deliver) and closes with a signed and hash-chained Closure Bundle. Commands proposed in the vision: `straymark stage open/close/status` (not implemented; correspond to Milestone 2 of the evolution toward Studio). +- **Charter** = bounded unit with verification + drift + audit anchor — the artifact this document defines. Charters live *inside* a Stage; a Stage typically contains one or more Charters plus their associated tasks. + +The implicit taxonomy of the vision is three-level: **Stage > Charter > Task**. The current CLI roadmap (`straymark-cli-roadmap.md` in `docs/decisions/proposals/`, Phases 1–3) operates entirely at the Charter level (what Sentinel called "Plan"), which is the level where empirical evidence from Sentinel exists. Stage would enter the CLI later as an additional layer, not as a rename of Charter. + +## 7. Implication for the StrayMark CLI roadmap + +It is worth reflecting in how the `straymark charter new` command is documented when Phase 1 lands (`straymark-cli-roadmap.md` §3.2 in `docs/decisions/proposals/`). Today the planned flag `--from-ailog ID` covers Mode B. Probably a `--from-spec specs/###-feature/` flag should also exist for Mode A — pre-populating `Origen:` pointing at SpecKit's `spec.md`, and optionally inheriting relevant US into the Context section. That is an exercise for Phase 1, not to resolve today, but worth noting in this document as an open decision for when the subcommand is designed. + +--- + +*This document captures the conceptual scope of the Charter artifact (originally called "Plan" in the Sentinel experiment) as understood at the end of April 2026. The definition will continue to evolve as adopters outside Sentinel exercise the pattern in other domains — version 0.3 will be written after observing at least one adopter project complete a Charter with `straymark charter` (Phase 1 exit criterion).* diff --git a/docs/decisions/proposals/2026-04-30-charter-telemetry.md b/docs/decisions/proposals/2026-04-30-charter-telemetry.md new file mode 100644 index 0000000..5a3e9b7 --- /dev/null +++ b/docs/decisions/proposals/2026-04-30-charter-telemetry.md @@ -0,0 +1,211 @@ +# StrayMark — Esquema de telemetría de ejecución de Charters + +**Versión:** 0.3 (rename Plan → Charter; refinado tras seis ciclos del experimento `/plan-audit` en Sentinel) +**Fecha:** 30 de abril de 2026 +**Autor:** Jose Villaseñor Montfort — StrangeDaysTech +**Propósito:** Recopilar datos comparables sobre la ejecución real de Charters en proyectos adoptantes, para validar la hipótesis del patrón antes de cristalizarlo en un schema formal. +**Evidencia preliminar disponible:** ver `straymark-thesis-validation.md` §3 para el cuerpo de datos generado por Sentinel (5 telemetrías YAML, 6 reportes de auditoría dual, 5 AILOGs narrativos). + +--- + +## Por qué este documento existe + +Los Charters (descritos en `que-es-un-charter.md` y en `straymark-cloud-proposal.md` §4.5) son un patrón emergente del uso real de StrayMark. Antes de elevarlos a entidad de primera clase del producto y cristalizarlos en un schema formal, conviene observarlos en ejecución a través de varios proyectos y recopilar datos que respondan preguntas concretas sobre su utilidad real, sus puntos fuertes y sus modos de falla. + +Este documento define un shape de telemetría manual que se aplica al cierre de cada Charter ejecutado. La aplicación es deliberadamente ligera (5–10 minutos por Charter) para no introducir fricción que sesgue los datos. Los campos están elegidos para responder preguntas específicas del proyecto de investigación, no para ser exhaustivos. + +Este esquema es instrumental: existe para producir conocimiento, no para definir el producto. Cuando ese conocimiento esté disponible, el schema formal del Charter podrá absorber lo que corresponda y descartar lo demás. + +**Nota terminológica.** Lo que este documento llama "Charter" se llamó "Plan" en el experimento Sentinel (PLAN-01..06). Los datos empíricos citados abajo se refieren a esos Plans históricos por su nombre original; el shape del schema y los ejemplos prospectivos usan el nombre going-forward "Charter". Justificación del rename en `que-es-un-charter.md` §2. + +--- + +## Preguntas que la telemetría debe responder + +La instrumentación está diseñada para responder, con datos cuantitativos y cualitativos, las siguientes preguntas. Bajo cada pregunta se añade la **respuesta preliminar de Sentinel** cuando el experimento aportó datos relevantes. + +1. **¿La sección "Pre-trabajo antes de planning" cumple su propósito?** ¿Cuánto del pre-trabajo declarado se hace efectivamente antes de la sesión de planning? ¿Cuánto se descubre durante? Si el descubrimiento durante es alto, el campo no está cumpliendo su función. + + *Respuesta preliminar de Sentinel:* sin evidencia directa — los seis ciclos no usaron sesiones de planning formales separadas de la ejecución. El campo `additional_context_loaded_manually` (PLAN-06: 6 archivos cargados durante implementación) es proxy del descubrimiento durante. Pendiente proyecto con sesión de planning explícita. + +2. **¿Los AILOGs de origen siguen siendo útiles cuando el Charter se activa?** + + *Respuesta preliminar de Sentinel:* sí, validado en PLAN-06 (`originating_ailogs.AILOG-2026-04-25-015`, marcado `still_relevant_at_execution: true`). El AILOG de origen documentaba el switch de fuente RPM que generó el sesgo de baseline; sin él, el use-case del Plan no estaría articulado. + +3. **¿Las estimaciones de esfuerzo son fiables?** + + *Respuesta preliminar de Sentinel:* el campo en TIEMPO (XS/S/M/L) es predictivo, el de líneas no lo es. PLAN-01..05 todos cumplieron tiempo 1.0x; el drift de líneas varió de 1.0x a 8.1x. PLAN-06 dio drift de tiempo 1.33x (40 min real vs 30 estimado), atribuido al rigor de format v3 (drift script + AILOG estructurado). Conclusión: retirar la estimación en líneas; mantener TIEMPO como única métrica de esfuerzo. Aplicado en TEMPLATE v2 (Sentinel) y propagado al schema v0.x abajo. + +4. **¿Los triggers observables se disparan limpiamente?** + + *Respuesta preliminar de Sentinel:* en 5/5 Plans ejecutados el trigger declarado del roadmap **no disparó**; el signal real fue del meta-experimento (validación del flujo) o cierre de backlog. Conclusión: el campo `trigger.declared_kind` es prescriptivo (cuándo SHOULD ejecutarse), no predictivo. Esto sugiere refinar el shape del Charter para distinguir trigger declarado de trigger efectivo, capturando ambos. + +5. **¿La ejecución de un Charter genera nuevos Charters, y en qué proporción?** + + *Respuesta preliminar de Sentinel:* sostenible. PLAN-05 generó 0 Plans nuevos (los follow-ups F4/F5/F6 cierran como tareas menores en commit follow-up al PR, no como Plans). PLAN-06 generó 0 Plans nuevos. Ratio observado: 0 follow-up Plans por Plan ejecutado, dentro del rango sostenible (0-1) que el supuesto pedía. + +6. **¿La calidad de las decisiones del agente mejora cuando hay contexto del Charter cargado vs cuando no?** + + *Respuesta preliminar de Sentinel:* sí parcialmente — los AILOGs ricos exportan signal pública y los auditores externos convergen a calibración mayor (Copilot 9.25, Gemini 9.5 en PLAN-05) cuando hay TEMPLATE v2 + AILOG rico. Pero los gaps F4 (evaluator_test no implementado) y F5 (hallucination arquitectónica) muestran que el agente puede no documentar lo que olvida. La conclusión refinada: la disciplina hace los gaps *visibles* a auditores externos, no los elimina. Ver `straymark-thesis-validation.md` §4.2. + +--- + +## Esquema de telemetría por Charter + +El campo se agrega al cierre de cada Charter ejecutado, idealmente en el frontmatter del markdown del Charter o en un archivo asociado `.straymark/charters/CHARTER-XXX.telemetry.yaml` (en Sentinel los archivos análogos viven como `.straymark/plans/PLAN-XXX.telemetry.yaml`). + +```yaml +charter_telemetry: + # Identificación + charter_id: "CHARTER-2026-XX-YY-001" + charter_title: "string corto" + closed_at: "2026-XX-YY" + + # Origen y activación + originating_ailogs: + - ailog_id: "AILOG-2026-04-24-010" + still_relevant_at_execution: true # bool + relevance_notes: "texto opcional explicando si seguía relevante" + trigger: + declared_kind: "event_trigger | date | metric_threshold | infrastructure_milestone" + declared_description: "texto del Charter" + fired_at: "2026-XX-YY" + fire_clarity: "clear | ambiguous | manually_decided" + fire_clarity_notes: "texto opcional" + + # Pre-trabajo + pre_work: + items_declared: 3 # int — cuántos items listaste como pre-trabajo + items_completed_before_planning: 2 # int — cuántos hiciste antes de la sesión + items_skipped: 0 # int — cuántos no se hicieron (declarar por qué) + items_discovered_during_planning: 1 # int — cuántos pre-trabajos no listados aparecieron en sesión + pre_work_quality: "high | medium | low" # tu juicio cualitativo + pre_work_notes: "texto libre" + + # Sesión de planning (si la hubo) + planning_session: + occurred: true # bool — algunos Charters se ejecutan sin sesión formal + duration_minutes: 45 # int + participants: 1 # int + decisions_made: 3 # int — decisiones de diseño/scope tomadas + decisions_deferred: 0 # int — decisiones que requirieron más investigación + notes: "texto libre" + + # Ejecución (campo de líneas retirado — Sentinel demostró que no es predictivo) + execution: + started_at: "2026-XX-YY" + finished_at: "2026-XX-YY" + estimated_effort: "M (~1.5h)" # XS/S/M/L con tiempo aproximado en h + actual_effort: "M (~1.5h)" # tiempo observado + estimation_drift_factor: 1.0 # ratio actual/estimated en TIEMPO únicamente + estimation_drift_reason: "texto" + + # Calidad del trabajo del agente durante la ejecución + agent_quality: + sessions_count: 1 # int — sesiones de Claude Code u otro agente + hallucinations_caught: 2 # int — veces que el agente inventó algo y lo pillaste + hallucination_categories: + - "API inexistente" + - "comportamiento de librería incorrecto" + decisions_contradicting_prior_adrs: 1 # int + contradiction_notes: "texto si las hubo" + context_loaded_was_sufficient: true # bool + additional_context_loaded_manually: 0 # int — archivos extra cargados manualmente durante implementación + r_n_plus_one_emergent_count: 0 # riesgos emergentes nombrados durante ejecución + # (validados en 4/4 ciclos de Sentinel como señal cross-agent) + skill_prompts_used: ["/plan-audit", "/plan-audit-review"] + + # Auditoría externa — array, no objeto único. + # Sentinel validó que dual-audit (Copilot + Gemini) genera calibración cross-modelo + # y que el delta de categorización entre auditores es señal valiosa. + external_audit: + - auditor: "copilot-v1.0.37" + findings_total: 5 # int + findings_by_category: + hallucination: 0 + implementation_gap: 2 + real_debt: 2 + false_positive: 1 + audit_quality: "high | medium | low" # juicio del calibrador humano + audit_notes: "texto libre" + - auditor: "gemini-cli-v1" + findings_total: 4 + findings_by_category: + hallucination: 1 + implementation_gap: 2 + real_debt: 0 + false_positive: 1 + audit_quality: "high | medium | low" + audit_notes: "texto libre" + + # Resultado y follow-ups + outcome: + completed_as_planned: true # bool + scope_changes: "ninguno | menor | mayor" + scope_change_notes: | # codificación F1...FN consistente con claude-analisis + F1 (IG): descripción del primer drift declarado-vs-implementado. + F2 (hallucination): el Charter asumió X pero la realidad es Y. + F3 (FP): riesgo R sobre-anticipado, no se materializó. + new_followups_generated: 2 # int — AILOGs con follow-ups nuevos + new_charters_created: 1 # int — Charters nuevos derivados + charters_invalidated: 0 # int — otros Charters que este Charter hizo obsoletos + associated_stage_id: "STAGE-2026-XX-YY-NNN" + + # Friction points y wins (cualitativos) + qualitative: + format_iteration: "v3" # qué versión del TEMPLATE se usó + # (auto-evolutivo: cada Charter refina el formato del próximo) + friction_points: + - "El trigger 'cuando aterrice un UI de operadores' fue ambiguo; tuve que decidir manualmente" + - "Pre-trabajo subestimado: faltaba investigar comportamiento de RBAC" + wins: + - "Tener el AILOG de origen ahorró 30 min de re-discovery del contexto" + - "El agente no contradijo ADR-007 porque estaba cargado en contexto inicial" + overall_satisfaction: 4 # int 1-5 — qué tan útil fue el formato del Charter en este caso + would_repeat_format: true # bool + proposed_format_changes: "texto — alimenta la próxima versión del TEMPLATE" +``` + +--- + +## Convenciones de uso + +**Cuándo se llena.** Al cierre de cada Charter ejecutado, en el mismo commit que cierra el Stage asociado. Si el Charter se cancela o se vuelve obsoleto sin ejecutarse, también vale registrar telemetría con `outcome.completed_as_planned: false` y notas explicando por qué. + +**Cuánto detalle.** Suficiente para que un análisis posterior pueda detectar patrones, no tanto que la instrumentación introduzca fricción que distorsione los datos. Los campos cuantitativos (`int`, `bool`, `ratio`) son obligatorios; los cualitativos (texto libre) son opcionales pero altamente valorados — frecuentemente el insight está en las notas, no en los números. + +**Quién interpreta.** Inicialmente el autor del proyecto (Jose) interpreta su propia telemetría. Cuando haya datos de tres o más proyectos distintos, se puede empezar a comparar entre ellos. La interpretación cruzada genera mejor evidencia que la auto-interpretación. + +**Privacidad y publicación.** La telemetría se queda en el repo; no se publica automáticamente. Cuando los datos se usen para escribir sobre el patrón (blog, documentación, paper), se anonimiza lo necesario y se publica sólo lo que el autor consciente. + +--- + +## Datos retrospectivos disponibles desde fases 8–12 del MVP + +**Estado actual:** este ejercicio sigue pendiente. El experimento `/plan-audit` post-MVP cubre el frente *prospectivo* (Plans 01-06 ejecutados con telemetría completa) pero no el retrospectivo de las fases 8-12. Cuando se materialice, los datos pre/post-skills aportarán otro eje de validación al supuesto #2 de la tesis ("notas estructuradas reducen modos de falla"). Ver `straymark-thesis-validation.md` §4.2. + +Además de los Plans en ejecución, el proyecto Sentinel tiene historial de auditorías y evaluaciones desde las fases 8 a 12 del MVP. Ese historial es valioso porque captura una transición natural: introducción de las skills de auditoría que generan prompts contextuales para Géminis. La hipótesis observable es que las auditorías post-skills tienen mejor calidad (menos falsos positivos, mejor detección de gaps reales, menos fricción en remediación) que las pre-skills. + +Para extraer ese conocimiento, conviene aplicar a las fases 8–12 una versión retrospectiva del esquema de telemetría, llenando con la mejor información disponible. Específicamente, conviene capturar: + +- Para cada fase: número de hallazgos del auditor, distribución por categoría (hallucination, gap, deuda, falso positivo), tiempo de remediación, número de re-auditorías necesarias. +- Marcar la fase exacta en la que se introdujo cada iteración de las skills, para poder hacer comparación pre/post. +- Versionado de las skills usadas en cada fase, si está disponible. +- Notas cualitativas sobre cómo se sintió cada fase: qué funcionó, qué no, qué cambiarías. + +Este ejercicio retrospectivo puede hacerse en una sola sesión de 2–3 horas de revisión del historial. El output sería un archivo `sentinel-mvp-audit-retrospective.md` que sirve como input para análisis comparativo y como contenido editorial futuro. + +--- + +## Cómo este documento evoluciona + +Después de ejecutar Charters en proyectos adoptantes y aplicar la telemetría retrospectiva a las fases 8–12 de Sentinel, la información acumulada permitirá: + +1. **Validar o invalidar campos del esquema.** Si un campo nunca aporta señal, se elimina. Si aparece consistentemente un dato no capturado, se agrega. +2. **Detectar patrones reales.** Por ejemplo, si los Charters con triggers de tipo `event_trigger` tienen ejecuciones más limpias que los de tipo `infrastructure_milestone`, eso es señal accionable para el diseño del producto. +3. **Generar narrativa basada en datos.** Cuando llegue el momento de escribir sobre StrayMark (blog, documentación, conversaciones de venta), las afirmaciones estarán respaldadas por evidencia concreta, no por intuición. +4. **Cristalizar el schema formal del Charter.** Sentinel produjo, a través del ciclo `/plan-audit` v1 → v2 → v3, un borrador empírico de TEMPLATE.md y un script `check-plan-drift.sh` validados con cero falsos positivos sobre dos tests empíricos. Ese borrador es el material de entrada para `charter.schema.v0.json` y `charter-telemetry.schema.v0.json` (ambos marcados *experimental* hasta validación con un segundo proyecto en otro dominio — ver `straymark-thesis-validation.md` §6 para el argumento N≈2-3). El schema `v1.0` estable requiere un eje de validación adicional: dominio distinto a Go backend. + +--- + +*Este es un instrumento de aprendizaje, no un compromiso de producto. Su valor se mide en cuánto conocimiento accionable produce sobre el patrón de Charters, no en su completitud o sofisticación.* diff --git a/Propuesta/devtrail-thesis-validation.md b/docs/decisions/proposals/2026-04-30-thesis-validation.md similarity index 83% rename from Propuesta/devtrail-thesis-validation.md rename to docs/decisions/proposals/2026-04-30-thesis-validation.md index 1e3de07..d4ec52e 100644 --- a/Propuesta/devtrail-thesis-validation.md +++ b/docs/decisions/proposals/2026-04-30-thesis-validation.md @@ -1,12 +1,12 @@ -# DevTrail — Validación empírica de la tesis con datos de Sentinel +# StrayMark — Validación empírica de la tesis con datos de Sentinel **Versión:** 0.2 (rename Plan → Charter en referencias going-forward; las citas históricas a Sentinel preservan "Plan") **Fecha:** 30 de abril de 2026 **Autor:** Jose Villaseñor Montfort — StrangeDaysTech -**Propósito:** Confrontar la tesis del producto, articulada en `devtrail-cloud-proposal.md` §2, contra la evidencia empírica generada por el primer experimento que la pone a prueba: `/plan-audit` ejecutado en el repo Sentinel durante 6 ciclos (PLAN-01..06) entre el 25 y el 28 de abril de 2026. -**Documentos relacionados:** `devtrail-cloud-proposal.md`, `devtrail-design-principles.md`, `devtrail-charter-telemetry.md`, `devtrail-cli-roadmap.md`, `que-es-un-charter.md` (rename Plan → Charter). +**Propósito:** Confrontar la tesis del producto, articulada en `straymark-cloud-proposal.md` §2, contra la evidencia empírica generada por el primer experimento que la pone a prueba: `/plan-audit` ejecutado en el repo Sentinel durante 6 ciclos (PLAN-01..06) entre el 25 y el 28 de abril de 2026. +**Documentos relacionados:** `straymark-cloud-proposal.md`, `straymark-design-principles.md`, `straymark-charter-telemetry.md`, `straymark-cli-roadmap.md`, `que-es-un-charter.md` (rename Plan → Charter). -**Nota de vocabulario.** Este documento cita extensamente evidencia de Sentinel, donde el artefacto se llamó "Plan" (PLAN-01..06). Esas referencias históricas se preservan en su forma original. Las afirmaciones prospectivas sobre el producto DevTrail going-forward (§6 schemas, §8 decisiones) usan el nombre actual "Charter". Justificación del rename en `que-es-un-charter.md` §2. +**Nota de vocabulario.** Este documento cita extensamente evidencia de Sentinel, donde el artefacto se llamó "Plan" (PLAN-01..06). Esas referencias históricas se preservan en su forma original. Las afirmaciones prospectivas sobre el producto StrayMark going-forward (§6 schemas, §8 decisiones) usan el nombre actual "Charter". Justificación del rename en `que-es-un-charter.md` §2. --- @@ -14,8 +14,8 @@ Los otros tres documentos de `Propuesta/` se escribieron antes de tener datos. Son hipótesis: cómo querríamos que fuera la herramienta, qué principios queremos defender, qué patrón de mercado creemos servir. La tesis central es la pieza más cargada y más arriesgada de ese conjunto: -> "DevTrail es la disciplina cognitiva externalizada que un ingeniero senior necesita cuando orquesta agentes de IA en proyectos medianos a grandes. Estructura la memoria del proyecto, restringe el espacio de decisión del agente con reglas vivas, y produce como subproducto una evidencia auditable que sirve también para cumplimiento regulatorio cuando hace falta. El producto principal es la herramienta que mejora el oficio; el cumplimiento es valor adicional aprovechable, no el motor." -> — `devtrail-cloud-proposal.md` §2 +> "StrayMark es la disciplina cognitiva externalizada que un ingeniero senior necesita cuando orquesta agentes de IA en proyectos medianos a grandes. Estructura la memoria del proyecto, restringe el espacio de decisión del agente con reglas vivas, y produce como subproducto una evidencia auditable que sirve también para cumplimiento regulatorio cuando hace falta. El producto principal es la herramienta que mejora el oficio; el cumplimiento es valor adicional aprovechable, no el motor." +> — `straymark-cloud-proposal.md` §2 Este documento confronta esa tesis con datos. No la defiende; intenta romperla. El objetivo es que un lector que no compró la tesis pueda, leyendo solo este texto, decidir si la evidencia disponible la sostiene, la matiza o la refuta. Si la evidencia no alcanza para algún supuesto, lo nombramos explícitamente y proponemos qué proyecto cerraría el gap. @@ -23,7 +23,7 @@ El sesgo de auto-confirmación es el riesgo principal: el experimento lo diseña ## 2. La tesis y sus seis supuestos verificables -`devtrail-cloud-proposal.md` §2 descompone la tesis en seis supuestos que se derivan del uso real del CLI en proyectos como Sentinel. Los reproducimos aquí para anclar la confrontación: +`straymark-cloud-proposal.md` §2 descompone la tesis en seis supuestos que se derivan del uso real del CLI en proyectos como Sentinel. Los reproducimos aquí para anclar la confrontación: 1. **Vibe coding no escala.** El "vibe coding" no escala a proyectos medianos a grandes; el agente, sin estructura externa, acumula deuda técnica oculta, alucinaciones recurrentes y deriva arquitectónica que el ingeniero descubre tarde y caro. 2. **Notas estructuradas reducen modos de falla.** Una capa de notas estructuradas, vivas y reglamentadas sobre el flujo de trabajo del agente reduce significativamente esos modos de falla. AILOGs, ADRs y AIDECs no son burocracia: son memoria extendida y guardarraíles de razonamiento. @@ -34,7 +34,7 @@ El sesgo de auto-confirmación es el riesgo principal: el experimento lo diseña ## 3. El experimento: Sentinel `/plan-audit` -Sentinel es el repo de un sistema Go (~15.9 kLOC al cierre del MVP, 96 archivos de producción) que adopta DevTrail como framework de governanza desde sus primeras Etapas. El experimento `/plan-audit` corre en paralelo al desarrollo post-MVP: cada Plan ejecutado se documenta con telemetría YAML, se audita con dos modelos externos (Copilot v1.0.37 y Gemini CLI v1) en paralelo, y se consolida con un análisis crítico de Claude. +Sentinel es el repo de un sistema Go (~15.9 kLOC al cierre del MVP, 96 archivos de producción) que adopta StrayMark como framework de governanza desde sus primeras Etapas. El experimento `/plan-audit` corre en paralelo al desarrollo post-MVP: cada Plan ejecutado se documenta con telemetría YAML, se audita con dos modelos externos (Copilot v1.0.37 y Gemini CLI v1) en paralelo, y se consolida con un análisis crítico de Claude. **Seis ciclos completos (25–28 abril 2026):** @@ -55,9 +55,9 @@ Sentinel es el repo de un sistema Go (~15.9 kLOC al cierre del MVP, 96 archivos **Fuentes de evidencia (rutas absolutas en el filesystem del autor):** -- Telemetría YAML: `/E/Proyectos/StrangeDaysTech/sentinel/.devtrail/plans/PLAN-{01,02,03,05,06}.telemetry.yaml` +- Telemetría YAML: `/E/Proyectos/StrangeDaysTech/sentinel/.straymark/plans/PLAN-{01,02,03,05,06}.telemetry.yaml` - Auditorías externas duales: `/E/Proyectos/StrangeDaysTech/sentinel/audit/plans/{05,06}/{copilot-v1.0.37-audit,gemini-cli-v1-audit,claude-analisis}.md` -- Narrativa decision-by-decision: `/E/Proyectos/StrangeDaysTech/sentinel/.devtrail/07-ai-audit/agent-logs/AILOG-2026-04-28-{020,021,022,023,024}-*.md` +- Narrativa decision-by-decision: `/E/Proyectos/StrangeDaysTech/sentinel/.straymark/07-ai-audit/agent-logs/AILOG-2026-04-28-{020,021,022,023,024}-*.md` - Tooling ejecutable validado: `/E/Proyectos/StrangeDaysTech/sentinel/scripts/check-plan-drift.sh` - Plan-docs canónicos bajo TEMPLATE: `/E/Proyectos/StrangeDaysTech/sentinel/docs/plans/{05,06}-*.md` @@ -67,7 +67,7 @@ Sentinel es el repo de un sistema Go (~15.9 kLOC al cierre del MVP, 96 archivos **Verdict: Validado parcialmente.** -El experimento no comparó head-to-head "agente con DevTrail" vs "agente sin DevTrail" — Sentinel adoptó DevTrail desde el inicio. Pero sí mostró que, *incluso con* disciplina y AILOGs estructurados, el agente acumula gaps no documentados que solo afloran con auditoría externa. Esto es un proxy: si con disciplina el agente todavía olvida cosas, sin disciplina las olvidaría todas. +El experimento no comparó head-to-head "agente con StrayMark" vs "agente sin StrayMark" — Sentinel adoptó StrayMark desde el inicio. Pero sí mostró que, *incluso con* disciplina y AILOGs estructurados, el agente acumula gaps no documentados que solo afloran con auditoría externa. Esto es un proxy: si con disciplina el agente todavía olvida cosas, sin disciplina las olvidaría todas. > "F4 (IG): `evaluator_test.go` declarado con 3 tests para `ResolveAnomalyThresholds` pero **sin cambios en el rango**. Cobertura unitaria del resolver ausente. **Hallazgo no documentado en AILOG-021** — gap real de cobertura." > — `audit/plans/05/claude-analisis.md` §3 (línea ~106), captura combinada de Copilot + Gemini. @@ -80,7 +80,7 @@ El experimento no comparó head-to-head "agente con DevTrail" vs "agente sin Dev **Lo validado:** el agente, incluso con disciplina, comete dos clases de fallo que solo afloran post-hoc: (a) implementación olvidada del Plan (F4: 3 tests prometidos no escritos), (b) hallucination arquitectónica del Plan-doc mismo (F5: el Plan asumió un punto de inyección que no existe). Ninguna de las dos fue capturada por checkpoints internos del agente — solo por auditoría externa multi-modelo. -**Lo no demostrado:** que sin DevTrail el problema sería *peor*. La hipótesis es plausible (los gaps capturados son justamente del tipo que se esfuma cuando no hay un Plan-doc declarado contra el que comparar), pero el experimento no construyó un brazo de control. Para una validación más fuerte, un proyecto futuro con dos brazos (con disciplina vs sin) o un proyecto que adopte DevTrail tarde y mida el delta de gaps capturados antes/después cerraría el supuesto. +**Lo no demostrado:** que sin StrayMark el problema sería *peor*. La hipótesis es plausible (los gaps capturados son justamente del tipo que se esfuma cuando no hay un Plan-doc declarado contra el que comparar), pero el experimento no construyó un brazo de control. Para una validación más fuerte, un proyecto futuro con dos brazos (con disciplina vs sin) o un proyecto que adopte StrayMark tarde y mida el delta de gaps capturados antes/después cerraría el supuesto. ### 4.2 Supuesto 2 — Notas estructuradas reducen modos de falla @@ -175,11 +175,11 @@ La parte *evidencia in-situ* está fuertemente validada: `check-plan-drift.sh` e > "Validación de hipótesis v3: `check-plan-drift.sh` reportó 0 drift pre-commit; los 3 findings reales son del tipo que el script no puede detectar por diseño (mitigaciones no implementadas, scope text vs payload, tests promised vs realized). Confirma: script + auditorías son complementarios." > — `AILOG-024` §Post-audit fixes (línea 154–158). -**Lo no probado todavía:** la parte de *firma criptográfica*. Sentinel no firmó bundles con Sigstore/cosign ni implementó hash-chaining. La afirmación de que firmar in-situ es estructuralmente más confiable que reconstrucción posterior es plausible (es la propiedad técnica de cualquier append-only log) pero el experimento no la ejercitó. Cerrar este gap requiere implementar `devtrail stage close` con firma cosign en un próximo ciclo y un escenario de tampering simulado para verificar detección. +**Lo no probado todavía:** la parte de *firma criptográfica*. Sentinel no firmó bundles con Sigstore/cosign ni implementó hash-chaining. La afirmación de que firmar in-situ es estructuralmente más confiable que reconstrucción posterior es plausible (es la propiedad técnica de cualquier append-only log) pero el experimento no la ejercitó. Cerrar este gap requiere implementar `straymark stage close` con firma cosign en un próximo ciclo y un escenario de tampering simulado para verificar detección. ## 5. Fricciones detectadas y marco virtud-vs-ceremonia -Sentinel reveló cuatro puntos de fricción cuantificables. El principio #6 de `devtrail-design-principles.md` ya establece que "fricción justificada es aceptable y a veces deseable". El refinamiento empírico del experimento es distinguir *fricción virtuosa* (la que externaliza signal a auditores externos y captura gaps que el agente solo no captura) de *ceremonia atacable* (la que solo genera triage manual o prescribe sin reflexividad). +Sentinel reveló cuatro puntos de fricción cuantificables. El principio #6 de `straymark-design-principles.md` ya establece que "fricción justificada es aceptable y a veces deseable". El refinamiento empírico del experimento es distinguir *fricción virtuosa* (la que externaliza signal a auditores externos y captura gaps que el agente solo no captura) de *ceremonia atacable* (la que solo genera triage manual o prescribe sin reflexividad). ### 5.1 Overhead de documentación — virtud parcial @@ -211,11 +211,11 @@ El Plan declaró una verificación que la realidad de testcontainers + audit pip ### 5.5 Síntesis del marco -La fricción de DevTrail es virtud cuando externaliza signal pública (R, drift detection, auditoría dual) y captura gaps que el agente solo no captura. La fricción es ceremonia atacable cuando solo genera triage o prescribe sin reflexividad. La primera se mantiene; la segunda es bug del formato, no virtud del principio. El refinamiento de `devtrail-design-principles.md` v0.2 incorpora explícitamente esta distinción. +La fricción de StrayMark es virtud cuando externaliza signal pública (R, drift detection, auditoría dual) y captura gaps que el agente solo no captura. La fricción es ceremonia atacable cuando solo genera triage o prescribe sin reflexividad. La primera se mantiene; la segunda es bug del formato, no virtud del principio. El refinamiento de `straymark-design-principles.md` v0.2 incorpora explícitamente esta distinción. ## 6. El argumento N≈2-3: por qué Sentinel cuenta más que un proyecto -El principio #12 de `devtrail-design-principles.md` v0.1 establece: "no debe avanzar más rápido de lo que aprendemos sobre cómo se usa realmente. Cristalizar features prematuramente, antes de tener datos de uso real en al menos tres proyectos distintos, genera costos altos de mantenimiento sobre features que pueden ser equivocadas". +El principio #12 de `straymark-design-principles.md` v0.1 establece: "no debe avanzar más rápido de lo que aprendemos sobre cómo se usa realmente. Cristalizar features prematuramente, antes de tener datos de uso real en al menos tres proyectos distintos, genera costos altos de mantenimiento sobre features que pueden ser equivocadas". Sentinel es *un solo proyecto* en el sentido literal (un repo, un dominio Go backend, un autor). Pero la evidencia que produjo tiene tres ejes de diversidad estructural que el principio busca capturar: @@ -238,12 +238,12 @@ Tres patrones emergieron del experimento que ninguno de los tres documentos de p **7.1 El formato es auto-evolutivo.** Ninguno de los tres docs anticipó que la aplicación del formato a sí mismo (telemetría → análisis crítico → propuesta de mejora → nuevo formato) sería un ciclo natural. Esto es un meta-patrón estructural que merece nombre propio en futuras versiones de los principios. Candidato: principio #13 ("la herramienta evoluciona consigo misma; cada uso es input para la próxima versión") o ampliación del principio #12. -**7.2 Drift script y auditoría externa son complementarios, no sustitutos.** AILOG-022 hipotetizó complementariedad; PLAN-06 la confirmó empíricamente. Esto cambia el marco mental de cómo diseñar tooling DevTrail: cada layer debe atacar un tipo de drift distinto (declaración vs implementación vs comportamiento), no replicar capacidades existentes. +**7.2 Drift script y auditoría externa son complementarios, no sustitutos.** AILOG-022 hipotetizó complementariedad; PLAN-06 la confirmó empíricamente. Esto cambia el marco mental de cómo diseñar tooling StrayMark: cada layer debe atacar un tipo de drift distinto (declaración vs implementación vs comportamiento), no replicar capacidades existentes. > "Hipótesis v3 confirmada: script + auditorías + AILOG son herramientas complementarias. Ninguna sustituye a las otras." > — `audit/plans/06/claude-analisis.md` §7 (línea 145). -**7.3 Auditoría dual como calibrador de modelos.** PLAN-05 fue el caso límite: Gemini calibró F5 correctamente como `hallucination` mientras Copilot lo categorizó como `implementation_gap`. La auditoría dual no es solo "dos pares de ojos" — es un mecanismo de calibración cross-modelo. El claude-analisis funciona como tercer modelo que reconcilia veredictos divergentes según el schema definicional. Esto sugiere una arquitectura de tres niveles para `devtrail charter audit` (fase 3 del roadmap): dos auditores en paralelo + un calibrador-reconciliador, no solo "ejecuta un audit con N modelos". +**7.3 Auditoría dual como calibrador de modelos.** PLAN-05 fue el caso límite: Gemini calibró F5 correctamente como `hallucination` mientras Copilot lo categorizó como `implementation_gap`. La auditoría dual no es solo "dos pares de ojos" — es un mecanismo de calibración cross-modelo. El claude-analisis funciona como tercer modelo que reconcilia veredictos divergentes según el schema definicional. Esto sugiere una arquitectura de tres niveles para `straymark charter audit` (fase 3 del roadmap): dos auditores en paralelo + un calibrador-reconciliador, no solo "ejecuta un audit con N modelos". ## 8. Verdict global y siguientes pasos @@ -262,13 +262,13 @@ Tres patrones emergieron del experimento que ninguno de los tres documentos de p 1. **Adoptante en otro dominio** (frontend, ML pipeline, infra) para diversificar el eje "dominio" del principio #12. Cierra parte del supuesto #1 si se mide delta de gaps capturados antes/después. 2. **Proyecto con flujo multi-actor** (al menos 2 personas decisoras, aprobación asíncrona, condiciones diferidas reales). Cierra el supuesto #4. -3. **Implementación de `devtrail stage close` con firma cosign + escenario de tampering** en uno de los repos existentes. Cierra la parte criptográfica del supuesto #6. +3. **Implementación de `straymark stage close` con firma cosign + escenario de tampering** en uno de los repos existentes. Cierra la parte criptográfica del supuesto #6. 4. **Revisión por un auditor ISO 42001 humano real** de los outputs de Sentinel. Cierra el supuesto #3 frente a un consumidor real, no solo frente a la estructura compatible. **Decisiones que la tesis valida y se pueden tomar ahora:** - Cristalizar Charters como entidad de primera clase del CLI con schema `v0.json` marcado experimental. -- Portar `TEMPLATE.md v3` y `check-plan-drift.sh` como artefactos canónicos del framework (renombrados en destino a `charter-template.md` y `devtrail charter drift` — ver `devtrail-cli-roadmap.md` §6). +- Portar `TEMPLATE.md v3` y `check-plan-drift.sh` como artefactos canónicos del framework (renombrados en destino a `charter-template.md` y `straymark charter drift` — ver `straymark-cli-roadmap.md` §6). - Mantener la jerarquía de personas (ingeniero senior primario) sin sesgo hacia compliance officer. - Posicionar el producto sobre "disciplina cognitiva" en marketing y docs, no sobre "compliance tool". @@ -278,8 +278,8 @@ Tres patrones emergieron del experimento que ninguno de los tres documentos de p - Comprometer un schema `v1.0` estable de Charters sin evidencia de un segundo dominio. - Marketing de "AI BOM agregado" sin haber probado la firma criptográfica en producción. -Las acciones del primer grupo se reflejan en `devtrail-cli-roadmap.md` v0.1 como Fase 1. Las del segundo grupo quedan explícitamente bloqueadas hasta evidencia adicional, manteniendo el principio #12 (velocidad = velocidad del aprendizaje). +Las acciones del primer grupo se reflejan en `straymark-cli-roadmap.md` v0.1 como Fase 1. Las del segundo grupo quedan explícitamente bloqueadas hasta evidencia adicional, manteniendo el principio #12 (velocidad = velocidad del aprendizaje). --- -*Este documento es la entrada principal para profundización empírica sobre la tesis de DevTrail. Las decisiones de producto que se tomen en `devtrail-cloud-proposal.md` v0.3 y `devtrail-cli-roadmap.md` v0.1 referencian sus secciones específicas como ancla de evidencia.* +*Este documento es la entrada principal para profundización empírica sobre la tesis de StrayMark. Las decisiones de producto que se tomen en `straymark-cloud-proposal.md` v0.3 y `straymark-cli-roadmap.md` v0.1 referencian sus secciones específicas como ancla de evidencia.* diff --git a/docs/decisions/proposals/2026-05-03-audit-skills-design.md b/docs/decisions/proposals/2026-05-03-audit-skills-design.md new file mode 100644 index 0000000..132ad26 --- /dev/null +++ b/docs/decisions/proposals/2026-05-03-audit-skills-design.md @@ -0,0 +1,358 @@ +# StrayMark — Auditoría externa como skill: checkpoint humano-en-el-loop y `/straymark-audit-{prompt,review}` + +**Versión:** 0.2 (Fase 1 implementada y shippeada — diseño v0 experimental, segundo dominio aún pendiente para cristalización a v1) +**Fecha:** 3 de mayo de 2026 +**Autor:** Jose Villaseñor Montfort — StrangeDaysTech +**Propósito:** Cerrar la fricción entre el CLI orchestration-only (`straymark charter audit`) y el agente que está dentro de la conversación del developer. Hoy el CLI escribe prompts a disco y el operador los abre manualmente; falta el paso "el agente principal te dice que llegamos a un checkpoint y te ofrece el prompt inline". Esta propuesta abstrae los skills `plan-audit` y `plan-audit-review` de Sentinel a `straymark-audit-prompt` y `straymark-audit-review` (instalables vía `straymark init` para todos los adoptantes) y agrega guidance de checkpoint a `AGENT-RULES.md`. +**Documentos relacionados:** `straymark-cli-roadmap.md` v0.3 §5 (Phase 3 audit, decisión A1 orchestration-only), `straymark-design-principles.md` v0.2 (#6 fricción virtuosa, #10 CLI no es LLM gateway, #12 cristalización experimental), `straymark-charter-telemetry.md` v0.3 (campo `external_audit` array), `que-es-un-charter.md` (alcance del Charter como ancla de auditoría ex-post), `straymark-audit-skills-implementacion.md` v0.2 (plan de rollout — Fase 1 cerrada, Fase 2 en recolección). + +--- + +## 0. Estado de implementación (al 3 de mayo de 2026) + +**Fase 1 cerrada.** La release `fw-4.8.0` / `cli-3.9.0` aterriza las dos skills, el flag CLI `--merge-into`, la guidance del checkpoint en `AGENT-RULES.md`, las docs adopter, y bumps de versión — entregadas en 5 PRs secuenciales mergeados el mismo día. + +**PRs shippeados:** + +| # | Tipo | PR | Aporte | +|---|---|---|---| +| 1 | feat(framework) | [#96](https://github.com/StrangeDaysTech/straymark/pull/96) | Skill `straymark-audit-prompt` × 3 plataformas (Claude / Gemini / agent) + 4 tests fixture | +| 2 | feat | [#97](https://github.com/StrangeDaysTech/straymark/pull/97) | Skill `straymark-audit-review` × 3 plataformas + flag CLI `straymark charter audit --finalize --merge-into ` + 4 tests integration sobre el merge + 4 tests fixture sobre el skill + fix bonus de placeholder `` en `audit_notes:` | +| 3 | feat(framework) | [#98](https://github.com/StrangeDaysTech/straymark/pull/98) | `AGENT-RULES.md §12 Audit Checkpoint` × 3 langs (EN / ES / zh-CN) + 4 tests fixture (presencia + paridad de anchors language-agnostic) | +| 4 | docs | [#99](https://github.com/StrangeDaysTech/straymark/pull/99) | Adopter docs: `WORKFLOWS.md`, `CLI-REFERENCE.md` (nueva `## Skills` section listando los 9 skills), `ADOPTION-GUIDE.md` (nueva `## External Audit (Optional)`), `QUICK-REFERENCE.md` — todos × 3 langs | +| 5 | chore | [#100](https://github.com/StrangeDaysTech/straymark/pull/100) | Bump `fw-4.7.1` → `fw-4.8.0` + `cli-3.8.1` → `cli-3.9.0`, version refs en 22 archivos × 3 langs, CHANGELOG combined section, tags `fw-4.8.0` y `cli-3.9.0` push (release workflows ejecutados) | + +**Decisiones de §2 materializadas:** + +- **D1 (skill = wrapper del CLI)** ✅ — ambas skills delegan vía `Bash(straymark charter audit *)` a la implementación canónica. Plantillas viven solo en `dist/.straymark/audit-prompts/`. Cero drift posible entre skill y CLI. +- **D2 (checkpoint soft, sin escalación a hard)** ✅ — `AGENT-RULES.md §12` declara explícitamente "this is a permanent v0+v1 design decision; see `Propuesta/straymark-audit-skills.md §2.2`". Ningún PR introdujo enforcement. `straymark metrics` no incluye KPI de audit coverage. +- **D3 (`straymark-audit-review` auto-mergea)** ✅ — implementado vía el flag nuevo `--merge-into `. String-level append a indent 2 bajo `charter_telemetry:`, preservando el shape hand-written de `charter close`. v0 rechaza re-audit con mensaje claro (manual reconciliation cuando aterriza re-merge en futuro). + +**Heurística arborist (§4.3) materializada:** + +La heurística "diff con función > 2× threshold cognitivo" está codificada en `AGENT-RULES.md §12` con graceful-degradation explícita ("if the binary lacks the `analyze` feature, silently skip this signal — do not warn, do not mention"). Los binarios oficiales (`release-cli.yml`) compilan con `default = ["tui", "analyze"]`, así que en práctica el 99% de adoptantes la tienen activa. + +**Cobertura de tests añadida:** 16 tests nuevos (8 fixture sobre skills × 2 + 4 fixture sobre §12 checkpoint + 4 integration sobre `--merge-into`). Suite completa: 271 unit + todas las integration verdes. + +**Items §6 (mapping a documentación) shipped:** + +- `dist/.straymark/00-governance/AGENT-RULES.md` § 12 (3 langs) — ✅ +- `docs/adopters/WORKFLOWS.md` (3 langs) — ✅ +- `docs/adopters/CLI-REFERENCE.md` (3 langs) con nueva sección `## Skills` listando los 9 skills + nueva `### Audit checkpoint` + callout "Skill alternative" en `### straymark charter audit` — ✅ +- `docs/adopters/ADOPTION-GUIDE.md` (3 langs) con sección `## External Audit (Optional)` — ✅ +- `dist/.straymark/00-governance/QUICK-REFERENCE.md` (3 langs) con tabla de skills completa — ✅ +- `README.md` (3 langs) — sin cambios materiales (solo bumps de versión vía sed) +- `CHANGELOG.md` — sección combined `Framework 4.8.0 / CLI 3.9.0` — ✅ +- `dist/STRAYMARK.md` — sin cambios (intencionalmente minimal) + +**Items diferidos a Fase 2 — observación, no implementación:** + +La recolección de telemetría operativa (cuántos checkpoints emit, cuántos audits aceptados/rechazados, correlación complejidad ↔ findings, diff_size ↔ findings_total) está descrita en `straymark-audit-skills-implementacion.md §2`. Requiere que la release ejercite en Sentinel + adoptante de frontend antes de poder entrar a Fase 3 (decisiones §9 sobre integración mayor de arborist). + +**Open issues a la fecha:** ninguno atribuible al rollout. + +**Items diferidos a v1 con criterio de salida explícito** (de §10 + del §9 del propuesta original): + +- Re-audit (append a `external_audit:` ya presente) — gated en demanda real de adopter. +- Auto-detección y enforcement de heterogeneidad inter-familia — diferido a v1, dependiente de que aterricen HTTP clients (decisión A1 del roadmap). +- Integración mayor de arborist (4 gaps de §9) — gated en data acumulada en Fase 2 + ciclo del adoptante de frontend. +- Cristalización del schema `audit-telemetry.schema.v0.json` a v1 estable — gated en segundo dominio (frontend). + +--- + +## 1. Contexto y problema + +### 1.1 El estado shippeado (`fw-4.7.1` / `cli-3.8.1`) + +El CLI ya orquesta auditoría multi-modelo en 3 pasos: + +- **PREPARE** — escribe `audit/charters/CHARTER-XX/prompts/auditor-{primary,secondary}.prompt.md` resolviendo plantillas en `dist/.straymark/audit-prompts/` con el contenido del Charter, git diff y AILOGs origen. +- **CALIBRATE** — valida las respuestas del operador contra `audit-output.schema.v0.json` y escribe `prompts/calibrator-reconciler.prompt.md`. +- **FINALIZE** — valida el calibrator response y **imprime** un bloque YAML formateado para el array `external_audit:` de la telemetría. + +El operador, entre paso y paso: (a) abre los archivos de prompt del disco, (b) los pega en su auditor de elección, (c) guarda las respuestas a paths canónicos, (d) re-ejecuta el comando con `--calibrate` o `--finalize`, (e) **copia-pega el YAML del FINALIZE a la telemetría manualmente**. Ver `cli/src/commands/charter/audit.rs` y `docs/adopters/CLI-REFERENCE.md` `### straymark charter audit`. + +### 1.2 Tres gaps que la propuesta atiende + +**G1 — No hay checkpoint en el workflow del agente.** `docs/adopters/WORKFLOWS.md` describe "passive loop: trabajar → documentar → review → commit" sin mencionar audit. `charter close` (`cli/src/commands/charter/close.rs`) no referencia audit. La decisión "auditar o no" hoy depende enteramente de memoria del developer, sin un punto explícito donde el agente que está co-implementando el Charter le ofrezca la opción. + +**G2 — Los prompts viven en disco, no en la conversación.** Los IDEs modernos (Claude Code, Cursor, etc.) son el contexto natural donde el developer interactúa con el agente. El CLI escribe prompts a archivos; el developer tiene que abrirlos en otro pane y copiarlos a otro modelo manualmente. Para un flujo IDE-first, el agente debería poder **imprimir el prompt directamente en la conversación**. + +**G3 — Sentinel tiene los skills, StrayMark no.** `sentinel/.claude/skills/plan-audit/` y `plan-audit-review/` (vocabulario "Plan", precediendo el rename a Charter) implementan exactamente este patrón — generar prompt inline, calibrar al regreso, fusionar en telemetría. Pero están acoplados a paths Sentinel-específicos (`docs/plans/`, `internal/modules/`, `go vet`, etc.) y no existen como skills StrayMark genéricos. Sentinel lleva 6 ciclos validándolos empíricamente; portarlos al framework cierra el segundo dominio operativo (skills + CLI dentro de StrayMark) sin esperar al adoptante de frontend. + +### 1.3 Por qué esto importa más allá del flow operativo + +StrayMark acelera el desarrollo a una cadencia que el operador humano no puede seguir por inspección directa — los Charters cierran, los AILOGs aterrizan, las telemetrías se llenan. Si en cada cierre el operador tuviera que mover datos manualmente entre archivos, el throughput colapsaría y la disciplina dejaría de ser fricción virtuosa para volverse ceremonia (principio #6). **Lo que se pueda automatizar de forma reversible debe automatizarse**; los documentos quedan para auditoría humana ex-post. + +## 2. Decisiones tomadas (con justificación) + +### 2.1 D1 — Las skills delegan al CLI, no son standalone + +`/straymark-audit-prompt CHARTER-XX` ejecuta `straymark charter audit CHARTER-XX` (PREPARE) por debajo, **lee** los archivos `prompts/auditor-{primary,secondary}.prompt.md` que el CLI acaba de escribir, e imprime su contenido inline en la conversación junto con guidance sobre qué modelo usar para cada uno. Análogamente, `/straymark-audit-review CHARTER-XX` ejecuta el `--calibrate` y luego el `--finalize`, leyendo los outputs intermedios. + +**Justificación:** + +- Single source of truth: las plantillas viven solo en `dist/.straymark/audit-prompts/`. El CLI las resuelve, la skill las consume. Cero drift entre plantilla-CLI y plantilla-skill. +- Compatibilidad con flujo no-IDE: un adoptante en CI o sin agente IDE-side sigue usando solo el CLI; los outputs son idénticos (mismas paths, mismo schema, misma telemetría). +- Cumple principio #10: el CLI sigue siendo el orquestador, la skill es UX inline. + +### 2.2 D2 — Checkpoint soft, sin escalación a hard planeada + +El checkpoint vive como guidance en `dist/.straymark/00-governance/AGENT-RULES.md` y como recordatorio en `WORKFLOWS.md`. **`charter close` no verifica** si la auditoría se realizó — close puede ejecutarse con o sin `audit/charters/CHARTER-XX/calibrator-reconciler.md` presente, sin warning, sin error, sin flag `--no-audit`. + +**Justificación (explícita y permanente):** + +- La auditoría externa cuesta dinero. Pedirle al adoptante 2-3 modelos pagos por cada Charter es una barrera real de adopción que no se debe disfrazar de "best practice". +- StrayMark ya provee disciplina suficiente (Charter declarativo + drift check + AILOG con R + telemetría ex-post) para que el resultado sea confiable sin auditoría externa. La auditoría es **señal adicional**, no requisito de cierre. +- La asimetría (close enforcing audit) penalizaría al adoptante por no tener recursos, dejando una marca permanente en su documentación. StrayMark no debe generar fricción que el adoptante percibiría como castigo por no consumir más LLMs. +- Esta decisión se cristaliza ahora y **no se revisa** en ciclos futuros — no hay "v1 hard enforcement" en el roadmap. Si un adoptante quiere enforcement, puede agregarlo en su CI con un check propio sobre los archivos del directorio `audit/charters/`. + +### 2.3 D3 — `/straymark-audit-review` auto-mergea el YAML en la telemetría + +Después de generar el calibrator response y validar los 3 outputs, la skill **edita** `.straymark/charters/CHARTER-XX.telemetry.yaml` directamente, insertando el array `external_audit:` con el contenido del FINALIZE. El developer ve el diff antes de aceptar (o vía git diff inmediatamente después). + +**Justificación:** + +- Cierra el último copy-paste manual del flujo audit. La velocidad operativa de StrayMark (descrita en §1.3) hace que dejar este paso al humano sea fricción no-virtuosa. +- Reversibilidad por inspección: el merge produce un cambio en un archivo YAML versionado; cualquier error es trivialmente reversible con `git checkout` o edición manual. +- Coincide con lo que Sentinel `plan-audit-review` hace empíricamente desde Plan-01. + +## 3. Diseño de los dos skills + +### 3.1 `straymark-audit-prompt` + +**Naming:** `straymark-audit-prompt` (kebab-case, prefijo `straymark-`, paralelo a los 7 skills existentes). + +**Distribución:** Tres archivos paralelos, instalados vía `dist-manifest.yml` que ya incluye `.claude/skills/`, `.gemini/skills/`, `.agent/workflows/`: + +- `dist/.claude/skills/straymark-audit-prompt/SKILL.md` — frontmatter con `name`, `description`, `allowed-tools: [Bash, Read]`. +- `dist/.gemini/skills/straymark-audit-prompt/SKILL.md` — frontmatter sin `allowed-tools`. +- `dist/.agent/workflows/straymark-audit-prompt.md` — frontmatter con solo `description`. + +**Argumentos:** `CHARTER-ID` posicional (mismas reglas de resolución que `charter status`). + +**Comportamiento:** + +1. Verifica que existe el Charter y está en status `in-progress` o `declared` (no `closed`). Si está `closed`, advierte y sale con código 0 — auditar un Charter ya cerrado es válido pero atípico. +2. Ejecuta `straymark charter audit ` (paso PREPARE). El CLI escribe los 2 prompts. +3. Lee `audit/charters//prompts/auditor-primary.prompt.md` y `auditor-secondary.prompt.md`. +4. Imprime en la conversación, con bloques de código separados, los 2 prompts completos. +5. Imprime guidance corta: qué familias de modelos usar (recomendación de heterogeneidad inter-familia, igual que CLI-REFERENCE §5.2 del roadmap), dónde guardar las respuestas (paths canónicos), y cómo regresar (`/straymark-audit-review CHARTER-XX`). + +**No hace:** invocar APIs, decidir el modelo del operador, validar nada (eso lo hace `audit-review`). + +**Ejemplo de salida (en la conversación del agente):** + +``` +> /straymark-audit-prompt CHARTER-04 + +✔ Resolved CHARTER-04 (in-progress) → audit/charters/CHARTER-04/prompts/ + +═══════════════════ AUDITOR PRIMARY PROMPT ═══════════════════ +[contenido del prompt resuelto, ~150-200 líneas] +══════════════════════════════════════════════════════════════ + +═══════════════════ AUDITOR SECONDARY PROMPT ═════════════════ +[contenido del prompt resuelto, ~130-150 líneas] +══════════════════════════════════════════════════════════════ + +Next steps: + 1. Run AUDITOR PRIMARY PROMPT in a model of family A + (e.g., Anthropic — claude-sonnet-4-6). + 2. Run AUDITOR SECONDARY PROMPT in a model of family B + (e.g., Google — gemini-2.5-pro). DO NOT use the same family + for both — see audit-prompts/auditor-primary.md §heterogeneity. + 3. Save responses to: + audit/charters/CHARTER-04/auditor-primary.md + audit/charters/CHARTER-04/auditor-secondary.md + 4. Return with: /straymark-audit-review CHARTER-04 +``` + +### 3.2 `straymark-audit-review` + +**Naming, distribución, argumentos:** análogos a `straymark-audit-prompt`. + +**Comportamiento:** + +1. Verifica que existen `audit/charters//auditor-primary.md` y `auditor-secondary.md` (las respuestas del operador). Si falta alguno, error con instrucción de invocar `straymark-audit-prompt` primero. +2. Ejecuta `straymark charter audit --calibrate`. El CLI valida los 2 outputs contra `audit-output.schema.v0.json` y escribe `prompts/calibrator-reconciler.prompt.md`. +3. Lee el calibrator prompt resuelto e **invoca al agente principal de la conversación** (Claude/Gemini/etc.) para producir el calibrator response. Esta es una diferencia importante con `straymark-audit-prompt`: aquí el calibrator SÍ corre dentro del agente principal, porque la heterogeneidad inter-familia solo importa para el par auditor (ver `straymark-cli-roadmap.md` §5.2 — el calibrador puede ser de cualquier familia incluyendo la del implementador). +4. Escribe `audit/charters//calibrator-reconciler.md` con el response. +5. Ejecuta `straymark charter audit --finalize`. El CLI valida los 3 outputs e imprime el YAML para `external_audit`. +6. **Auto-mergea** el YAML en `.straymark/charters/.telemetry.yaml`: + - Si la telemetría no existe todavía (Charter aún no cerrado vía `charter close`), la skill **no la crea** — solo escribe `audit/charters//external-audit-pending.yaml` con el bloque listo, y deja un mensaje al developer: "Run `straymark charter close CHARTER-XX` first; the audit findings will be auto-merged at close time" (ver §3.3 sobre la integración con close). + - Si la telemetría existe y ya tiene `external_audit:` poblado (re-audit), la skill **append** al array (no reemplaza), preservando histórico. + - Si la telemetría existe sin `external_audit:`, inserta el campo con el array nuevo. +7. Imprime resumen al developer: cuántos findings totales, cuántos por categoría, dónde quedó el calibrator analysis, y dónde se mergeó la telemetría (con sugerencia de `git diff` para revisar). + +**Ejemplo de salida:** + +``` +> /straymark-audit-review CHARTER-04 + +✔ Validated audit/charters/CHARTER-04/auditor-primary.md (5 findings) +✔ Validated audit/charters/CHARTER-04/auditor-secondary.md (4 findings) +✔ Wrote audit/charters/CHARTER-04/prompts/calibrator-reconciler.prompt.md +✔ Generated audit/charters/CHARTER-04/calibrator-reconciler.md + (calibrator: claude-opus-4-7, 8 findings consolidated: + agreed=3, disputed=2, unique_primary=1, unique_secondary=1, rejected=1) +✔ Merged external_audit array into + .straymark/charters/CHARTER-04.telemetry.yaml + + Run `git diff .straymark/charters/CHARTER-04.telemetry.yaml` + to review the merge before commit. +``` + +### 3.3 Integración opcional con `charter close` + +`charter close` se mantiene **agnóstico** del audit (decisión D2). Pero como el flujo natural es `audit-prompt` → `audit-review` → `charter close`, hay un caso (§3.2 paso 6) donde la skill audit-review se ejecuta antes de close y debe diferir el merge. La propuesta: + +- Si `audit-review` corre antes de close: deja `audit/charters//external-audit-pending.yaml` listo. +- `charter close` (sin cambios al CLI Rust en este PR) no lo lee. El operador, al cerrar interactivamente, copiará el bloque manualmente al campo `external_audit:` cuando llegue el prompt correspondiente — exactamente igual que hoy con la salida de FINALIZE. +- En un PR futuro **opcional** (no parte de este scope), `charter close` podría leer `external-audit-pending.yaml` automáticamente y pre-poblar el campo en el flujo interactivo. Queda fuera de v0 hasta validar que el patrón se usa. + +## 4. Lógica del checkpoint + +### 4.1 Cuándo el agente debe proponerlo + +El checkpoint **no es una skill que el developer invoque**. Es guidance al agente principal (Claude Code, Gemini Code, Cursor, etc.) sobre cuándo proponerlo proactivamente. La sección se agrega a `dist/.straymark/00-governance/AGENT-RULES.md` con un trigger claro. + +**Trigger:** el agente debe proponer el checkpoint cuando, en el contexto de implementación de un Charter, **simultáneamente**: + +1. El Charter está en status `in-progress` o `declared`. +2. Todas las tasks del Charter están marcadas como `[x]` (completadas) o el agente acaba de completar la última. +3. `straymark charter drift CHARTER-XX` produce exit 0 (sin drift inacontabilizado). +4. El developer aún **no** ha invocado `straymark charter close` ni mencionado intención de cerrar. + +Si los 4 se cumplen, el agente emite un mensaje de checkpoint **una sola vez** por Charter (no repite en cada turno). + +### 4.2 Forma de la recomendación Sí/No + +El agente debe redactar la recomendación como **opinión informada**, no como pregunta neutra. La forma: + +``` +Llegamos al checkpoint del Charter CHARTER-XX. Está implementado, drift OK, pendiente solo charter close. + +En este punto puedes correr una auditoría externa (típicamente 2 modelos +de familias distintas + un calibrador) que arroje findings cross-modelo +sobre la implementación. + +Mi recomendación: [SÍ / NO], porque: + - [razón concreta basada en el Charter actual] + +Si decides hacerla: ejecuta /straymark-audit-prompt CHARTER-XX y te +imprimo aquí mismo los 2 prompts. Cuando regreses con las respuestas +del operador externo, ejecuta /straymark-audit-review CHARTER-XX y yo +calibro + mergeo en la telemetría. + +Si decides no auditar: continúa con straymark charter close CHARTER-XX +cuando estés listo. La auditoría es completamente opcional — el +Charter declarado + drift check + AILOG dan suficiente disciplina +para cierre confiable sin auditoría externa. +``` + +### 4.3 Heurísticas para la recomendación SÍ/NO + +`AGENT-RULES.md` debe codificar heurísticas, no reglas rígidas (principio #6: el agente está cerca del contexto, sus heurísticas se afinan con el adoptante). Las iniciales: + +**Recomienda SÍ cuando** (cualquiera basta): + +- El Charter tocó superficie crítica de seguridad (auth, RLS, secret handling, IAM). +- El Charter introdujo un componente nuevo (no refactor) que el developer no había co-implementado antes. +- Algún AILOG asociado documenta un R con confidence `low` o `medium` y `risk_level` ≥ `medium`. +- El developer marcó el Charter como `effort_estimate: L` y es el primer Charter del adoptante. +- El developer **explícitamente pidió validación cross-modelo** en el trigger del Charter. +- **Señal estructural de complejidad** *(disponible cuando el CLI fue compilado con el feature `analyze` activo — true en los binarios oficiales descargados vía `straymark update-cli`)*: el diff del Charter introduce o modifica al menos una función cuya cognitive complexity supera **2× el threshold configurado** en `.straymark/config.yml` (`complexity.threshold`, default `8` → ≥ `17`). Una función densa nueva es exactamente el caso donde dos auditores cross-modelo capturan implementation gaps que un solo modelo deja pasar. El cómputo se hace invocando la lógica que ya alimenta `straymark analyze` (`cli/src/analysis_engine.rs`) sobre el subset de archivos modificados en `range`. **Graceful-degradation:** si la skill detecta que el binario actual fue compilado sin `analyze` (caso 1% — adoptante en CI ligero, governance-only, target no-oficial, supply-chain audit, lenguaje no soportado), salta esta heurística silenciosamente y evalúa solo las anteriores — no falla, no warning, no menciona la ausencia. El feature flag `analyze` se mantiene como `default = true` precisamente para que esta rama sea improbable en práctica. + +**Recomienda NO cuando** (todas): + +- El Charter es refactor o documentación (no introduce comportamiento nuevo). +- `effort_estimate` ≤ `S`. +- AILOGs asociados confidence `high` y sin R emergentes. +- `risk_level` del Charter ≤ `low`. + +**Caso default (ninguno claro):** recomienda NO con justificación neutra ("no veo señal específica que justifique el costo de 2-3 modelos adicionales; cierra cuando estés listo"). Esto evita inflar el costo del adoptante por inercia. + +### 4.4 Lo que el checkpoint **no** hace + +- No bloquea ninguna acción del developer. +- No vuelve a aparecer si el developer dijo "no auditar" — el agente recuerda la decisión por el resto del Charter. +- No cuenta hacia métricas de calidad: no hay un KPI "% Charters auditados" en `straymark metrics` (D2 — la auditoría es señal adicional, no requisito). + +## 5. Coexistencia CLI ↔ Skills + +| Caso de uso | Herramienta indicada | +|---|---| +| Developer trabajando en IDE con agente activo, finaliza Charter | Skills `/straymark-audit-prompt` + `/straymark-audit-review` | +| CI / batch / script sin agente IDE-side | CLI directo: `straymark charter audit` (PREPARE/CALIBRATE/FINALIZE) | +| Adoptante sin presupuesto para audit | Ninguna — `charter close` directo, audit es opcional | +| Re-auditoría de un Charter ya cerrado (post-incident review) | Skills funcionan también en Charters `closed`; auto-merge hace `append` al array | +| Adoptante quiere usar solo CLI (no skills, no agente) | El CLI sigue siendo standalone; las skills son layer adicional | + +Las skills son sugaring; el CLI es la base. Quitar las skills no rompe nada. Esta es la propiedad arquitectónica que mantiene principio #10. + +## 6. Documentación a actualizar + +| Archivo | Cambio | +|---|---| +| `dist/.straymark/00-governance/AGENT-RULES.md` (EN + ES + zh-CN) | Nueva sección "Audit checkpoint" con triggers (§4.1), forma del mensaje (§4.2), heurísticas SÍ/NO (§4.3). | +| `docs/adopters/WORKFLOWS.md` (EN + ES + zh-CN) | Diagrama del loop incluye el checkpoint (entre drift y close), con nota de que es opt-in. | +| `docs/adopters/CLI-REFERENCE.md` (EN + ES + zh-CN) | Nueva sección `## Skills` (paralela a `## Commands`) listando los 9 skills (7 actuales + 2 nuevos). Para cada skill: nombre, propósito, ejemplo de invocación, archivos que produce. La sección `### straymark charter audit` (CLI) gana un párrafo "Skill alternative" referenciando los nuevos skills. | +| `dist/.straymark/00-governance/QUICK-REFERENCE.md` (EN + ES + zh-CN) | Tabla de skills agrega 2 filas. | +| `dist/.straymark/00-governance/DOCUMENTATION-POLICY.md` | Sin cambios — el campo `external_audit` ya está en la policy. | +| `docs/adopters/ADOPTION-GUIDE.md` (EN + ES + zh-CN) | Sección "Daily loop" menciona el checkpoint. Sección "External audit (optional)" expande sobre cuándo y cómo. | +| `dist/STRAYMARK.md` | Sin cambios — STRAYMARK.md es minimal y no cubre Phase 3. | +| `README.md` (EN + ES + zh-CN) | Tabla de comandos no cambia (skills no van ahí). Tabla de skills (si existe) gana 2 filas; si no existe, sección breve. | +| `CHANGELOG.md` | `## Framework X.Y.Z` con `### Added`: dos nuevas skills + nuevo checkpoint en AGENT-RULES.md. `## CLI X.Y.Z` solo si la skill `straymark-audit-review` requiere ajustes en cómo el CLI imprime el FINALIZE (parser-friendly), lo cual es probable pero menor. | +| `Propuesta/straymark-cli-roadmap.md` | Nueva entrada en §0 ("Releases shipped") cuando aterrice. Si la implementación cierra el gap §5.5 que diferimos a v1, marcarlo. | + +## 7. Plan de implementación (PRs ordenados) + +| # | Título | Critical path | Estimación | Tipo | +|---|---|---|---|---| +| 1 | Skill `straymark-audit-prompt` (3 plataformas) + plantillas verificadas | sí | 4-6 h | framework + tests | +| 2 | Skill `straymark-audit-review` (3 plataformas) — incluye lógica de merge YAML | sí | 8-10 h | framework + tests | +| 3 | Checkpoint guidance en `AGENT-RULES.md` (3 langs) + tests de fixture en `cli/tests/` que verifican que la sección existe | sí | 3-4 h | governance | +| 4 | Documentación adopter — `WORKFLOWS.md`, `CLI-REFERENCE.md`, `ADOPTION-GUIDE.md`, `QUICK-REFERENCE.md`, `README.md` (3 langs cada uno) | no (paralelizable) | 5-7 h | docs | +| 5 | Bump `fw-X.Y.Z` (minor: nuevas skills + nueva guidance) y `cli-X.Y.Z` solo si PR 2 requiere ajustes al CLI; CHANGELOG; tag release | sí | 1 h | release | + +Total: ~21-28 h focused; 1.5-2 semanas con dependencias de revisor. PR 1-3 son secuenciales; PR 4 puede empezar en paralelo después de que PR 3 estabilice el shape. + +## 8. Riesgos + +**R1 — Drift entre plantilla CLI y skill.** Si por alguna razón un futuro PR modifica las plantillas en `dist/.straymark/audit-prompts/` y la skill las sobre-procesa por separado, los outputs divergen. *Mitigación (D1):* la skill **no procesa** plantillas; lee los archivos resueltos que el CLI escribe. Drift estructuralmente imposible. + +**R2 — El checkpoint inflama costo del adoptante.** Un agente eager-to-help que recomienda SÍ siempre, multiplica el gasto en LLMs. *Mitigación (§4.3):* las heurísticas tienen "default NO" cuando ninguna señal es clara, y el mensaje es explícito sobre el costo. Validar en el primer ciclo de adoptante de frontend que el agente no esté sobre-recomendando. + +**R3 — Los IDEs no honran el trigger del checkpoint.** El agente solo emite el checkpoint cuando los 4 triggers se cumplen, pero no todos los runtime de IDE inspeccionan los archivos antes de cada turno. *Mitigación:* el checkpoint también puede invocarse manualmente como `/straymark-audit-checkpoint CHARTER-XX` (skill no incluida en este v0; queda como fallback a explorar si hace falta). + +**R4 — Auto-merge falla en YAML mal-formado.** La telemetría existente puede tener el campo `external_audit:` con sintaxis inesperada. *Mitigación:* la skill valida el YAML antes de mergear, falla con error explícito si no parsea, y deja `external-audit-pending.yaml` para merge manual. Nunca destruye datos. + +**R5 — El operador olvida regresar con `/straymark-audit-review`.** El flujo se queda colgado: prompts generados, respuestas pegadas, calibrator nunca corre. *Mitigación:* el checkpoint mensaje incluye instrucciones explícitas sobre el regreso; `straymark charter status` (en un PR futuro opcional) podría detectar la presencia de `auditor-*.md` sin `calibrator-reconciler.md` y advertir al developer la próxima vez que consulte el Charter. + +**R6 — Sentinel no es un buen proxy para validar las heurísticas.** Sentinel es Go-backend; las heurísticas de "tocó auth/RLS/IAM" pueden no aplicar a otros stacks. *Mitigación:* el ciclo frontend es exactamente el N=2 que valida si las heurísticas del checkpoint son inter-stack. Mantenerse en v0 experimental hasta entonces. + +## 9. Lo que NO está en este v0 + +- **No hay skill `straymark-audit-checkpoint`.** El checkpoint es guidance al agente, no comando del developer. Si los IDEs no honran el trigger, se reconsidera (R3). +- **No hay enforcement en `charter close`.** Decisión D2, cristalizada permanentemente. +- **No hay invocación automática del CLI desde la skill en un loop.** La skill ejecuta el CLI vía Bash y lee outputs; no hay daemon, no hay watcher, no hay polling. +- **No hay traducción i18n del calibrator response.** El calibrator response queda en el idioma que el agente principal use; las plantillas de auditor-prompts están en EN canónico (igual que hoy). +- **No hay métricas en `straymark metrics` sobre audit coverage.** Por D2: no convertir audit en KPI elimina el incentivo a inflar el conteo. +- **No hay charter audit-review para AILOGs sueltos** (sin Charter). El alcance es estrictamente Charter-bound. Auditar AILOGs sin Charter queda como fricción a observar antes de extender el patrón. +- **No se integra arborist más allá del checkpoint.** Hoy `arborist-metrics` (vía feature `analyze`) solo alimenta `straymark analyze` y, con esta propuesta, una heurística opcional del checkpoint en §4.3. **Hay potencial mucho mayor reconocido pero fuera de scope:** (a) campo `agent_quality.complexity_delta` en `charter-telemetry.schema` poblado automáticamente por `charter close`, (b) warning en `validate --include-charters` cuando un Charter cierra con funciones que cruzaron `2× threshold` sin un AILOG explicando, (c) métricas longitudinales en `straymark metrics` (cómo evoluciona la complejidad del proyecto a lo largo de Charters cerrados), (d) sección "Code complexity surface" auto-generada en el Charter al usar `--from-spec` o `--from-ailog`. Cada una abre superficie de schema que requiere su propia validación empírica antes de cristalizar — quedan como propuestas separadas para ciclos posteriores cuando el adoptante de segundo dominio (frontend) aporte señal sobre qué métricas son útiles inter-stack. + +## 10. Criterios de salida v0 → v1 + +Para cristalizar este patrón a v1 estable (siguiendo principio #12, paralelo al §0 del roadmap): + +- Al menos 1 ciclo completo de `straymark-audit-prompt` + `straymark-audit-review` ejecutado en el adoptante de segundo dominio (frontend) con findings cross-modelo consistentes con la calibración observada en Sentinel. +- El checkpoint emitido al menos 3 veces, con la decisión SÍ/NO del developer alineada con la heurística en al menos 2/3 (señal de que la heurística es útil, no ruido). +- Cero pérdida de datos por auto-merge fallido (R4). +- 0 issues abiertas en GitHub atribuibles a desincronización CLI ↔ skill. + +Si alguno falla, el cycle siguiente del roadmap reabre el diseño antes de promover a v1. + +--- + +*v0.2 corresponde al estado post-Fase-1 (release `fw-4.8.0` / `cli-3.9.0`). La cristalización a v1 sigue gated en el segundo dominio (adoptante de frontend) y en la data de Fase 2. La sección 2 (decisiones D1/D2/D3) se mantiene estable — D2 en particular es decisión definitiva que no se revisa en futuros ciclos. La próxima versión (0.3) se escribirá al cerrar Fase 2 con la data acumulada y la decisión de §9 promote/defer/discard por gap.* diff --git a/docs/decisions/proposals/2026-05-03-audit-skills-rollout.md b/docs/decisions/proposals/2026-05-03-audit-skills-rollout.md new file mode 100644 index 0000000..065d23c --- /dev/null +++ b/docs/decisions/proposals/2026-05-03-audit-skills-rollout.md @@ -0,0 +1,345 @@ +# Plan de implementación — StrayMark audit skills + checkpoint + +**Versión:** 0.2 (Fase 1 cerrada el 3 de mayo de 2026 con la release `fw-4.8.0` / `cli-3.9.0`; Fase 2 abierta — recolección de telemetría operativa) +**Fecha:** 3 de mayo de 2026 +**Autor:** Jose Villaseñor Montfort — StrangeDaysTech +**Propósito:** Operacionalizar `straymark-audit-skills.md` v0.2 — aterrizar las 2 skills + checkpoint guidance en releases concretas, definir las condiciones de cierre por fase, y especificar la telemetría que se recaba durante el rollout para informar las decisiones de §9 (qué de la integración mayor de arborist se promueve a propuesta propia y qué se descarta). +**Documento padre:** `Propuesta/straymark-audit-skills.md` v0.2 (este plan no repite el diseño; lo asume). +**Documentos relacionados:** `Propuesta/straymark-cli-roadmap.md` v0.3 (gating de cristalización v0 → v1), `Propuesta/straymark-charter-telemetry.md` v0.3 (schema actual de telemetría). + +--- + +## 0. Estructura del rollout + +| Fase | Objetivo | Duración | Releases | Estado | +|---|---|---|---|---| +| 1 — Core implementation | Aterrizar las 2 skills + checkpoint en `fw-X.Y.Z` | 1.5–2 sem focused | 1 minor framework + posible patch CLI | ✅ **cerrada** (3 de mayo de 2026 — `fw-4.8.0` / `cli-3.9.0` shippeada en 1 día con 5 PRs) | +| 2 — Recolección de telemetría | Operar las skills en Sentinel + adoptante de frontend, recabar señal sobre uso real | 6–10 ciclos de Charter (~2-3 meses calendar) | sin releases (solo logs) | 🟡 **abierta** desde el cierre de Fase 1 | +| 3 — Decisiones §9 | Evaluar la data acumulada y decidir qué de los 4 gaps de §9 se promueve a propuesta propia | 1 sem de análisis | release subsiguiente solo si algo se promueve | ⬜ pendiente — gated en §2.4 | + +Las fases son secuenciales para Fase 1 → Fase 2; Fase 3 puede ejecutarse parcialmente cuando haya señal suficiente sin esperar el N=10 (early-stop si la señal ya es clara). + +**Cierre de Fase 1 (3 de mayo de 2026):** las 5 PRs (#96, #97, #98, #99, #100) mergeadas el mismo día. Tags `fw-4.8.0` y `cli-3.9.0` push, release workflows ejecutados. Adoptantes obtienen el flujo nuevo via `straymark update-framework` / `straymark update-cli`. Detalle por PR en `straymark-audit-skills.md` §0. + +--- + +## 1. Fase 1 — Core implementation + +### 1.1 Secuencia de PRs + +Hereda `straymark-audit-skills.md` §7 con verificación concreta por PR. + +**PR 1 — Skill `straymark-audit-prompt` (3 plataformas) + tests** + +Archivos a crear: +- `dist/.claude/skills/straymark-audit-prompt/SKILL.md` +- `dist/.gemini/skills/straymark-audit-prompt/SKILL.md` +- `dist/.agent/workflows/straymark-audit-prompt.md` + +Verificación operativa (ejecutar antes de mergear): + +```bash +# El skill no rompe la instalación +cargo install --path cli/ +straymark init /tmp/test-audit-prompt +ls /tmp/test-audit-prompt/.claude/skills/straymark-audit-prompt/SKILL.md +ls /tmp/test-audit-prompt/.gemini/skills/straymark-audit-prompt/SKILL.md +ls /tmp/test-audit-prompt/.agent/workflows/straymark-audit-prompt.md + +# El skill produce un Charter ejercitable +cd /tmp/test-audit-prompt +straymark charter new --type M --title "test audit-prompt" +# (simular invocación de skill manualmente — leer SKILL.md y seguir instrucciones) +# Verificar que el `cargo run -- charter audit CHARTER-01` se ejecuta limpio +``` + +Test fixture en `cli/tests/audit_skill_test.rs`: verificar que el archivo de skill existe en el manifest y se copia tras `init`. + +Condición de cierre PR 1: +- 3 archivos de skill creados. +- Test fixture verde. +- `dist-manifest.yml` no requiere cambios (las 3 carpetas ya están listadas). +- CHANGELOG.md `### Added (Framework)` sumado. + +**PR 2 — Skill `straymark-audit-review` (3 plataformas) + auto-merge YAML + tests** + +Archivos a crear: análogo a PR 1 (3 SKILL.md). + +Lógica clave en el cuerpo del skill (descrita en `straymark-audit-skills.md` §3.2): +1. Verificar `audit/charters//auditor-{primary,secondary}.md` existen. +2. Ejecutar `straymark charter audit --calibrate`. +3. Generar calibrator response usando el agente principal. +4. Ejecutar `straymark charter audit --finalize`. +5. **Mergear** YAML en `.straymark/charters/.telemetry.yaml`. + +Verificación operativa: + +```bash +# Flujo end-to-end con responses fixtures +cd /tmp/test-audit-prompt +straymark charter audit CHARTER-01 # PREPARE +cp tests/fixtures/auditor-primary.md audit/charters/CHARTER-01/ +cp tests/fixtures/auditor-secondary.md audit/charters/CHARTER-01/ +# (simular invocación de straymark-audit-review manualmente) +# Resultado esperado: calibrator-reconciler.md generado, telemetry.yaml mergeado +test -f audit/charters/CHARTER-01/calibrator-reconciler.md +grep -A5 'external_audit:' .straymark/charters/CHARTER-01.telemetry.yaml +``` + +**El auto-merge requiere ajustes al CLI** (probable patch `cli-3.8.2` o `cli-3.9.0`): +- Hoy `--finalize` solo imprime el YAML a stdout. Para que la skill pueda mergearlo confiablemente, conviene un flag `--finalize --emit-json` que estructure la salida como JSON parseable, o un flag `--finalize --merge-into ` que el CLI haga directamente el merge (más limpio — la skill solo invoca, no parsea). +- Decisión recomendada: agregar `--merge-into` al CLI en este mismo PR. Mantiene el patrón "CLI orquesta, skill UX inline". + +Condición de cierre PR 2: +- 3 archivos de skill creados. +- Patch del CLI con `--merge-into` (si se acuerda esa ruta). +- Test integration end-to-end con fixture en `cli/tests/audit_review_e2e_test.rs`. +- CHANGELOG.md `### Added (CLI)` y `### Added (Framework)`. + +**PR 3 — Checkpoint guidance en `AGENT-RULES.md` (3 langs) + tests de fixture** + +Archivos a editar: +- `dist/.straymark/00-governance/AGENT-RULES.md` (EN canónico) +- `dist/.straymark/00-governance/i18n/es/AGENT-RULES.md` +- `dist/.straymark/00-governance/i18n/zh-CN/AGENT-RULES.md` + +Sección nueva con título "Audit checkpoint" que codifica: +- Los 4 triggers booleanos (in-progress + tasks done + drift OK + close no invocado). +- Forma del mensaje SÍ/NO (texto literal a usar por el agente). +- Heurísticas SÍ/NO de §4.3 incluyendo la complejidad arborist con graceful-degradation. +- Reglas: emit una sola vez por Charter, recordar decisión del developer. + +Verificación: + +```bash +# La sección existe en las 3 langs +for lang in '' 'i18n/es/' 'i18n/zh-CN/'; do + grep -c '^## Audit checkpoint\|^## 审计检查点\|^## Checkpoint de auditoría' \ + dist/.straymark/00-governance/${lang}AGENT-RULES.md +done +# Cada uno debe reportar 1 +``` + +Test fixture en `cli/tests/governance_test.rs`: post-`init` la sección existe en cada `AGENT-RULES.md`. + +Condición de cierre PR 3: +- 3 archivos editados con paridad estructural. +- Test verde. +- `release-framework.yml` versionado en footers. + +**PR 4 — Documentación adopter (paralelo a PR 3, no critical-path)** + +Archivos a editar (cada uno × 3 langs): +- `docs/adopters/WORKFLOWS.md` — diagrama del loop incluye checkpoint. +- `docs/adopters/CLI-REFERENCE.md` — nueva sección `## Skills` listando los 9 skills (7 + 2 nuevos), con ejemplo de invocación y archivos producidos por cada uno. La sección `### straymark charter audit` (CLI) gana párrafo "Skill alternative". +- `docs/adopters/ADOPTION-GUIDE.md` — sección "External audit (optional)". +- `dist/.straymark/00-governance/QUICK-REFERENCE.md` — tabla de skills +2 filas. +- `README.md` — solo si la tabla de skills existe en el README. + +Verificación: + +```bash +for lang in '' 'i18n/es/' 'i18n/zh-CN/'; do + echo "=== ${lang:-en} ===" + grep -c 'straymark-audit-prompt\|straymark-audit-review' \ + docs/${lang}adopters/CLI-REFERENCE.md +done +# Cada uno debe reportar ≥ 2 +``` + +Condición de cierre PR 4: +- 9 archivos editados (3 docs × 3 langs). +- Paridad estructural verificada (las 3 langs documentan los mismos skills). +- Sin breaking changes en links existentes. + +**PR 5 — Bump versión + CHANGELOG + tag release** + +Decisión de bump: +- `fw-X.Y.0` (minor — nuevas skills + nueva guidance en governance). +- `cli-X.Y.0` (minor) **solo si PR 2 incluyó el flag `--merge-into`**. Si la skill parsea el stdout actual en su lugar, no hay bump CLI. + +Procedimiento estándar (`CLAUDE.md` Release Workflow). Tag release. Verificar que los 4 binarios oficiales se publican y que `straymark update-framework` baja el nuevo fw. + +### 1.2 Estimación + +5 PRs × ~3-6 h = 21-28 h focused. Calendarizable en 2 semanas con ciclos de revisión. + +PR 1, 2, 3 son secuenciales (PR 2 depende de la decisión de schema en PR 1; PR 3 puede arrancar en paralelo con PR 2 desde su rama). + +PR 4 puede arrancar tras PR 3 estabilizar el shape de los skills y el wording del checkpoint. PR 5 cierra la fase. + +### 1.3 Condiciones de cierre Fase 1 + +- ✅ Los 5 PRs mergeados a main, tag release publicado. *Cumplido — PRs #96, #97, #98, #99, #100 mergeados el 3 de mayo de 2026; tags `fw-4.8.0` y `cli-3.9.0` pushed; release workflows ejecutados.* +- ✅ Las 3 langs en paridad estructural (sección AGENT-RULES + skills documentation + WORKFLOWS). *Cumplido — verificado por el test fixture `cli/tests/checkpoint_guidance_test.rs::audit_checkpoint_section_three_langs_share_load_bearing_anchors` y por inspección visual en PR #98 + #99.* +- ✅ Verificación end-to-end ejecutada en un proyecto sandbox: crear Charter, invocar `straymark-audit-prompt` simulado, pegar respuestas fixture, invocar `straymark-audit-review` simulado, verificar telemetry mergeada. *Cumplido — el test integration `cli/tests/charter_audit_test.rs::audit_merge_into_appends_external_audit_to_telemetry` ejercita el flujo completo (PREPARE → fixtures de auditor → CALIBRATE → fixture de calibrator → FINALIZE --merge-into → assertion sobre telemetry mergeada con indent 2, ambos auditores presentes, charter id real, keys pre-existentes preservadas).* +- ✅ 0 issues abiertas en GitHub atribuibles al rollout. *Cumplido al momento del cierre.* +- ✅ `straymark-audit-skills.md` v0.1 → v0.2: §0 nuevo "Estado de implementación" con la release shippeada (mismo patrón que `straymark-cli-roadmap.md` §0). *Cumplido en este mismo bump — ver `straymark-audit-skills.md` §0.* + +**Nota de cierre:** Fase 1 ejecutada en 1 día calendar (5 PRs secuenciales el 3 de mayo de 2026), substancialmente más rápido que la estimación de 1.5-2 semanas focused. El throughput se debe a que el diseño en `straymark-audit-skills.md` ya tenía las decisiones cristalizadas (D1/D2/D3) y la heurística arborist con graceful-degradation explícita — no hubo decisiones pendientes durante la implementación. Sirve como evidencia operativa adicional para principio #6 (cuando la propuesta es bien escrita, la implementación es ejecución, no diseño). + +--- + +## 2. Fase 2 — Recolección de telemetría + +El propósito de esta fase es **acumular evidencia operativa** que informe las decisiones de §9 (qué de la integración mayor de arborist se promueve). Sin un punto explícito de recolección, las decisiones se tomarían por intuición — exactamente lo que principio #12 pretende prevenir. + +### 2.1 Qué se recaba + +Por cada invocación de `straymark-audit-review` (= cada cierre de ciclo audit completo), la skill escribe un registro JSONL append en `.straymark/audit-telemetry/log.jsonl` con shape: + +```json +{ + "schema_version": "v0", + "charter_id": "CHARTER-04", + "charter_status_at_review": "in-progress", + "timestamp": "2026-05-15T14:30:00Z", + "checkpoint": { + "emitted": true, + "recommendation": "yes", + "reasons_fired": ["security_surface", "cog_complexity_2x"], + "developer_decision": "accepted" + }, + "complexity": { + "feature_available": true, + "max_cog_complexity_in_diff": 24, + "files_over_2x_threshold": 2, + "threshold_used": 8 + }, + "diff_size": { + "files_changed": 17, + "lines_added": 542, + "lines_deleted": 88 + }, + "audit": { + "auditor_primary_model": "claude-sonnet-4-6", + "auditor_secondary_model": "gemini-2.5-pro", + "calibrator_model": "claude-opus-4-7", + "findings_total": 8, + "findings_by_category": { + "hallucination": 0, + "implementation_gap": 3, + "real_debt": 4, + "false_positive": 1 + }, + "calibrator_status": { + "agreed": 3, + "disputed": 2, + "unique_primary": 1, + "unique_secondary": 1, + "rejected": 1 + } + }, + "auto_merge": { + "succeeded": true, + "telemetry_path": ".straymark/charters/CHARTER-04.telemetry.yaml" + } +} +``` + +**Campos clave para §9:** + +- `complexity.max_cog_complexity_in_diff` ↔ `audit.findings_by_category.implementation_gap` — establece o refuta la correlación: ¿funciones complejas atraen más implementation gaps? +- `checkpoint.reasons_fired` con `cog_complexity_2x` ↔ `checkpoint.developer_decision` — valida si la heurística de complejidad es predictiva de decisiones SÍ del developer. +- `complexity.feature_available: false` cuenta — cuántos adoptantes corren CLI sin `analyze` activo (informa si forzar el feature haría daño). +- `diff_size.lines_added` ↔ `audit.findings_total` — establece o refuta: ¿los Charters con diff grande (proxy de "el operador no pudo auditar archivo por archivo") se benefician más del audit externo en términos de findings descubiertos? Esta correlación es la evidencia central que justifica o descarta §9(b) — un warning en `validate --include-charters` cuando un Charter grande cierra sin audit. Campo objetivo, derivado de `git diff --stat` sobre el rango, no requiere supervisión humana ni API clients. + +**Anti-objetivo:** este log NO se sube a un servicio externo, NO contiene PII, NO sale del repo del adoptante. Es un artefacto local que **el adoptante consulta voluntariamente** y comparte fragmentos relevantes en el feedback periódico (issues, conversaciones). Honra el principio de StrayMark-as-local-tool. + +### 2.2 Cómo se evita el sesgo de datos + +- **Recolección por defecto**, no opt-in. Si el adoptante quiere desactivar, agrega `audit.telemetry: false` en `.straymark/config.yml` (no se incluye un flag CLI para evitar fricción visible). +- **Sin envío automático**. Si después de N ciclos hace falta evidencia agregada, el operador del adoptante corre `straymark metrics --export-audit-telemetry > audit-telemetry.json` y lo comparte en un issue. La friction de tener que exportar manualmente garantiza intención. +- **Schema explícito** (`audit-telemetry.schema.v0.json` en `dist/.straymark/schemas/`) versionado. Cambios al shape son breaking changes documentados. + +### 2.3 Quién opera Fase 2 + +- **Sentinel** continúa siendo el dominio principal. Cada Charter cerrado vía el nuevo flujo (`straymark-audit-prompt` → `straymark-audit-review`) genera un registro. +- **Adoptante de frontend** (cuando aterrice) genera registros desde el primer Charter. **Crítico para inter-stack:** la heurística de complejidad debe validarse en TypeScript/JavaScript, no solo en Go. +- Cada 2-3 ciclos, el operador exporta el log a un issue de GitHub con el label `audit-telemetry-snapshot`. Eso construye un timeline público auditado (cumple principio #2). + +### 2.4 Métricas de salida Fase 2 + +Fase 2 cierra cuando se cumple **al menos una** de estas condiciones: + +- **Suficiencia cuantitativa.** Acumulados ≥ 8 registros de los cuales ≥ 3 son del adoptante de frontend (no Sentinel). +- **Suficiencia de señal.** La correlación `max_cog_complexity_in_diff` ↔ `implementation_gap_count` es estadísticamente clara (Spearman ρ > 0.5 con p < 0.1) **o** claramente nula (ρ < 0.2 con p < 0.1) — en cualquiera de los dos extremos hay evidencia para decidir. +- **Suficiencia narrativa.** Al menos 2 incidentes operativos donde un campo arborist hubiera sido decisivo (o claramente irrelevante) — convertirlos en mini-postmortems en AILOGs y cerrar la fase con esa evidencia. +- **Hard timeout.** 4 meses calendar tras cierre de Fase 1, independiente de la evidencia. Se entra a Fase 3 con la data que haya, aunque sea inconclusa. + +--- + +## 3. Fase 3 — Decisiones §9 + +### 3.1 Marco de decisión + +Por cada uno de los 4 gaps de `straymark-audit-skills.md` §9, se decide **explícitamente** entre: + +- **Promote** — escribir propuesta dedicada (e.g., `Propuesta/straymark-charter-complexity-delta.md`) y entrar al ciclo de roadmap. +- **Defer** — seguir observando; reabrir cuando una nueva señal lo justifique. +- **Discard** — la data demostró que el gap no aporta valor; queda registrado en este documento como decidido y cerrado. + +La decisión es **separada por gap** — los 4 no se mueven en bloque. + +### 3.2 Criterios concretos por gap + +**(a) Campo `agent_quality.complexity_delta` en charter-telemetry** + +- **Promote si:** existe correlación clara complejidad ↔ findings (§2.4 suficiencia de señal positiva). El campo tiene valor predictivo. +- **Promote si (alternativo):** ≥ 3 incidentes donde el operador habría usado el campo retrospectivamente (e.g., "este Charter fue problemático, ¿qué tan complejo era el código?") y el dato no estaba. +- **Discard si:** correlación clara nula y cero incidentes operativos. + +**(b) Warning en `validate --include-charters` por funciones sobre 2× threshold sin AILOG** + +- **Promote si:** durante Fase 2, el log muestra ≥ 2 casos donde un Charter cerró con `max_cog_complexity_in_diff > 2× threshold` y NO había AILOG referenciando esa complejidad — y al menos 1 de esos 2 produjo finding `real_debt` o `implementation_gap`. +- **Defer si:** los casos existen pero no produjeron findings (la complejidad sin AILOG no fue señal de problema en práctica). +- **Discard si:** durante Fase 2 hubo 0 casos del patrón. + +**(c) Métricas longitudinales en `straymark metrics`** + +- **Promote si:** ≥ 1 adoptante (Sentinel o frontend) reporta haber consultado manualmente la evolución de complejidad y encuentra fricción de no tenerlo en el comando. +- **Defer si:** nadie lo consulta voluntariamente. Las métricas longitudinales solo aportan valor si se miran; no se construye reporting que nadie lee. +- **Discard:** no aplica — la data se acumula gratis vía PR (a) si aterriza, así que "discard" estricto es improbable. + +**(d) Sección "Code complexity surface" auto-generada en `charter new --from-spec/--from-ailog`** + +- **Promote si:** el adoptante de frontend reporta que al crear Charters nuevos, la información de complejidad pre-existente del scope ayuda a estimar effort más realistamente. +- **Defer si:** el adoptante reporta que la sección auto-generada se ignora en práctica (lo borraron del template, no lo leyeron). +- **Discard si:** la sección introdujo sesgo (Charters más estrechos de lo conveniente porque "ese archivo es complejo, no lo toco" — anti-patrón documentado). + +### 3.3 Output de Fase 3 + +Un commit a `Propuesta/` con: + +- **`Propuesta/straymark-audit-skills.md` v0.2** — §9 actualizado para cada gap: estado (promote/defer/discard), evidencia que sostiene la decisión, link a propuesta nueva si aplica. +- **`Propuesta/straymark-audit-skills-implementacion.md` v0.2** — §3 actualizado con la data acumulada y las decisiones tomadas. +- **Si algún gap se promueve:** nueva propuesta dedicada en `Propuesta/straymark-.md` con su propio plan. + +--- + +## 4. Próximos pasos post-cierre + +Cuando Fase 3 cierre: + +1. **Si ningún gap se promueve** — la integración arborist queda como hoy: alimenta `straymark analyze` (standalone) y la heurística opcional del checkpoint en §4.3. Documentar explícitamente en `Propuesta/straymark-audit-skills.md` §9 que se evaluó y se decidió no expandir, con la evidencia. Esta es una decisión legítima — no expandir es respuesta válida. + +2. **Si uno o más gaps se promueven** — cada uno entra al ciclo de roadmap en `Propuesta/straymark-cli-roadmap.md` v0.4 (cuando se escriba) con su propia secuencia de PRs, exit criteria, y subsection en §0 si aplica. + +3. **Cristalización v0 → v1 de las skills mismas** — independiente de §9, las skills `straymark-audit-prompt` y `straymark-audit-review` cumplen su gate de v1 estable cuando satisfacen §10 de la propuesta padre. Eso puede pasar antes, durante, o después de Fase 3 — son ortogonales. + +4. **Evolución del schema de telemetría audit** — `audit-telemetry.schema.v0.json` puede evolucionar a v1 cuando la data acumulada muestre campos faltantes (e.g., tiempo invertido por audit, costo en USD reportado por el adoptante, satisfacción cualitativa). Cualquier cambio breaking incrementa el `schema_version` en cada registro. + +--- + +## 5. Decisiones operativas que NO requieren propuesta + +Algunas evoluciones menores se acuerdan acá y se aplican sin propuesta dedicada: + +- **Ajustes al wording del checkpoint** en `AGENT-RULES.md` (lenguaje, ejemplos, tono): patch directo cuando un adoptante reporta fricción. +- **Tuning de los multiplicadores de la heurística arborist** (hoy `2× threshold`): ajustar a `1.5×` o `3×` si la data de Fase 2 muestra que `2×` produce demasiados/pocos triggers. Cambio mínimo, sin breaking change. +- **Adición de modelos a la tabla de familias** (`dist/.straymark/audit-prompts/model-families.yaml` si se crea — es un follow-up del CLI roadmap §5.2): no requiere propuesta, es housekeeping. +- **Bumps menores del feature `analyze` por upgrades de arborist**: housekeeping. + +--- + +*Este plan es operativo, no exhaustivo. Cualquier desviación material durante implementación (PR que se parte en dos, fase de telemetría que se acelera, decisión §9 que se toma early) se documenta amending este archivo, no creando uno nuevo. v0.2 cierra Fase 1; v0.3 se escribirá al cerrar Fase 2 (recolección de telemetría completada según §2.4); v0.4 al cerrar Fase 3 (decisiones §9 tomadas).* diff --git a/Propuesta/devtrail-cli-roadmap.md b/docs/decisions/proposals/2026-05-03-cli-roadmap.md similarity index 52% rename from Propuesta/devtrail-cli-roadmap.md rename to docs/decisions/proposals/2026-05-03-cli-roadmap.md index 3f96e6d..669b4dc 100644 --- a/Propuesta/devtrail-cli-roadmap.md +++ b/docs/decisions/proposals/2026-05-03-cli-roadmap.md @@ -1,10 +1,10 @@ -# DevTrail CLI — Roadmap hacia la tesis (post-Sentinel) +# StrayMark CLI — Roadmap hacia la tesis (post-Sentinel) **Versión:** 0.3 (post-implementación de las 3 fases — A1 orchestration-only documentada para Fase 3; RFCs #67/#82/#91 cerradas; frictions F1-F8 + observación O3 resueltos; CHARTER-01/02 + AILOG-01 ejemplos shipped en `dist/docs/examples/`) **Fecha:** 3 de mayo de 2026 **Autor:** Jose Villaseñor Montfort — StrangeDaysTech **Propósito:** Traducir los hallazgos validados de Sentinel en una secuencia accionable de cambios al CLI Rust y al framework, manteniendo el principio #12 (cristalización experimental, no estable). -**Documentos relacionados:** `devtrail-thesis-validation.md` (evidencia que justifica el roadmap), `devtrail-design-principles.md` (anotaciones v0.2 sobre #6, #9, #12), `devtrail-cloud-proposal.md` §4.5 y §8 (Charters en Cloud, Q3), `devtrail-charter-telemetry.md` v0.3 (schema de telemetría refinado), `que-es-un-charter.md` (alcance conceptual del artefacto Charter y coexistencia con SpecKit). +**Documentos relacionados:** `straymark-thesis-validation.md` (evidencia que justifica el roadmap), `straymark-design-principles.md` (anotaciones v0.2 sobre #6, #9, #12), `straymark-cloud-proposal.md` §4.5 y §8 (Charters en Cloud, Q3), `straymark-charter-telemetry.md` v0.3 (schema de telemetría refinado), `que-es-un-charter.md` (alcance conceptual del artefacto Charter y coexistencia con SpecKit). --- @@ -31,7 +31,7 @@ Las tres fases del roadmap están shippeadas. El gate de cristalización `v0 → **Diferencias entre §5.5 como escrito y §5.5 como entregado:** -- §5.5 criterio 4 dice "una configuración monocromática es rechazada con error claro; una heterogénea procede sin advertencia". Como shippeado, la heterogeneidad inter-familia es **recomendación documentada** (CLI-REFERENCE.md `devtrail charter audit` section), **no auto-enforcement**. El criterio depende de A1: sin invocación de APIs, el CLI no sabe qué modelo usará el operador, así que no hay punto de inyección donde validar la heterogeneidad. Auto-enforcement queda como gate v1 cuando los HTTP clients se justifiquen. +- §5.5 criterio 4 dice "una configuración monocromática es rechazada con error claro; una heterogénea procede sin advertencia". Como shippeado, la heterogeneidad inter-familia es **recomendación documentada** (CLI-REFERENCE.md `straymark charter audit` section), **no auto-enforcement**. El criterio depende de A1: sin invocación de APIs, el CLI no sabe qué modelo usará el operador, así que no hay punto de inyección donde validar la heterogeneidad. Auto-enforcement queda como gate v1 cuando los HTTP clients se justifiquen. **Items §6 (mapping Sentinel → CLI) shipped:** @@ -39,7 +39,7 @@ Las tres fases del roadmap están shippeadas. El gate de cristalización `v0 → - `dist/docs/examples/charters/CHARTER-02-baseline-recompute.md` (anonimizado de PLAN-06 de Sentinel) — ✅ - `dist/docs/examples/ailogs/AILOG-2026-01-15-001-anomaly-detector-introduction.md` (anonimizado del AILOG originador de CHARTER-01) — ✅ -Estos viven fuera del manifest de `devtrail init` por diseño (decisión A6 del plan original): adopters los browse en GitHub o vía clone, no se auto-instalan como artefactos del framework. +Estos viven fuera del manifest de `straymark init` por diseño (decisión A6 del plan original): adopters los browse en GitHub o vía clone, no se auto-instalan como artefactos del framework. **Open issues a la fecha:** @@ -57,11 +57,11 @@ Estos viven fuera del manifest de `devtrail init` por diseño (decisión A6 del ## 1. Por qué este documento existe -`devtrail-cloud-proposal.md` v0.3 confirma que la tesis se sostiene con la evidencia de Sentinel y nombra qué decisiones la evidencia permite tomar ahora. Este documento traduce esas decisiones en una secuencia concreta de cambios al CLI Rust y al framework `dist/.devtrail/`. No incluye trabajo de Cloud ni features de aprobación condicional — esos quedan bloqueados hasta validación con un segundo proyecto en otro dominio o con flujo multi-actor. +`straymark-cloud-proposal.md` v0.3 confirma que la tesis se sostiene con la evidencia de Sentinel y nombra qué decisiones la evidencia permite tomar ahora. Este documento traduce esas decisiones en una secuencia concreta de cambios al CLI Rust y al framework `dist/.straymark/`. No incluye trabajo de Cloud ni features de aprobación condicional — esos quedan bloqueados hasta validación con un segundo proyecto en otro dominio o con flujo multi-actor. El roadmap está pensado para tres ciclos de release del CLI (estimación: 3-4 patches/minor cada uno) que pueden ejecutarse en serie o con solapamiento mínimo. Cada fase es shippable independientemente y produce señal antes de la siguiente. Si la fase 1 no genera adopción medible, las fases 2-3 se cuestionan antes de invertir. -**Nota terminológica.** Lo que el experimento Sentinel llamó "Plan" (Plans 01-06) se llama **Charter** en el vocabulario DevTrail going-forward, para evitar colisión nominal con `plan.md` de GitHub SpecKit. Los registros históricos de Sentinel preservan "Plan"; este documento usa "Charter" para todo lo prospectivo y "Plan" cuando cita literalmente artefactos de Sentinel. Justificación completa en `que-es-un-charter.md` §2. +**Nota terminológica.** Lo que el experimento Sentinel llamó "Plan" (Plans 01-06) se llama **Charter** en el vocabulario StrayMark going-forward, para evitar colisión nominal con `plan.md` de GitHub SpecKit. Los registros históricos de Sentinel preservan "Plan"; este documento usa "Charter" para todo lo prospectivo y "Plan" cuando cita literalmente artefactos de Sentinel. Justificación completa en `que-es-un-charter.md` §2. ## 2. Secuencia recomendada y justificación @@ -82,49 +82,49 @@ El roadmap está pensado para tres ciclos de release del CLI (estimación: 3-4 p **Objetivo:** que un usuario adoptante pueda crear, listar, navegar y validar Charters usando el CLI, sin tener que copiar manualmente el TEMPLATE de Sentinel. -### 3.1 Cambios al framework (`dist/.devtrail/`) +### 3.1 Cambios al framework (`dist/.straymark/`) -- **Portar `TEMPLATE.md v3`** desde `/E/Proyectos/StrangeDaysTech/sentinel/docs/plans/TEMPLATE.md` a `dist/.devtrail/templates/charter-template.md` con las 6 convenciones embebidas validadas (separación Local/Production checks, esfuerzo en TIEMPO, sub-secciones estructuradas, R, Cierre del Charter, auto-checklist drift). El template renombra "Cierre del Plan" → "Cierre del Charter" en su cuerpo; las referencias del template a Sentinel quedan como ejemplos históricos. -- **Schema mínimo `dist/.devtrail/schemas/charter.schema.v0.json`** marcado *experimental*. Frontmatter mínimo: `charter_id`, `origin` (union: `originating_ailogs` array u `originating_spec` path), `trigger`, `effort_estimate` (XS/S/M/L), `status` (declared/in-progress/closed). El campo `origin` admite ambas formas para soportar tanto el modo Sentinel (Charter nacido de un AILOG) como el modo SpecKit-driver (Charter derivado de un `specs/###-feature/`); ver §3.5 para la justificación. El schema NO se cristaliza como `v1.0` hasta tener un segundo proyecto en otro dominio (ver `devtrail-thesis-validation.md` §6). -- **Charters canónicos como ejemplos** en `dist/docs/examples/charters/` (copia anonimizada de PLAN-05 y PLAN-06 de Sentinel, renombrados a `CHARTER-01` y `CHARTER-02` en los ejemplos para que adoptantes los lean como referencia de uso real bajo el vocabulario DevTrail). +- **Portar `TEMPLATE.md v3`** desde `/E/Proyectos/StrangeDaysTech/sentinel/docs/plans/TEMPLATE.md` a `dist/.straymark/templates/charter-template.md` con las 6 convenciones embebidas validadas (separación Local/Production checks, esfuerzo en TIEMPO, sub-secciones estructuradas, R, Cierre del Charter, auto-checklist drift). El template renombra "Cierre del Plan" → "Cierre del Charter" en su cuerpo; las referencias del template a Sentinel quedan como ejemplos históricos. +- **Schema mínimo `dist/.straymark/schemas/charter.schema.v0.json`** marcado *experimental*. Frontmatter mínimo: `charter_id`, `origin` (union: `originating_ailogs` array u `originating_spec` path), `trigger`, `effort_estimate` (XS/S/M/L), `status` (declared/in-progress/closed). El campo `origin` admite ambas formas para soportar tanto el modo Sentinel (Charter nacido de un AILOG) como el modo SpecKit-driver (Charter derivado de un `specs/###-feature/`); ver §3.5 para la justificación. El schema NO se cristaliza como `v1.0` hasta tener un segundo proyecto en otro dominio (ver `straymark-thesis-validation.md` §6). +- **Charters canónicos como ejemplos** en `dist/docs/examples/charters/` (copia anonimizada de PLAN-05 y PLAN-06 de Sentinel, renombrados a `CHARTER-01` y `CHARTER-02` en los ejemplos para que adoptantes los lean como referencia de uso real bajo el vocabulario StrayMark). ### 3.2 Comandos nuevos del CLI -- `devtrail charter new [--type X|S|M|L] [--from-ailog ID | --from-spec PATH] [--title "..."]` — scaffolds un Charter desde el template. Si `--from-ailog` está presente, pre-popula `originating_ailogs` con el ID (caso post-MVP / mantenimiento, p.ej. los Plans 01-06 históricos de Sentinel). Si `--from-spec` está presente (p.ej. `specs/001-sentinel-mvp/`), pre-popula `originating_spec` apuntando al `spec.md` correspondiente y hereda User Stories relevantes a la sección Context (caso greenfield con SpecKit como driver). Los flags son mutuamente excluyentes; si ambos faltan, el Charter se crea sin origen y debe llenarse manualmente. Genera el archivo en `docs/charters/NN-slug.md` con `NN` autoincrementado. Justificación de los dos modos en §3.5. -- `devtrail charter list [--status declared|in-progress|closed|all]` — enumera Charters en `docs/charters/` con estado, esfuerzo declarado, AILOGs origen. Default: `--status all`. -- `devtrail charter status [CHARTER-ID]` — muestra detalle de un Charter: archivos declarados, AILOGs origen, telemetría si existe, drift-check si existe. Si se omite el ID, lista los últimos 5 Charters. +- `straymark charter new [--type X|S|M|L] [--from-ailog ID | --from-spec PATH] [--title "..."]` — scaffolds un Charter desde el template. Si `--from-ailog` está presente, pre-popula `originating_ailogs` con el ID (caso post-MVP / mantenimiento, p.ej. los Plans 01-06 históricos de Sentinel). Si `--from-spec` está presente (p.ej. `specs/001-sentinel-mvp/`), pre-popula `originating_spec` apuntando al `spec.md` correspondiente y hereda User Stories relevantes a la sección Context (caso greenfield con SpecKit como driver). Los flags son mutuamente excluyentes; si ambos faltan, el Charter se crea sin origen y debe llenarse manualmente. Genera el archivo en `docs/charters/NN-slug.md` con `NN` autoincrementado. Justificación de los dos modos en §3.5. +- `straymark charter list [--status declared|in-progress|closed|all]` — enumera Charters en `docs/charters/` con estado, esfuerzo declarado, AILOGs origen. Default: `--status all`. +- `straymark charter status [CHARTER-ID]` — muestra detalle de un Charter: archivos declarados, AILOGs origen, telemetría si existe, drift-check si existe. Si se omite el ID, lista los últimos 5 Charters. ### 3.3 Integración con comandos existentes -- **`devtrail validate`**: añadir validación opt-in del frontmatter de Charters contra `charter.schema.v0.json` cuando el flag `--include-charters` esté presente (default: false, para no romper proyectos existentes sin Charters). -- **`devtrail explore` (TUI)**: añadir vista `Charters` paralela a `Documents`, con navegación por estado y búsqueda por AILOG origen. Usa `pulldown-cmark` ya disponible. +- **`straymark validate`**: añadir validación opt-in del frontmatter de Charters contra `charter.schema.v0.json` cuando el flag `--include-charters` esté presente (default: false, para no romper proyectos existentes sin Charters). +- **`straymark explore` (TUI)**: añadir vista `Charters` paralela a `Documents`, con navegación por estado y búsqueda por AILOG origen. Usa `pulldown-cmark` ya disponible. ### 3.4 Tests y documentación -- Tests integration en `cli/tests/` que crean un proyecto temporal con `devtrail init`, ejercitan `charter new/list/status` en los tres caminos de origen (`--from-ailog`, `--from-spec` con un `specs/` mock, y sin flag), y verifican el shape del Charter generado contra el schema en cada caso. +- Tests integration en `cli/tests/` que crean un proyecto temporal con `straymark init`, ejercitan `charter new/list/status` en los tres caminos de origen (`--from-ailog`, `--from-spec` con un `specs/` mock, y sin flag), y verifican el shape del Charter generado contra el schema en cada caso. - Sección `## Charters` nueva en `docs/adopters/CLI-REFERENCE.md` (EN + ES + zh-CN) con ejemplos de uso. Plantilla para README. La sección debe incluir una nota corta explicando que en docs históricos de Sentinel y en evidencia empírica del experimento `/plan-audit`, este artefacto aparece bajo el nombre "Plan". ### 3.5 Coexistencia con flujos SpecKit -DevTrail llamó originalmente a este artefacto "Plan" durante el experimento Sentinel; se renombró a **Charter** precisamente para evitar la colisión nominal con `plan.md` de SpecKit, que es un artefacto distinto (feature-completo y arquitectónico, más cercano a un ADR + skeleton de proyecto). El Charter DevTrail es una unidad acotada con verificación ejecutable, declaración de archivos y ancla de auditoría ex-post. No compiten — viven en momentos distintos del ciclo. SpecKit termina al producir `tasks.md`; DevTrail Charter empieza ahí (cuando hay spec previa) o se sostiene solo (cuando no la hay). El alcance conceptual completo y la comparación pieza a pieza viven en `que-es-un-charter.md`. +StrayMark llamó originalmente a este artefacto "Plan" durante el experimento Sentinel; se renombró a **Charter** precisamente para evitar la colisión nominal con `plan.md` de SpecKit, que es un artefacto distinto (feature-completo y arquitectónico, más cercano a un ADR + skeleton de proyecto). El Charter StrayMark es una unidad acotada con verificación ejecutable, declaración de archivos y ancla de auditoría ex-post. No compiten — viven en momentos distintos del ciclo. SpecKit termina al producir `tasks.md`; StrayMark Charter empieza ahí (cuando hay spec previa) o se sostiene solo (cuando no la hay). El alcance conceptual completo y la comparación pieza a pieza viven en `que-es-un-charter.md`. **Tres modos de coexistencia que Fase 1 debe soportar de fábrica:** -1. **Greenfield con SpecKit como driver.** Un Charter DevTrail toma un subconjunto de `tasks.md` (típicamente una user story o una fase) y le añade verificación + drift + audit. Lo cubre el flag `--from-spec PATH` (§3.2): pre-popula `originating_spec` y hereda User Stories al Context. +1. **Greenfield con SpecKit como driver.** Un Charter StrayMark toma un subconjunto de `tasks.md` (típicamente una user story o una fase) y le añade verificación + drift + audit. Lo cubre el flag `--from-spec PATH` (§3.2): pre-popula `originating_spec` y hereda User Stories al Context. 2. **Mantenimiento / post-MVP.** No hay SpecKit upstream — el Charter nace de un AILOG. Es el caso real de Sentinel (Plans 01-06). Lo cubre el flag `--from-ailog ID` (§3.2). -3. **Híbrido.** Features mayores con flujo SpecKit completo + Charters DevTrail; bug fixes, gobernanza, deuda y features chicas con solo Charter DevTrail. Probablemente el más realista en la práctica; no requiere flags adicionales — emerge de combinar los dos modos anteriores según el tipo de trabajo. +3. **Híbrido.** Features mayores con flujo SpecKit completo + Charters StrayMark; bug fixes, gobernanza, deuda y features chicas con solo Charter StrayMark. Probablemente el más realista en la práctica; no requiere flags adicionales — emerge de combinar los dos modos anteriores según el tipo de trabajo. **Implicaciones de diseño:** - `charter.schema.v0.json` (§3.1) declara `origin` como union `originating_ailogs | originating_spec` precisamente para no privilegiar un modo sobre el otro. -- `devtrail validate --include-charters` (§3.3) acepta ambas formas de `origin`; un Charter sin ninguna falla con error explicativo. -- `devtrail charter list` (§3.2) puede agrupar por origen cuando sea útil (p.ej. `devtrail charter list --origin spec` para ver solo Charters derivados de SpecKit). -- La integración con SpecKit es de *lectura* — el CLI DevTrail no genera ni modifica artefactos de SpecKit, solo los referencia. Esto preserva el principio de no acoplar DevTrail a un flujo de planning particular. +- `straymark validate --include-charters` (§3.3) acepta ambas formas de `origin`; un Charter sin ninguna falla con error explicativo. +- `straymark charter list` (§3.2) puede agrupar por origen cuando sea útil (p.ej. `straymark charter list --origin spec` para ver solo Charters derivados de SpecKit). +- La integración con SpecKit es de *lectura* — el CLI StrayMark no genera ni modifica artefactos de SpecKit, solo los referencia. Esto preserva el principio de no acoplar StrayMark a un flujo de planning particular. ### 3.6 Criterios de salida de la Fase 1 -- ✅ `devtrail charter new` genera un Charter compatible con `check-plan-drift.sh` (Sentinel) ejecutado manualmente — la compatibilidad sintáctica se preserva aunque cambien los nombres canónicos en el framework. Se valida en ambos modos (`--from-ailog` y `--from-spec`). *Validado empíricamente por Sentinel CHARTER-02..06.* -- ⏳ Al menos 1 adoptante (idealmente fuera de Go) ha creado un Charter completo con `devtrail charter` y reportado sobre la experiencia. *Sentinel (Go-backend) ha cerrado 6 Charters; el siguiente cycle se realizará en un subproyecto de frontend, abriendo el segundo-dominio.* +- ✅ `straymark charter new` genera un Charter compatible con `check-plan-drift.sh` (Sentinel) ejecutado manualmente — la compatibilidad sintáctica se preserva aunque cambien los nombres canónicos en el framework. Se valida en ambos modos (`--from-ailog` y `--from-spec`). *Validado empíricamente por Sentinel CHARTER-02..06.* +- ⏳ Al menos 1 adoptante (idealmente fuera de Go) ha creado un Charter completo con `straymark charter` y reportado sobre la experiencia. *Sentinel (Go-backend) ha cerrado 6 Charters; el siguiente cycle se realizará en un subproyecto de frontend, abriendo el segundo-dominio.* - ✅ Schema `charter.schema.v0.json` no ha requerido breaking changes en 2 ciclos de release. *Cumplido — 0 breaking changes a través de fw-4.4.0 → fw-4.7.1.* ## 4. Fase 2 — Telemetría y drift-check ejecutable @@ -133,27 +133,27 @@ DevTrail llamó originalmente a este artefacto "Plan" durante el experimento Sen ### 4.1 Cambios al framework -- **Schema `dist/.devtrail/schemas/charter-telemetry.schema.v0.json`** derivado de `devtrail-charter-telemetry.md` v0.2 con los 4 campos refinados por Sentinel: `external_audit` como array, `outcome.scope_change_notes` con codificación `F1...FN`, `agent_quality.r_n_plus_one_emergent_count`, `qualitative.format_iteration`. +- **Schema `dist/.straymark/schemas/charter-telemetry.schema.v0.json`** derivado de `straymark-charter-telemetry.md` v0.2 con los 4 campos refinados por Sentinel: `external_audit` como array, `outcome.scope_change_notes` con codificación `F1...FN`, `agent_quality.r_n_plus_one_emergent_count`, `qualitative.format_iteration`. ### 4.2 Comandos nuevos del CLI -- `devtrail charter close [CHARTER-ID]` — guía interactiva (estilo `git commit` con prompts) para llenar la telemetría YAML al cierre del Charter. Pregunta campo por campo, valida tipos contra schema, escribe el archivo `.devtrail/charters/CHARTER-ID.telemetry.yaml`. Tiempo objetivo del flujo: 5-10 min (mismo target que `devtrail-charter-telemetry.md` declara). -- `devtrail charter drift [CHARTER-ID] [--range REV..REV]` — reimplementación o invocación del `check-plan-drift.sh` de Sentinel. Decisión técnica abierta (principio #9): invocar el script bash directamente desde Rust si está disponible, o reimplementar nativamente preservando la propiedad "0 falsos positivos en 2/2 tests". El usuario *adoptante* no debe percibir diferencia. +- `straymark charter close [CHARTER-ID]` — guía interactiva (estilo `git commit` con prompts) para llenar la telemetría YAML al cierre del Charter. Pregunta campo por campo, valida tipos contra schema, escribe el archivo `.straymark/charters/CHARTER-ID.telemetry.yaml`. Tiempo objetivo del flujo: 5-10 min (mismo target que `straymark-charter-telemetry.md` declara). +- `straymark charter drift [CHARTER-ID] [--range REV..REV]` — reimplementación o invocación del `check-plan-drift.sh` de Sentinel. Decisión técnica abierta (principio #9): invocar el script bash directamente desde Rust si está disponible, o reimplementar nativamente preservando la propiedad "0 falsos positivos en 2/2 tests". El usuario *adoptante* no debe percibir diferencia. ### 4.3 AILOG-awareness para reducir ceremonia -`AILOG-022` §Risk R2 documentó que el script genera ruido cuando alerta sobre R ya documentados en AILOG. La fase 2 debe atacar esa ceremonia (`devtrail-design-principles.md` v0.2 §6 distingue virtud vs ceremonia): +`AILOG-022` §Risk R2 documentó que el script genera ruido cuando alerta sobre R ya documentados en AILOG. La fase 2 debe atacar esa ceremonia (`straymark-design-principles.md` v0.2 §6 distingue virtud vs ceremonia): -- `devtrail charter drift` debe leer los AILOGs referenciados en el frontmatter del Charter y suprimir alertas sobre paths ya documentados como `R` en algún AILOG. Esta es la mitigación R2 que Sentinel propuso pero no implementó. +- `straymark charter drift` debe leer los AILOGs referenciados en el frontmatter del Charter y suprimir alertas sobre paths ya documentados como `R` en algún AILOG. Esta es la mitigación R2 que Sentinel propuso pero no implementó. ### 4.4 Hook opcional pre-PR -- `dist/.devtrail/hooks/pre-pr.sh` que ejecuta `devtrail charter drift` automáticamente antes de abrir un PR. Opt-in via `devtrail init --hooks` o configuración manual. NO es default (principio #6: fricción virtuosa, pero no impuesta sin consentimiento). +- `dist/.straymark/hooks/pre-pr.sh` que ejecuta `straymark charter drift` automáticamente antes de abrir un PR. Opt-in via `straymark init --hooks` o configuración manual. NO es default (principio #6: fricción virtuosa, pero no impuesta sin consentimiento). ### 4.5 Criterios de salida de la Fase 2 -- ⏳ Al menos 2 adoptantes han usado `devtrail charter close` y producido telemetría YAML válida. *Solo Sentinel hasta hoy (6 telemetrías cerradas: CHARTER-01..06). Se cumple cuando un adopter de segundo dominio cierre al menos 1 Charter.* -- ✅ `devtrail charter drift` mantiene la propiedad de 0 falsos positivos en proyectos adoptantes. *Validado empíricamente por Sentinel CHARTER-02..06; el único falso positivo histórico (F3 — regex column-1) se cerró en `fw-4.6.1`.* +- ⏳ Al menos 2 adoptantes han usado `straymark charter close` y producido telemetría YAML válida. *Solo Sentinel hasta hoy (6 telemetrías cerradas: CHARTER-01..06). Se cumple cuando un adopter de segundo dominio cierre al menos 1 Charter.* +- ✅ `straymark charter drift` mantiene la propiedad de 0 falsos positivos en proyectos adoptantes. *Validado empíricamente por Sentinel CHARTER-02..06; el único falso positivo histórico (F3 — regex column-1) se cerró en `fw-4.6.1`.* - ✅ AILOG-awareness reduce el triage manual a cero en al menos 1 caso real reportado. *Validado por Sentinel CHARTER-06 (ver issue #91 para evidencia: drift detectó `subscriber.go` declarado pero no modificado, y la supresión AILOG-aware eliminó el triage manual al 100%).* ## 5. Fase 3 — Auditoría externa multi-modelo @@ -162,11 +162,11 @@ DevTrail llamó originalmente a este artefacto "Plan" durante el experimento Sen ### 5.1 Diseño de tres niveles (no solo "ejecuta N modelos") -`devtrail-thesis-validation.md` §7.3 argumenta que la auditoría dual de Sentinel reveló un patrón de tres niveles: dos auditores en paralelo + un calibrador-reconciliador (claude-analisis) que aplica el schema definicional. La fase 3 implementa esa arquitectura, no una orquestación plana de N modelos. +`straymark-thesis-validation.md` §7.3 argumenta que la auditoría dual de Sentinel reveló un patrón de tres niveles: dos auditores en paralelo + un calibrador-reconciliador (claude-analisis) que aplica el schema definicional. La fase 3 implementa esa arquitectura, no una orquestación plana de N modelos. ### 5.2 Heterogeneidad inter-familia como restricción de diseño -La auditoría externa **no es sustituible por auto-auditoría del mismo modelo**, y la razón no es operativa — es estadística y estructural. El comando `devtrail charter audit` debe imponer la restricción de heterogeneidad inter-familia desde el inicio, no como configuración opcional. +La auditoría externa **no es sustituible por auto-auditoría del mismo modelo**, y la razón no es operativa — es estadística y estructural. El comando `straymark charter audit` debe imponer la restricción de heterogeneidad inter-familia desde el inicio, no como configuración opcional. **Tres bases teóricas que sostienen la restricción:** @@ -176,22 +176,22 @@ La auditoría externa **no es sustituible por auto-auditoría del mismo modelo** 3. **Convergencia inter-modelo como señal estructural.** Lo que Sentinel mostró empíricamente — Copilot 9.25 / Gemini 9.5 convergiendo en PLAN-05 sobre los mismos findings, capturando F4 y F5 que el AILOG no documentó — es que la *diversidad* es estructural, no aditiva. Esa convergencia no se reproduce entre dos auditorías del mismo modelo porque comparten el sesgo. -**El matiz importante: no toda auto-auditoría está descalificada.** Para *checks estructurales* (drift de archivos declarados vs modificados, consistencia interna del Charter, syntax/type checks), un mismo modelo se audita bien — `check-plan-drift.sh` no necesita Gemini para funcionar y la Fase 2 es deliberadamente single-model. Para *checks semánticos* (¿esta arquitectura es correcta?, ¿esta categorización es `hallucination` vs `implementation_gap`?), la heterogeneidad es lo que captura la calibración. La distinción es la misma virtud-vs-ceremonia que `devtrail-design-principles.md` v0.2 §6 articula: la heterogeneidad inter-familia es virtud cuando externaliza signal donde el sesgo es probable; es ceremonia cuando solo agrega latencia y costo en checks estructurales. +**El matiz importante: no toda auto-auditoría está descalificada.** Para *checks estructurales* (drift de archivos declarados vs modificados, consistencia interna del Charter, syntax/type checks), un mismo modelo se audita bien — `check-plan-drift.sh` no necesita Gemini para funcionar y la Fase 2 es deliberadamente single-model. Para *checks semánticos* (¿esta arquitectura es correcta?, ¿esta categorización es `hallucination` vs `implementation_gap`?), la heterogeneidad es lo que captura la calibración. La distinción es la misma virtud-vs-ceremonia que `straymark-design-principles.md` v0.2 §6 articula: la heterogeneidad inter-familia es virtud cuando externaliza signal donde el sesgo es probable; es ceremonia cuando solo agrega latencia y costo en checks estructurales. -**Implicación operacional para `devtrail charter audit`:** +**Implicación operacional para `straymark charter audit`:** - Si el implementador fue de la familia X (ej: Claude), al menos uno de los dos auditores debe ser de una familia distinta a X. El comando rechaza con error explicativo configuraciones donde implementador y ambos auditores son de la misma familia. - El calibrador-reconciliador puede ser de cualquier familia (incluida la del implementador) porque su trabajo es aplicar el schema definicional sobre veredictos ya producidos, no descubrir gaps. -- La detección de "familia" se hace por mapeo de model-id → family declarado en una tabla del framework (`dist/.devtrail/audit-prompts/model-families.yaml` con entradas como `claude-* → anthropic`, `gpt-*/copilot-* → openai`, `gemini-* → google`). El usuario puede extender la tabla para nuevos modelos. +- La detección de "familia" se hace por mapeo de model-id → family declarado en una tabla del framework (`dist/.straymark/audit-prompts/model-families.yaml` con entradas como `claude-* → anthropic`, `gpt-*/copilot-* → openai`, `gemini-* → google`). El usuario puede extender la tabla para nuevos modelos. ### 5.3 Cambios al framework -- **Plantillas de prompt en `dist/.devtrail/audit-prompts/`**: una por rol (`auditor-primary.md`, `auditor-secondary.md`, `calibrator-reconciler.md`). Las plantillas se derivan de las que Sentinel usó implícitamente; se documentan formalmente. +- **Plantillas de prompt en `dist/.straymark/audit-prompts/`**: una por rol (`auditor-primary.md`, `auditor-secondary.md`, `calibrator-reconciler.md`). Las plantillas se derivan de las que Sentinel usó implícitamente; se documentan formalmente. - **Schema de output canónico**: cada auditor produce un archivo en `audit/charters/{CHARTER-ID}/{role}.md` con frontmatter parseable que se mapea al campo `external_audit` de la telemetría. El calibrador produce `claude-analisis.md` (o equivalente) con consolidación de findings. ### 5.4 Comando nuevo del CLI -- `devtrail charter audit [CHARTER-ID] [--auditors model1,model2] [--calibrator model3] [--implementer-family X]` — orquesta la ejecución secuencial: auditor primary → auditor secondary (en paralelo si la API lo permite) → calibrator que reconcilia veredictos divergentes según el schema. Genera los 3 archivos de output. Integra automáticamente el campo `external_audit` array en la telemetría. Aplica la restricción de heterogeneidad inter-familia descrita en §5.2: si el flag `--implementer-family` no está presente, el comando lo infiere del último AILOG asociado al Charter; si la inferencia y la configuración resultan en una combinación monocromática (implementador + ambos auditores misma familia), el comando rechaza con error explicativo y sugiere alternativas. +- `straymark charter audit [CHARTER-ID] [--auditors model1,model2] [--calibrator model3] [--implementer-family X]` — orquesta la ejecución secuencial: auditor primary → auditor secondary (en paralelo si la API lo permite) → calibrator que reconcilia veredictos divergentes según el schema. Genera los 3 archivos de output. Integra automáticamente el campo `external_audit` array en la telemetría. Aplica la restricción de heterogeneidad inter-familia descrita en §5.2: si el flag `--implementer-family` no está presente, el comando lo infiere del último AILOG asociado al Charter; si la inferencia y la configuración resultan en una combinación monocromática (implementador + ambos auditores misma familia), el comando rechaza con error explicativo y sugiere alternativas. Decisión abierta: qué APIs/modelos soportar. Recomendación inicial: usar el patrón "user provides the API key" (similar a herramientas como `aichat`), no acoplar el CLI a un proveedor específico. Soportar al menos OpenAI (Copilot stand-in), Google (Gemini), Anthropic (Claude) en v0. @@ -199,42 +199,42 @@ Decisión abierta: qué APIs/modelos soportar. Recomendación inicial: usar el p ### 5.5 Criterios de salida de la Fase 3 -- ⏳ Al menos 1 ciclo de auditoría externa multi-modelo ejecutada en un proyecto adoptante con resultados consistentes con la calibración cross-modelo observada en Sentinel. *Pendiente — Sentinel todavía no ejercita `devtrail charter audit` sobre la nueva versión `fw-4.7.x`. El próximo cycle de telemetría (frontend) lo cubre.* +- ⏳ Al menos 1 ciclo de auditoría externa multi-modelo ejecutada en un proyecto adoptante con resultados consistentes con la calibración cross-modelo observada en Sentinel. *Pendiente — Sentinel todavía no ejercita `straymark charter audit` sobre la nueva versión `fw-4.7.x`. El próximo cycle de telemetría (frontend) lo cubre.* - ✅ El calibrador-reconciliador produce findings en formato compatible con el array `external_audit` de la telemetría. *Schema `audit-output.schema.v0.json` enforza compatibilidad por construcción; integración con telemetry validated por la integration test del 3-step flow.* -- ✅ Documentación clara de que el CLI orquesta pero no provee modelos; el usuario controla qué APIs usar. *CLI-REFERENCE.md `### devtrail charter audit` lo declara explícito; CHANGELOG fw-4.7.0 documenta la decisión A1.* +- ✅ Documentación clara de que el CLI orquesta pero no provee modelos; el usuario controla qué APIs usar. *CLI-REFERENCE.md `### straymark charter audit` lo declara explícito; CHANGELOG fw-4.7.0 documenta la decisión A1.* - ⏳ La restricción de heterogeneidad inter-familia se ejercita en los tests integration: una configuración monocromática es rechazada con error claro; una heterogénea procede sin advertencia. *Diferido a v1 por la decisión A1 (orchestration-only) — sin invocación de APIs, el CLI no conoce los modelos del operador, así que no hay punto de inyección donde validar. La heterogeneidad queda como recomendación documentada (CLI-REFERENCE.md) hasta que los HTTP clients aterricen.* ## 6. Mapeo artefactos Sentinel → CLI -Tabla de referencia rápida que conecta cada artefacto validado en Sentinel con su destino en el CLI/framework. La columna izquierda preserva el vocabulario histórico de Sentinel ("Plan"); la columna derecha usa el vocabulario DevTrail going-forward ("Charter"). +Tabla de referencia rápida que conecta cada artefacto validado en Sentinel con su destino en el CLI/framework. La columna izquierda preserva el vocabulario histórico de Sentinel ("Plan"); la columna derecha usa el vocabulario StrayMark going-forward ("Charter"). -| Artefacto Sentinel (vocabulario "Plan") | Ruta absoluta de origen | Fase | Destino DevTrail (vocabulario "Charter") | Estado | +| Artefacto Sentinel (vocabulario "Plan") | Ruta absoluta de origen | Fase | Destino StrayMark (vocabulario "Charter") | Estado | |---------------------|--------------------------|------|---------|---| -| `TEMPLATE.md` v3 | `sentinel/docs/plans/TEMPLATE.md` | 1 | `dist/.devtrail/templates/charter-template.md` | ✅ shipped (`fw-4.4.0`) | +| `TEMPLATE.md` v3 | `sentinel/docs/plans/TEMPLATE.md` | 1 | `dist/.straymark/templates/charter-template.md` | ✅ shipped (`fw-4.4.0`) | | Plan-docs canónicos | `sentinel/docs/plans/{05,06}-*.md` | 1 | `dist/docs/examples/charters/CHARTER-{01,02}-*.md` (anonimizados) | ✅ shipped | -| Telemetrías YAML | `sentinel/.devtrail/plans/PLAN-{05,06}.telemetry.yaml` | 2 | Schema validador para `devtrail charter close` output | ✅ shipped (`fw-4.6.0`) | -| `check-plan-drift.sh` | `sentinel/scripts/check-plan-drift.sh` | 2 | `devtrail charter drift` (reimplementación nativa Rust) | ✅ shipped (`cli-3.7.0`) | -| Reportes auditoría dual | `sentinel/audit/plans/{05,06}/{copilot,gemini,claude-analisis}.md` | 3 | Output canónico de `devtrail charter audit` (orchestration-only en v0; ver A1 §0) | ✅ shipped (`cli-3.8.0`) | -| AILOG canónico originador | `sentinel/.devtrail/07-ai-audit/agent-logs/AILOG-2026-04-24-010-pm008-anomaly-detector.md` | Referencia transversal | `dist/docs/examples/ailogs/AILOG-2026-01-15-001-anomaly-detector-introduction.md` (anonimizado, par de `CHARTER-01`) | ✅ shipped | +| Telemetrías YAML | `sentinel/.straymark/plans/PLAN-{05,06}.telemetry.yaml` | 2 | Schema validador para `straymark charter close` output | ✅ shipped (`fw-4.6.0`) | +| `check-plan-drift.sh` | `sentinel/scripts/check-plan-drift.sh` | 2 | `straymark charter drift` (reimplementación nativa Rust) | ✅ shipped (`cli-3.7.0`) | +| Reportes auditoría dual | `sentinel/audit/plans/{05,06}/{copilot,gemini,claude-analisis}.md` | 3 | Output canónico de `straymark charter audit` (orchestration-only en v0; ver A1 §0) | ✅ shipped (`cli-3.8.0`) | +| AILOG canónico originador | `sentinel/.straymark/07-ai-audit/agent-logs/AILOG-2026-04-24-010-pm008-anomaly-detector.md` | Referencia transversal | `dist/docs/examples/ailogs/AILOG-2026-01-15-001-anomaly-detector-introduction.md` (anonimizado, par de `CHARTER-01`) | ✅ shipped | ## 7. Verificación end-to-end de cada fase -Cada fase tiene un test de aceptación operacional que el equipo de DevTrail debe poder ejecutar sin instrucciones adicionales: +Cada fase tiene un test de aceptación operacional que el equipo de StrayMark debe poder ejecutar sin instrucciones adicionales: **Fase 1:** -1. `cargo install --path cli/` instala `devtrail` con la nueva subcomanda `charter`. -2. En un repo limpio: `devtrail init && devtrail charter new --type M --title "test charter"` produce un Charter en `docs/charters/01-test-charter.md` válido contra `charter.schema.v0.json`. -3. `devtrail charter list` muestra el Charter recién creado en estado `declared`. -4. `devtrail validate --include-charters` pasa sin errores. +1. `cargo install --path cli/` instala `straymark` con la nueva subcomanda `charter`. +2. En un repo limpio: `straymark init && straymark charter new --type M --title "test charter"` produce un Charter en `docs/charters/01-test-charter.md` válido contra `charter.schema.v0.json`. +3. `straymark charter list` muestra el Charter recién creado en estado `declared`. +4. `straymark validate --include-charters` pasa sin errores. **Fase 2:** -1. Tras Fase 1, un commit que toca archivos del Charter + `devtrail charter drift CHARTER-01` reporta 0 drift. +1. Tras Fase 1, un commit que toca archivos del Charter + `straymark charter drift CHARTER-01` reporta 0 drift. 2. Se introduce un drift artificial (declarar archivo extra que no se modifica); el comando reporta 1 omisión y exit code 1. 3. Se documenta el drift en un AILOG asociado; el comando con AILOG-awareness lo suprime y reporta limpio. -4. `devtrail charter close CHARTER-01` produce un YAML válido contra `charter-telemetry.schema.v0.json`. +4. `straymark charter close CHARTER-01` produce un YAML válido contra `charter-telemetry.schema.v0.json`. **Fase 3:** -1. `devtrail charter audit CHARTER-01 --auditors copilot,gemini --calibrator claude` produce 3 archivos de output bien formados. +1. `straymark charter audit CHARTER-01 --auditors copilot,gemini --calibrator claude` produce 3 archivos de output bien formados. 2. El calibrador reconcilia veredictos divergentes (caso de prueba: F5 PLAN-05-style donde un auditor categoriza como `implementation_gap` y otro como `hallucination`). 3. La telemetría queda enriquecida con el campo `external_audit` array correctamente poblado. @@ -242,14 +242,14 @@ Cada fase tiene un test de aceptación operacional que el equipo de DevTrail deb Para mantener disciplina de cristalización experimental: -- **No `charter.schema.v1.0` estable** — solo `v0` experimental hasta validación con segundo proyecto en otro dominio (`devtrail-thesis-validation.md` §6). -- **No features de aprobación condicional** — supuesto #4 sin evidencia (`devtrail-thesis-validation.md` §4.4). -- **No firma criptográfica de Charters** — la prioridad criptográfica vive en `devtrail stage close` (Cloud roadmap), no en Charters aún. +- **No `charter.schema.v1.0` estable** — solo `v0` experimental hasta validación con segundo proyecto en otro dominio (`straymark-thesis-validation.md` §6). +- **No features de aprobación condicional** — supuesto #4 sin evidencia (`straymark-thesis-validation.md` §4.4). +- **No firma criptográfica de Charters** — la prioridad criptográfica vive en `straymark stage close` (Cloud roadmap), no en Charters aún. - **No integración Cloud para Charters** — primero validar el flujo local en CLI con adoptantes; la integración con Inbox y Trust Center sigue al uso real. -- **No comando `devtrail charter extract` (auto-generar Charters desde AILOGs)** — el patrón existe en `cloud-proposal.md` §4.5 pero requiere observación adicional sobre cómo los adoptantes generan Charters en práctica antes de cristalizar la heurística de extracción. +- **No comando `straymark charter extract` (auto-generar Charters desde AILOGs)** — el patrón existe en `cloud-proposal.md` §4.5 pero requiere observación adicional sobre cómo los adoptantes generan Charters en práctica antes de cristalizar la heurística de extracción. -Cada uno de estos puntos tiene un criterio de salida explícito en `devtrail-thesis-validation.md` §8 que, cuando se cumpla, abre la puerta a un nuevo ciclo de roadmap. +Cada uno de estos puntos tiene un criterio de salida explícito en `straymark-thesis-validation.md` §8 que, cuando se cumpla, abre la puerta a un nuevo ciclo de roadmap. --- -*Este roadmap es el primer artefacto que traduce evidencia empírica en código accionable para DevTrail. Su evolución sigue el patrón auto-evolutivo observado en Sentinel: cada fase ejecutada genera datos que refinan el roadmap del próximo ciclo. La versión 0.3 (este documento) se escribió tras completar las 3 fases en `fw-4.4.0` → `fw-4.7.1` con Sentinel como adoptante único; la próxima versión (0.4) se escribirá cuando el segundo dominio (subproyecto frontend de Sentinel, agendado) cierre al menos 1 Charter completo y aporte señal sobre qué del schema `v0` debe promoverse a `v1`, qué frictions emergen en un stack distinto a Go, y si los HTTP clients se justifican antes de v1 estable.* +*Este roadmap es el primer artefacto que traduce evidencia empírica en código accionable para StrayMark. Su evolución sigue el patrón auto-evolutivo observado en Sentinel: cada fase ejecutada genera datos que refinan el roadmap del próximo ciclo. La versión 0.3 (este documento) se escribió tras completar las 3 fases en `fw-4.4.0` → `fw-4.7.1` con Sentinel como adoptante único; la próxima versión (0.4) se escribirá cuando el segundo dominio (subproyecto frontend de Sentinel, agendado) cierre al menos 1 Charter completo y aporte señal sobre qué del schema `v0` debe promoverse a `v1`, qué frictions emergen en un stack distinto a Go, y si los HTTP clients se justifican antes de v1 estable.* diff --git a/docs/decisions/proposals/2026-05-04-audit-cli-flow.md b/docs/decisions/proposals/2026-05-04-audit-cli-flow.md new file mode 100644 index 0000000..b196238 --- /dev/null +++ b/docs/decisions/proposals/2026-05-04-audit-cli-flow.md @@ -0,0 +1,603 @@ +# StrayMark — Audit v1: flujo CLI-driven con disciplina de tool use y zero copy/paste + +**Versión:** 0.2 (cierra design phase tras revisión con material concreto de Sentinel — D11/D12/D13/D14 incorporadas, lift completo del prompt mature pre-StrayMark de Sentinel, wording de zero-friction afinado) +**Fecha:** 4 de mayo de 2026 +**Autor:** Jose Villaseñor Montfort — StrangeDaysTech +**Propósito:** Articular el rediseño integral del flujo de auditoría externa de Charters tras el primer encuentro empírico con un Charter L multi-commit en Sentinel (CHARTER-07, CommsHub Etapa 2). El rediseño aborda integralmente los 3 hallazgos del [issue #102](https://github.com/StrangeDaysTech/straymark/issues/102) más un cuarto eje que el operador surfaceó después: la eliminación total del copy/paste entre IDE principal y CLIs auditoras vía paths canónicos en el repo del adoptante. Una sola iteración de upstream que devuelve a Sentinel un flujo audit substantivo a tiempo para su Etapa 2 — la evidencia que aporta justifica la inversión. +**Documentos relacionados:** `straymark-audit-skills.md` v0.2 (diseño v0 que esta propuesta extiende), `straymark-audit-skills-implementacion.md` v0.2 (plan que se cierra parcialmente con esta iteración), `straymark-design-principles.md` v0.2 (especialmente A1 orchestration-only que esta propuesta preserva en espíritu), `straymark-telemetria-etapa2-sentinel.md` v0.1 (flujo telemetría que se ajusta a la nueva convención de paths), [Issue #102](https://github.com/StrangeDaysTech/straymark/issues/102) (reporte original de Sentinel), `Propuesta/sentinel-skill-prompt-audit.md` y `Propuesta/sentinel-skill-prompt-audit-review.md` (skills mature pre-StrayMark de Sentinel — base directa de la plantilla unificada y del review consolidado v1). + +--- + +## 1. Contexto y problema + +### 1.1 Lo que sucedió en CHARTER-07 + +El 4 de mayo de 2026, Sentinel cerró el primer audit cycle del flujo `audit-skills` shippeado en `fw-4.8.0` / `cli-3.9.0`. CHARTER-07 (CommsHub Etapa 2 foundation: 8 commits, ~4150 líneas, 7 migraciones, 12 query files SQLC, 4 ports, 28 errores, 21 modelos, 16 events, PII guard, 8 OTel metrics, Wire stub) cerró el audit con `findings_total: 1` (un self-categorized false positive de auditor-primary; auditor-secondary 0 findings). + +Esto **se ve limpio. No lo es.** El reporte de Sentinel (issue #102) articula con precisión por qué, y el operador tomó la decisión correcta de pausar `charter close` antes de pollutar la telemetría Phase 2 con un cycle vacuamente exitoso. + +### 1.2 Los cuatro ejes a resolver + +**Eje 1 — R10: resolver duplica contenido via HTML-comment placeholder expansion.** + +El resolver del CLI hace `string.replace({{placeholder}}, content)` global, sin reconocer si el placeholder está dentro de ``. La plantilla `auditor-primary.md` documenta sus placeholders en un header HTML con sintaxis literal `{{placeholder}} — descripción`, y cada uno se expande con su contenido completo. Resultado: prompt de 1300 líneas en lugar de ~700, ~30k tokens duplicados, posible degradación de calidad del audit. + +Categoría: bug mecánico. Severidad media. Reversibilidad alta. + +**Eje 2 — R11(A): `git_range` default es `HEAD~1..HEAD`.** + +CHARTER-07 tiene 8 commits en feature branch. Los auditores procesaron solo el último (un commit metadata-only de atomic update). No vieron migrations, SQLC, scaffolding, Wire, ni la PII guard test — los ~4150 líneas que constituyen la implementación real. La convergencia en "0 findings substantivos" carga vacuamente, no es evidencia de corrección. + +Categoría: decisión de diseño que fue válida bajo asunción no explícita (Charters single-commit). El primer encuentro empírico con Charter L multi-commit la invalida. + +**Eje 3 — R11(B): modo paste-based produce audits estructuralmente limitados.** + +Aún con `git_range` correcto, los auditores en modo paste no pueden: +- Abrir archivos fuera del diff para verificar cross-references. +- Consultar `data-model.md` para validar migrations. +- Confirmar coverage de mappings (`eventTypeToPayload`). +- Inspeccionar patterns existentes (e.g., RLS de spec-001 para validar nueva policy). + +Sin tool use, los auditores extienden a training data + assumptions. La pre-StrayMark methodology de Sentinel tenía un prompt iteradamente refinado contra slip-ups específicos (Gemini asumiendo corrección de clases por naming es el ejemplo canónico). Esa disciplina **no es representable en prompt paste-based**. + +Categoría: extensión arquitectónica. **NO es regresión a A1** (orchestration-only): la solución no es implementar HTTP API clients. Es extender el alcance a un segundo modo (CLI auditor-side con tool use) donde el operador maneja sus propias CLIs auditoras y StrayMark solo provee prompts disciplinados. + +**Eje 4 — Eliminación de copy/paste vía paths canónicos + skill auditor-side.** + +Surfaceado por el operador después del issue #102 desde su experiencia operativa: aún con (B) resuelto, el flujo "operador genera prompt → operador copia → operador pega en LLM externo → operador copia respuesta → operador pega en archivo → operador regresa" es fricción independiente. El rediseño puede usar el filesystem del repo como canal estructurado: el agente principal escribe el prompt en path canónico; las CLIs auditoras leen ese path, ejecutan, y escriben los reports en otro path canónico; el agente principal lee los N reports al regresar. + +Esto convierte el copy/paste en **invocación de skills**: el operador solo invoca `/straymark-audit-prompt`, `/straymark-audit-execute` (en N CLIs), y `/straymark-audit-review`. El intercambio de datos entre agentes es vía filesystem, no manual. + +### 1.3 Por qué iteración integrada y no patches secuenciales + +Patches secuenciales (R10 hoy, R11(A) la próxima semana, R11(B) en dos semanas, eje 4 en tres) forzarían a Sentinel a re-correr CHARTER-07 múltiples veces contra fixes parciales, gastando cycles audit reales sin generar evidencia marginal. Una iteración integrada permite: + +- Sentinel re-audita CHARTER-07 **una sola vez** con el flujo completo nuevo. +- Sentinel continúa Etapa 2 desde CHARTER-08 bajo el flujo unificado, sin migrar mid-stage. +- La evidencia v1 que se acumule durante CHARTER-07..13 es coherente (un solo flujo, una telemetría, una convención). +- StrayMark evita el costo de coordinación de múltiples releases con migraciones overlapping. + +El costo de la iteración integrada: ~5-7 PRs ordenados en lugar de 3-4 patches paralelos. Manejable en una sesión de implementación dedicada (similar al day de Phase 1). + +--- + +## 2. Decisiones de diseño + +### D1 — Convención de paths canónica nueva: `.straymark/audits/` + +**Decisión:** los outputs del flujo audit viven bajo `.straymark/audits//`. La carpeta `audit/` actual se considera convención v0 deprecada. + +**Justificación:** `audit/` (singular, sin prefijo) en el root del repo es genérica y puede chocar con carpetas legítimas del adoptante (auditorías de seguridad de la app, auditorías de licencias, etc.). `.straymark/audits/` (plural, bajo dotdir StrayMark) es claramente de la herramienta y nunca colisiona porque `.straymark/` ya está reservado. + +**Estructura interna:** + +``` +.straymark/audits/ +└── CHARTER-07/ + ├── audit-prompt.md # prompt unificado, generado por audit-prompt skill + ├── report-claude-sonnet-4-6.md # generado por audit-execute en CLI claude + ├── report-gemini-2.5-pro.md # generado por audit-execute en CLI gemini + └── report-gpt-5.3-codex.md # opcional, tercera auditoría +``` + +Naming de reports: `report-.md`. El skill `audit-execute` deriva el slug del model identifier que el agente conoce sobre sí mismo. Si un mismo modelo audita dos veces (raro pero posible), el segundo agrega sufijo `-2`, etc. + +### D2 — Plantilla unificada: un solo `audit-prompt.md` + +**Decisión:** retirar la distinción `auditor-primary.md` / `auditor-secondary.md`. Una sola plantilla `audit-prompt.md` que cualquier auditor ejecuta. + +**Justificación:** en v0 la diferencia entre primary y secondary era cosmética — mismo schema de output, mismas instrucciones, mismo framing modulo tres líneas de wording. La distinción servía para que el calibrator pudiera comparar simétricamente, pero el calibrator funciona igual leyendo N reports independientes. Una sola plantilla: + +- Reduce mantenimiento (una superficie de actualización en lugar de dos). +- Permite N auditorías (no fijado a 2 — el operador decide cuántas). +- Elimina la pregunta "¿cuál es el primary?" que era arbitraria. +- Simplifica el modelo mental para el adoptante. + +La plantilla unificada absorbe la disciplina de tool use (D5) y el wording mature de Sentinel pre-StrayMark. + +### D3 — Soporte de N auditorías, no 2 + +**Decisión:** `straymark-audit-review` itera todos los `report-*.md` en `.straymark/audits//` en lugar de leer exactamente 2 archivos. + +**Justificación:** el operador puede tener razones legítimas para querer 3 o 4 auditorías: + +- Charters de alto riesgo (security-critical) merecen más cobertura cross-modelo. +- Charters con superficie especializada (ML, criptografía, infra cloud) pueden beneficiarse de un auditor de modelo especializado además de los generales. +- Adoptantes con presupuesto suficiente quieren más señal. + +El minimum viable sigue siendo 2 (heterogeneidad inter-familia), pero el flujo no impone el techo. La convención de paths permite N reports naturalmente. + +**Borde inferior:** si `.straymark/audits//` tiene 0 o 1 reports cuando el operador invoca `audit-review`, el skill emite warning (heterogeneidad insuficiente) pero procede — la decisión final es del operador. + +### D4 — Nuevo skill `straymark-audit-execute` + +**Decisión:** se crea un tercer skill StrayMark (`straymark-audit-execute CHARTER-XX`) que se invoca en CLIs auditoras (gemini-cli, claude-cli, copilot-cli, codex-cli, etc.) en lugar del flujo paste manual. + +**Comportamiento del skill:** + +1. Recibe `CHARTER-XX` como argumento. +2. Lee `.straymark/audits/CHARTER-XX/audit-prompt.md`. +3. Sigue la disciplina del prompt: lee archivos relevantes vía tool use (Read), recolecta evidencia, produce findings con citas `path:line`. +4. Escribe `.straymark/audits/CHARTER-XX/report-.md` con frontmatter conforme a `audit-output.schema.v0.json`. +5. Imprime al operador la ruta del reporte + instrucción de regresar al agente principal y ejecutar `/straymark-audit-review CHARTER-XX` cuando todas las auditorías estén completas. + +**Distribución (igual que los demás skills):** + +- `dist/.claude/skills/straymark-audit-execute/SKILL.md` (allowed-tools: Read, Write, Bash, Glob, Grep) +- `dist/.gemini/skills/straymark-audit-execute/SKILL.md` +- `dist/.agent/workflows/straymark-audit-execute.md` + +**Crítico:** este skill **no invoca APIs externos**. Corre dentro de la CLI auditora que el operador ya está usando con sus propias credenciales. StrayMark solo provee la skill que dice "lee este archivo, audit con tool use, escribe este otro archivo". + +### D5 — Disciplina de tool use enforced por el prompt + +**Decisión:** la plantilla unificada `audit-prompt.md` incluye una sección de **Disciplina de evidencia** que enuncia explícitamente: + +> *"Solo puedes opinar sobre archivos que has abierto vía tool call (`Read`, `Grep`, etc.). Cualquier finding que produzcas debe citar `path:line` de los archivos específicos que abriste. Findings sin citas se consideran inválidas y se rechazan en review. Si no abriste un archivo, no puedes inferir comportamiento, estructura, ni corrección sobre él."* + +**En modo CLI** (`audit-execute` en gemini-cli/claude-cli/etc.): el agente cumple la disciplina literalmente. El skill `audit-review` valida que cada finding incluye al menos una cita `path:line`; findings sin cita se descartan o se marcan como `low-confidence`. + +**En modo paste** (operador pega manualmente en LLM de chat): la disciplina opera como guía aspiracional. Si el modelo no tiene tool use, no puede cumplirla literalmente; produce findings sin citas. El skill `audit-review` los procesa pero los marca con menor peso. Esto degrada gracefully sin romper. + +El prompt mature de Sentinel pre-StrayMark (que el operador ofreció contribuir) es la base. Se incorpora con atribución. + +### D6 — `git_range` default cambia a `origin/main..HEAD` con fallback + +**Decisión:** + +- Si la rama actual tiene `origin/main` reachable → default `origin/main..HEAD`. +- Si no → fallback a `HEAD~1..HEAD` con warning explícito. +- Flag `--range` sigue intacto para override. + +**Justificación:** R11(A) del issue #102. El comportamiento previo era válido bajo asunción de Charters single-commit; el caso real es Charters multi-commit en feature branches. + +**Consideración de breaking-ness:** estrictamente no breaking (output sigue siendo válido), pero scripts que dependan del default cambian. CHANGELOG documenta explícitamente la rationale. Bump a `cli-3.10.0` (minor, no patch). + +### D7 — R10 fix: resolver respeta bounds de `` + +**Decisión:** opción 1 de las dos que Sentinel propuso — el resolver detecta bloques `` y skipea reemplazo de placeholders dentro de ellos. + +**Justificación:** opción 1 es semánticamente correcta (los HTML comments son no-content por design en markdown). Opción 2 (detectar pattern indentado + ` — descripción`) acopla resolver con convención de documentación de plantillas, que es frágil ante cambios de formato. + +**Implementación:** una pasada simple sobre el template antes del replace global, identificando ranges `` y excluyendo placeholders dentro. Test de regresión: template con `{{x}}` produce un único replace. + +### D8 — CLI subcommand simplificado + +**Decisión:** el subcommand `straymark charter audit` se simplifica: + +**v0:** `straymark charter audit [--calibrate | --finalize] [--merge-into ]` (3 pasos: prepare, calibrate, finalize). + +**v1:** `straymark charter audit [--prepare | --merge-reports] [--merge-into ]`. + +- **`--prepare`** (default): genera `audit-prompt.md` resuelto en `.straymark/audits//`. Sustituye el "PREPARE" de v0. +- **`--merge-reports`**: lee N `report-*.md` desde `.straymark/audits//`, valida cada uno contra schema, produce el bloque YAML `external_audit:` array. Combinable con `--merge-into ` para auto-mergear en telemetry. Sustituye el "FINALIZE" de v0. +- **No hay paso `--calibrate` separado**: la "calibración" la hace el agente principal vía el skill `straymark-audit-review` que lee los reports + razona inline + invoca `--merge-reports --merge-into ` al final. + +**Justificación:** el paso `--calibrate` v0 era un pre-procesamiento de calibrator-reconciler.prompt.md que en práctica solo funcionaba si el calibrator también corría en CLI con filesystem access (que el agente principal del IDE sí tiene). En v1, el agente principal **es** el calibrator implícito; no necesita una plantilla separada para reconciliar — itera los reports directamente y produce el análisis inline. Eso elimina un archivo redundante (`calibrator-reconciler.prompt.md`) y un paso CLI redundante. + +### D9 — Schema `audit-output.schema.v0.json` ajustado + +**Decisión:** schema se mantiene en `v0` (experimental), con dos cambios: + +- `audit_role` deja de ser enum `auditor-primary | auditor-secondary | calibrator-reconciler`. Pasa a ser `auditor` (singular) — un solo rol porque ya no distinguimos primary/secondary, y el reconciler ahora es el agente principal in-conversation que no escribe report propio. +- Frontmatter de un report incluye campo opcional `evidence_citations: ` — cuántos `path:line` cita el body. El skill `audit-review` lo usa para weighting. + +**Cambios al schema viejo:** SI breaking dentro del experimental `v0`. Pero los reports v0 viejos (en `audit/charters/CHARTER-XX/`) no son leídos por v1 (paths distintos), así que no hay path de migración. Los outputs v0 quedan como evidencia histórica del cycle paused. + +### D10 — Sin modo `--auditor-mode cli|paste` explícito + +**Decisión:** no hay flag CLI para distinguir modo CLI vs paste. El sistema es agnóstico de cómo el operador obtuvo cada `report-*.md`. + +**Justificación:** el skill `audit-review` no necesita saber si un report fue generado por `audit-execute` en CLI con tool use, o si el operador lo escribió manualmente después de un chat paste. Lee el archivo, valida el schema, procesa. La diferencia se refleja naturalmente en los `evidence_citations` (alto en CLI, bajo o cero en paste). El operador es libre de mezclar modos. + +Esto simplifica enormemente: una sola convención de paths, una sola plantilla, un solo flujo de review. El modo es problema del operador. + +### D11 — El review v1 produce un análisis consolidado, no solo YAML + +**Decisión:** el skill `straymark-audit-review` v1 evoluciona de "validate + merge YAML" a "consolidated analysis generator". Produce `.straymark/audits//review.md` con la estructura completa observada en el skill `audit-review` mature de Sentinel pre-StrayMark (`Propuesta/sentinel-skill-prompt-audit-review.md`): + +1. **Resumen ejecutivo** (2-3 párrafos: hallazgos clave, scope confusion si aplica, bug más crítico). +2. **Definición del alcance correcto** (tabla con tasks del Charter, checkpoint, qué está IN vs OUT de scope). +3. **Evaluación por auditoría** — tabla por auditor con findings, severidad reportada, veredicto y justificación. +4. **Plan de remediación** — priorizado P0 (Seguridad) / P1 (Integridad) / P2 (Consistencia) / P3 (Robustez) / P4 (Documentación) con archivo:línea, problema, remediación, complejidad, quién lo detectó. +5. **Hallazgos descartados** (misatribuciones + falsos positivos) — tabla con hallazgo, tipo, etapa real si aplica, auditor que lo reportó. +6. **Calificación de auditores** — score 1-10 sobre 4 criterios con weights: + - Scope precision: 25% + - Technical depth: 25% + - Bug detection: 30% + - False positive rate: 20% +7. **Conclusión** (estado del Charter, hallazgos críticos, próximo paso). + +El veredicto por finding sigue el vocabulario del Sentinel skill: **VALID / PARTIALLY VALID (con reclassification) / MISATTRIBUTED / FALSE POSITIVE / DUPLICATE**. + +**Adicional al review.md:** el `external_audit:` array YAML se mergea en la telemetry como en v0 (vía `--merge-reports --merge-into`). Las dos cosas coexisten: el review consolidado es para el operador (legible, accionable), el YAML es para la telemetry agregada (machine-readable, alimenta Phase 2 stats). + +**Justificación:** R11(B) del issue #102 articulaba "audits de structurally limited substantive reach". Un YAML mergeado no resuelve eso aunque tenga citaciones. Un análisis consolidado sí — es la diferencia entre "se generó la telemetría" y "el operador tiene un documento usable para remediation". El skill `audit-review` mature de Sentinel ya validó empíricamente que el formato consolidado es el delivery útil al humano; lift directo en lugar de re-derivar. + +### D12 — La plantilla unificada `audit-prompt.md` se basa directamente en el Sentinel skill, parametrizada + +**Decisión:** la plantilla unificada se construye lifting el contenido del skill `audit/SKILL.md` mature de Sentinel pre-StrayMark (`Propuesta/sentinel-skill-prompt-audit.md`). Se preservan integralmente las 7 secciones que son universales y portables: + +1. **§REGLA ABSOLUTA — SOLO LECTURA** (Sentinel líneas 55-77): disciplina enunciada operacionalmente — *"Si encuentras un bug, DOCUMENTALO en tu reporte. NO lo corrijas. Si encuentras un archivo faltante, REPORTALO. NO lo crees. Violación de esta regla invalida toda la auditoría."* Es la solución textual a R11(B) y reemplaza directamente el placeholder de "tool-use enforcement" propuesto en D5. +2. **§Tu rol** ("No eres cheerleader") — anti-pattern del modelo complaciente. +3. **§Reglas de alcance** — out-of-scope handling como sección separada. +4. **§Paso 2 — Verificar cada tarea (OBLIGATORIO)** — chain de verificación con tool use: localizar → leer COMPLETO → trazar (handler → service → repo → SQL) → leer ≥2 test cases → comparar contra tarea con cita `archivo:línea`. +5. **§Paso 5 — Calibrar severidad contra config REAL** — anti-inflation y anti-deflation con checklist obligatorio (driver activo, feature flags, build tags, rol DB, deployment scope) antes de declarar Critical/High. +6. **§Lo que NO debes hacer** — closing reinforcement. +7. **§Formato de salida** — estructura del report markdown (Alcance, Verificación de compilación/tests, Trazabilidad tarea por tarea, Hallazgos por severidad, Notas fuera de alcance, Evaluación de checkpoint, Conclusión). + +**Lo que se parametriza** (los hardcodes Sentinel se convierten en placeholders del resolver del CLI): + +| Sentinel hardcode | Placeholder StrayMark v1 | +|---|---| +| `specs/001-sentinel-mvp/tasks.md` | `{{charter_path}}` + `{{charter_body}}` | +| `## Etapa N:` heading | `{{charter_id}}` + `{{charter_title}}` | +| Lista de tareas extraída de `tasks.md` | `{{tasks_list}}` (extraído de `## Tasks` del Charter) | +| Checkpoint textual | `{{charter_trigger}}` o sección equivalente | +| `audit/etapas-implementacion/{N}/[tu-nombre]-audit.md` | `.straymark/audits/{{charter_id}}/report-.md` | +| Project description "Sentinel es un monolito modular en Go..." | `{{project_context}}` (derivado de README/CLAUDE.md o config opcional) | +| `internal/modules/identity/`, `middleware/auth*` | `{{security_paths_hint}}` (derivado de Charter risk_level + tags) | +| `internal/core/eventbus/factory.go`, etc. | `{{factory_hints}}` (placeholder libre, opcional) | +| `go vet ./...`, `go build`, `go test` | `{{build_commands}}` (derivado de project type) | +| `originating_ailogs[]` (no presente en Sentinel) | `{{originating_ailogs}}` — se inyecta el contenido de los AILOGs origen para context | +| `{{git_diff}}` | `{{git_diff}}` (output de git diff sobre el `--range` resuelto) | + +**Lo que se preserva como ilustración didáctica:** los ejemplos concretos del skill Sentinel (la anécdota de Etapa 12 Pub/Sub stub vs gochannel) se mantienen en la plantilla **rotulados como "Ejemplo (de un caso real en proyecto adoptante)"**. Son material didáctico para que el auditor entienda el patrón anti-inflation aún sin trabajar en Sentinel. + +**Crédito:** la plantilla incluye una nota al pie: *"Esta plantilla se basa en el skill `audit/SKILL.md` mature pre-StrayMark de Sentinel, contribuido vía issue #102. Las 7 secciones universales se preservan integralmente; los hardcodes específicos a Sentinel se parametrizaron. Crédito a José Villaseñor Montfort (operador Sentinel/StrayMark) por el material base."* + +### D13 — `.straymark/audits/` namespaced para extensibilidad futura, sin nest bajo `charters/` + +**Decisión:** la convención de paths queda `.straymark/audits/-/...`. La primera (y única en v1) categoría es `CHARTER-`, pero la estructura **no se anida bajo `.straymark/charters/`** porque eso cerraría la puerta a auditar otras categorías de unidades en el futuro. + +**Estructura conceptual:** + +``` +.straymark/audits/ +├── CHARTER-07/ # auditoría de un Charter (v1, único caso soportado) +├── CHARTER-08/ +└── (futuro) + ├── MODULE-payments/ # auditoría de un módulo completo + ├── RELEASE-v2.0/ # auditoría pre-release + └── EPIC-multi-tenancy/ # auditoría de un epic transversal +``` + +**Justificación (rationale del operador en sesión de revisión):** los archivos audit ya tienen el ID del unit en el nombre del directorio, así que anidar bajo `charters/` es redundante. Más importante, **el adoptante puede extender el framework para auditar unidades más amplias o estrechas que un Charter** sin que la convención de paths requiera reestructuración. Esto preserva los principios #5 (schema-driven antes que feature-driven) y #12 (espera evidencia antes de cristalizar) — la primera y única categoría hoy es Charter; futuras categorías se exploran cuando un caso operativo concreto las demande. + +**Lo que NO se cristaliza ahora:** el shape exacto de las futuras categorías (qué metadata necesita un MODULE audit, cómo se invoca, etc.) queda fuera de v1. El namespacing solo deja la puerta abierta. + +### D14 — Discovery automático y detección de slug en `straymark-audit-execute` + +**Decisión:** dos enhancements de zero-friction al skill `straymark-audit-execute`: + +**(a) Argumento opcional con discovery automático.** Si el operador invoca `/straymark-audit-execute` sin argumento (porque abre la CLI auditora y no recuerda qué CHARTER auditar), el skill busca en `.straymark/audits/*/audit-prompt.md` los prompts existentes que **aún no tienen** un `report-.md` (ya hecho por este modelo). Tres casos: + +- **Exactamente uno encontrado** → procede automáticamente. +- **Múltiples encontrados** → lista al operador con CHARTER IDs + títulos, pide selección numérica. +- **Ninguno encontrado** → mensaje: "No hay audit prompts pendientes para este modelo. Verifica que el operador haya ejecutado `/straymark-audit-prompt` en el agente principal primero." + +**(b) Detección automática del model slug.** El skill identifica su propio `model-id` desde el contexto runtime de la CLI auditora (ej. `claude-sonnet-4-6`, `gemini-2.5-pro`, `gpt-5.3-codex`). Construye el slug del filename automáticamente. Si por alguna razón runtime no expone el model-id, el skill pide al operador confirmar — pero el caso default es automático. + +**Justificación:** el operador puede abrir 3 CLIs auditoras simultáneamente (gemini-cli en una terminal, claude-cli en otra, copilot-cli en tercera). Recordar exactamente qué CHARTER ID escribir en cada una es fricción innecesaria. El discovery automático elimina esa fricción manteniendo la decisión consciente del operador (sigue invocando el skill explícitamente). La detección de slug elimina la fricción de "¿cómo escribo el filename?". + +**Importante:** el discovery automático **no** invoca el skill por sí solo — el operador sigue invocándolo explícitamente. Solo simplifica el "qué argumento pasar". + +--- + +## 3. Arquitectura nueva + +### 3.1 Flujo end-to-end + +``` +[Repo del adoptante] + +Operador humano: + 1. Crea Charter via `straymark charter new ...` + 2. Implementa con agente IA principal (multi-task, multi-commit) + +Agente IA principal: + 3. Alcanza checkpoint de audit (AGENT-RULES.md §12) + 4. Pregunta SÍ/NO con recomendación + +[Si NO] + 5a. Charter cierra normalmente via `straymark charter close` + +[Si SÍ] +Operador humano: + 5. Invoca `/straymark-audit-prompt CHARTER-XX` en agente principal + +Agente principal (Claude Code, etc.): + 6. Ejecuta `straymark charter audit CHARTER-XX --prepare` + 7. CLI escribe `.straymark/audits/CHARTER-XX/audit-prompt.md` + 8. Skill avisa al operador (sin requerir paths del operador): + "Prompt generado. Abre las CLIs auditoras que decidas usar + (recomendación: 2 modelos de familias distintas) y en cada + una invoca /straymark-audit-execute CHARTER-XX. Cuando TODAS + las auditorías que encargues hayan terminado (no antes), + regresa aquí y ejecuta /straymark-audit-review CHARTER-XX." + +Operador humano (en N CLIs auditoras, secuencial o paralelo): + 9. Para cada CLI (gemini-cli, claude-cli, copilot-cli, ...): + - cd al repo del adoptante (los skills ya están instalados + localmente vía straymark init, no requiere setup extra) + - Invoca `/straymark-audit-execute CHARTER-XX` + (o sin argumento, el skill descubre el CHARTER pendiente) + +Cada agente auditor (en su propia CLI): + 10. Lee .straymark/audits/CHARTER-XX/audit-prompt.md + (sin que el operador le pase el path — el skill lo construye + desde el CHARTER-ID o lo descubre automáticamente) + 11. Audit con tool use: lee archivos relevantes, cita path:line + 12. Escribe .straymark/audits/CHARTER-XX/report-.md + (slug detectado automáticamente desde el runtime) + 13. Skill avisa al operador: + "Audit completo (CHARTER-XX, este modelo). + Report en .straymark/audits/CHARTER-XX/report-.md. + + IMPORTANTE: solo regresa a /straymark-audit-review en tu + agente principal cuando TODAS las auditorías que decidiste + encargar hayan terminado. Si tienes otras CLIs auditoras + corriendo (gemini-cli, copilot-cli, etc.), espera a que + terminen antes de invocar review. Si invocas review con + reports incompletos, el análisis consolidado quedará + parcial y tendrás que descartarlo o re-correrlo." + +Operador humano (cuando TODAS las auditorías encargadas terminaron): + 14. Regresa al agente principal + 15. Invoca `/straymark-audit-review CHARTER-XX` + +Agente principal: + 16. Itera `.straymark/audits/CHARTER-XX/report-*.md` (N archivos) + 17. Valida cada uno contra schema (audit-output.schema.v0.json) + 18. Por cada finding del master list: lanza Explore agents en + paralelo (hasta 3 a la vez) para verificar contra el código, + clasifica veredicto (VALID/PARTIALLY VALID/MISATTRIBUTED/ + FALSE POSITIVE/DUPLICATE), reclasifica severidad si aplica + (anti-inflation, anti-deflation), busca findings que los + auditores hayan missed + 19. Produce .straymark/audits/CHARTER-XX/review.md consolidado + con 6 secciones: Resumen ejecutivo, Definición de alcance, + Evaluación por auditoría, Plan de remediación P0-P4, + Hallazgos descartados, Calificación de auditores + 20. Ejecuta `straymark charter audit CHARTER-XX --merge-reports + --merge-into .straymark/charters/CHARTER-XX.telemetry.yaml` + 21. external_audit array mergeado en telemetry, audit-telemetry + JSONL log escrito + 22. Skill avisa al operador: + "Review consolidado en .straymark/audits/CHARTER-XX/review.md + (incluye remediation plan P0-P4 con N items, calificación + de auditores). YAML mergeado en telemetry. + Sugerido: git diff para revisar antes de close." + +Operador humano: + 23. Revisa review.md (lectura humana, principal delivery) + 24. Revisa via git diff los cambios al telemetry + 25. (Opcional) Aplica remediation plan items P0/P1 si los hay + 26. Cierra Charter con `straymark charter close CHARTER-XX` +``` + +**Cero copy/paste manual** entre operador y agentes. **Cero paths que el operador tenga que escribir.** Solo 3 invocaciones de skills con CHARTER-ID (o ninguno, vía discovery), más decisiones de autoría humana (sí/no auditar, qué CLIs usar, cuándo todas terminaron). El intercambio de archivos entre agentes es vía filesystem del repo. + +**Cero copy/paste manual entre operador y agentes.** El operador solo invoca skills. + +### 3.2 Cambios concretos por componente + +**Archivos del framework (`dist/`):** + +- `dist/.straymark/audit-prompts/audit-prompt.md` — NEW. Plantilla unificada **basada directamente en `Propuesta/sentinel-skill-prompt-audit.md`** con las 7 secciones universales (REGLA ABSOLUTA, Tu rol, Reglas de alcance, Paso 2 verificación obligatoria, Paso 5 calibración severidad, Lo que NO debes hacer, Formato de salida). Hardcodes Sentinel parametrizados según D12. Ejemplos didácticos (Etapa 12 Pub/Sub stub) preservados con rótulo "Ejemplo de caso real". Crédito explícito a Sentinel al pie. +- `dist/.straymark/audit-prompts/auditor-primary.md` — DELETE. +- `dist/.straymark/audit-prompts/auditor-secondary.md` — DELETE. +- `dist/.straymark/audit-prompts/calibrator-reconciler.md` — DELETE (el rol calibrator ahora lo cumple el agente principal vía el skill `straymark-audit-review`, no requiere plantilla separada). +- `dist/.straymark/schemas/audit-output.schema.v0.json` — UPDATE: `audit_role: auditor` simple (eliminar enum auditor-primary/secondary/calibrator-reconciler), agregar `evidence_citations: ` opcional para weighting. +- `dist/.claude/skills/straymark-audit-prompt/SKILL.md` — UPDATE: nueva ruta canónica `.straymark/audits//audit-prompt.md`, wording de "espera a TODAS las auditorías" en next-steps guidance. +- `dist/.gemini/skills/straymark-audit-prompt/SKILL.md` — UPDATE (mismo). +- `dist/.agent/workflows/straymark-audit-prompt.md` — UPDATE (mismo). +- `dist/.claude/skills/straymark-audit-execute/SKILL.md` — NEW. Body incluye: lectura de `.straymark/audits//audit-prompt.md`, audit con tool use (Read/Grep/Bash test commands), escritura de `report-.md`. Implementa D14 (discovery automático cuando argumento omitido + detección automática de model slug). Aviso final al operador con énfasis "espera a TODAS las auditorías encargadas antes de invocar review". +- `dist/.gemini/skills/straymark-audit-execute/SKILL.md` — NEW (mismo). +- `dist/.agent/workflows/straymark-audit-execute.md` — NEW (mismo, sin allowed-tools). +- `dist/.claude/skills/straymark-audit-review/SKILL.md` — UPDATE: **evoluciona de "validate + merge YAML" a "consolidated analysis generator"** según D11. Body incluye: iteración de N reports, verificación finding por finding contra código vía Explore agents (paralelización hasta 3 a la vez), clasificación de veredictos (VALID/PARTIALLY VALID/MISATTRIBUTED/FALSE POSITIVE/DUPLICATE), severity calibration (anti-inflation/anti-deflation), búsqueda de findings missed, generación de `review.md` con 6 secciones, calificación de auditores 1-10 sobre 4 criterios, merge YAML adicional vía `--merge-reports --merge-into`. +- `dist/.gemini/skills/straymark-audit-review/SKILL.md` — UPDATE (mismo). +- `dist/.agent/workflows/straymark-audit-review.md` — UPDATE (mismo). +- `dist/.straymark/00-governance/AGENT-RULES.md` (3 langs) — UPDATE §12: wording del checkpoint mencionando el flujo nuevo de 3 skills + paths canónicos `.straymark/audits/`. Nota explícita de "espera a TODAS las auditorías encargadas antes de invocar audit-review". + +**Archivos del CLI (`cli/`):** + +- `cli/src/commands/charter/audit.rs` — UPDATE: + - Nueva ruta canónica `.straymark/audits//`. + - Subcommand simplificado: `--prepare` (default) y `--merge-reports`. Eliminar `--calibrate` y `--finalize` (con shim de deprecation que dirige al nuevo flag — ver §4 migración). + - `git_range` default cambia con fallback inteligente. + - Resolver respeta `` (R10 fix). + - `--merge-reports` itera N archivos en lugar de leer 2 fijos. +- `cli/src/main.rs` — UPDATE clap subcommand. +- `cli/tests/charter_audit_test.rs` — UPDATE tests existentes (ahora bajo `.straymark/audits/`) + 4 tests nuevos: + - `audit_prepare_writes_unified_prompt_to_canonical_location` + - `audit_merge_reports_iterates_n_reports` + - `audit_resolver_respects_html_comment_bounds` + - `audit_git_range_falls_back_when_no_origin_main` + +**Documentación adopter (`docs/`):** + +- `docs/adopters/CLI-REFERENCE.md` (3 langs) — UPDATE §`straymark charter audit` (subcommand simplificado, paths nuevos), §Skills (skill nuevo `audit-execute`, audit-review evolucionado). +- `docs/adopters/WORKFLOWS.md` (3 langs) — UPDATE Charter audit checkpoint con flujo nuevo. +- `docs/adopters/ADOPTION-GUIDE.md` (3 langs) — UPDATE §External Audit (Optional) con guía de cómo configurar CLIs auditoras read-only. +- `dist/.straymark/00-governance/QUICK-REFERENCE.md` (3 langs) — UPDATE tabla skills (3 audit skills ahora). + +--- + +## 4. Migración desde v0 (estrategia para Sentinel y futuros adoptantes) + +### 4.1 Convención de paths + +- v0 usaba `audit/charters//auditor-{primary,secondary,reconciler}.md`. +- v1 usa `.straymark/audits//audit-prompt.md` + `report-*.md`. + +**Para Sentinel (CHARTER-07 paused):** los outputs v0 quedan en `audit/charters/CHARTER-07/` como evidencia histórica. Sentinel re-corre el cycle bajo v1 (`straymark charter audit CHARTER-07 --prepare`), genera nuevos archivos en `.straymark/audits/CHARTER-07/`, ejecuta `audit-execute` en sus CLIs auditoras, y cierra. La carpeta `audit/` queda en el repo (no se borra) — útil para postmortem comparativo entre v0 y v1. + +**Para futuros adoptantes:** desde `fw-4.9.0` en adelante, todos los Charters usan la convención nueva. No hay legacy. + +### 4.2 Subcommand CLI + +- `straymark charter audit --calibrate` → deprecated; emite warning con instrucción de usar el flujo nuevo via skill `straymark-audit-review`. +- `straymark charter audit --finalize` → deprecated; warning + redirect a `--merge-reports`. +- `straymark charter audit --finalize --merge-into ` → deprecated; el comportamiento equivalente es `--merge-reports --merge-into ` pero leyendo de la nueva ruta. + +Los flags deprecated se mantienen en `cli-3.10.0` con warning. Se eliminan en `cli-3.11.0` o cuando todos los adoptantes hayan migrado (lo que llegue antes). + +### 4.3 Schema audit-output + +- Reports v0 (con `audit_role: auditor-primary | auditor-secondary | calibrator-reconciler`) NO son leídos por el sistema v1. +- Reports v1 usan `audit_role: auditor` simple. +- No hay shim de migración automática de reports — los v0 se quedan como están en `audit/charters/`, los v1 se generan limpios en `.straymark/audits/`. + +### 4.4 Charter telemetry + +- El campo `external_audit:` array en `charter-telemetry.schema.v0.json` no cambia shape — sigue siendo array de objetos auditor con findings_total, findings_by_category, audit_quality, audit_notes. +- El skill `audit-review` v1 produce el mismo shape; solo cambia la fuente (lee N `report-*.md` en lugar de 2 archivos fijos). +- Telemetrías de Charters cerrados antes de `fw-4.9.0` siguen siendo válidas y leíbles por el sistema. + +--- + +## 5. Plan de implementación + +### 5.1 Secuencia de PRs + +| # | Título | Critical path | Estimación | +|---|---|---|---| +| 1 | R10 fix: resolver respeta `` bounds + tests de regresión | sí | 2-3 h | +| 2 | `git_range` default change con fallback + tests + CHANGELOG note | sí | 2-3 h | +| 3 | Plantilla unificada `audit-prompt.md` (basada en prompt Sentinel pre-StrayMark) + delete primary/secondary/reconciler templates + schema audit-output ajustado | sí | 4-5 h | +| 4 | CLI subcommand simplificado: `--prepare` / `--merge-reports`, paths canónicos `.straymark/audits/`, deprecation shims de `--calibrate` / `--finalize` con warning | sí | 5-6 h | +| 5 | Skill nueva `straymark-audit-execute` × 3 plataformas + tests fixture | sí | 3-4 h | +| 6 | Skill `straymark-audit-prompt` y `straymark-audit-review` actualizadas × 3 plataformas + tests fixture | sí | 3-4 h | +| 7 | Documentación adopter (CLI-REFERENCE, WORKFLOWS, ADOPTION-GUIDE, QUICK-REFERENCE × 3 langs) + AGENT-RULES §12 | parcial | 4-5 h | +| 8 | Bump `fw-4.9.0` / `cli-3.10.0` + CHANGELOG combined section + tag release | sí | 1-2 h | + +**Total estimado:** 28-36 horas focused (revisado al alza tras incorporar el lift completo de los Sentinel skills, el review consolidado de D11, y los enhancements de D14). Calendarizable como una sesión densa similar al day de Phase 1, o distribuible en 2-3 días con verificación intermedia. + +**Críticos secuenciales:** PR 1 → PR 2 → PR 3 → PR 4 → (PR 5 || PR 6) → PR 7 → PR 8. + +PR 5 y PR 6 pueden ir en paralelo desde sus ramas tras PR 4. + +### 5.2 Estrategia de tests + +Reusar el patrón de Phase 1: tests fixture sobre archivos de skills (existencia, frontmatter shape, paridad cross-language) + integration tests sobre el CLI que ejercitan el flujo end-to-end con fixtures. + +Tests de integración nuevos clave: + +- `audit_prepare_writes_unified_prompt_to_dot_straymark_audits_path` — verifica que `--prepare` escribe a la ubicación nueva. +- `audit_merge_reports_handles_n_reports` — verifica con 2, 3, y 4 reports en el directorio. +- `audit_merge_reports_warns_on_single_report` — verifica que `audit-review` emite warning si solo encuentra 1 report (heterogeneidad insuficiente). +- `audit_resolver_skips_placeholders_inside_html_comments` — R10 regression test. +- `audit_default_range_uses_origin_main_when_available` — R11(A) test. +- `audit_default_range_falls_back_to_head_minus_one_when_no_origin_main` — R11(A) fallback test. +- `audit_deprecated_calibrate_flag_emits_warning_and_continues` — backwards compat shim. + +### 5.3 Verificación end-to-end + +Antes de bumpear y release: + +1. Sandbox local: `cargo install --path cli/`, `straymark init /tmp/sandbox-v1`, crear Charter ficticio multi-commit, ejercitar el flujo completo con fixtures. +2. Cross-language paridad de skills y docs. +3. Backwards compat: invocar `straymark charter audit --calibrate` y verificar warning + redirect. +4. Schema validation: report con `audit_role: auditor-primary` (v0) es rechazado por validator v1 con error claro. + +--- + +## 6. Versionado y release + +**Bump:** + +- `cli-3.10.0` (minor) — nuevos flags, paths canónicos cambiados, R10 + R11(A) fixes incluidos. Backwards compat shims con deprecation warnings. +- `fw-4.9.0` (minor) — nuevo skill, plantilla unificada, deletion de plantillas v0, schema audit-output ajustado. + +**CHANGELOG combined section:** + +`## Framework 4.9.0 / CLI 3.10.0 — Audit v1: CLI-driven flow with tool-use discipline` + +Sección detallada cubriendo: +- Added (Framework): nuevo skill `straymark-audit-execute`, plantilla unificada. +- Added (CLI): `--prepare`, `--merge-reports`, soporte para N reports. +- Changed (CLI): `git_range` default `origin/main..HEAD`, paths canónicos a `.straymark/audits/`. +- Fixed (CLI): R10 resolver bug. +- Deprecated (CLI): `--calibrate`, `--finalize` (con warning + redirect). +- Removed (Framework): plantillas `auditor-primary.md`, `auditor-secondary.md`, `calibrator-reconciler.md`. +- BREAKING (Framework): convención de paths cambia (`audit/` → `.straymark/audits/`). Audits v0 paused (Sentinel CHARTER-07) deben re-correrse bajo v1. +- Crédito explícito a José Villaseñor Montfort (operador Sentinel/StrayMark) por los skills `audit/SKILL.md` y `audit-review/SKILL.md` mature pre-StrayMark contribuidos vía issue #102. Las 7 secciones universales de `audit-prompt.md` y la estructura de 6 secciones del review consolidado v1 se basan integralmente en ese material; los hardcodes específicos a Sentinel se parametrizaron contra Charter doc + originating AILOGs + git range. Ejemplos didácticos (Etapa 12 Pub/Sub stub) preservados con rótulo de caso real. + +**Tags y release workflows:** `fw-4.9.0` y `cli-3.10.0` push, los workflows de release-cli.yml + release-framework.yml ejecutan, binarios cross-platform y ZIP framework publican. + +--- + +## 7. Lo que NO está en alcance v1 + +Para preservar foco y no inflar la iteración: + +- **No HTTP API clients propios.** Decisión A1 sigue. StrayMark no maneja API keys, no invoca APIs, no mantiene HTTP clients. La CLI auditora del operador hace todo eso. +- **No `--strict-citations` enforcement.** Findings sin citas se marcan `low-confidence` pero no se rechazan automáticamente. Validar la utilidad de la citación es trabajo de Phase 2 telemetría. +- **No detección automática de "qué CLI auditora tiene el operador".** El operador instala lo que quiere; el skill se invoca y funciona si está disponible. +- **No multi-Charter audit batch** (`straymark charter audit CHARTER-07,CHARTER-08`). Si el patrón emerge, propuesta separada. +- **No re-audit support** (rerunear un cycle audit cuando ya existe `external_audit:` en telemetry). El v0 también lo rechaza; v1 mantiene la decisión hasta que un caso operativo concreto la justifique. +- **No automatización del `git diff` review post-merge.** El operador revisa manualmente; ese es el design. +- **No migración automática de Sentinel.** El operador (re)ejecuta los comandos manualmente en CHARTER-07 cuando v1 ship — no hay tooling de migración specific to Sentinel. + +--- + +## 8. Próximos pasos + +**Inmediato (esta sesión, si el operador aprueba la propuesta):** + +1. Solicitar al operador el prompt mature de Sentinel pre-StrayMark (lo ofreció en issue #102) para incorporarlo como base de la plantilla unificada. +2. Iniciar implementación PR-by-PR según §5.1. + +**Sentinel mientras tanto:** + +- CHARTER-07 sigue paused (correctamente). +- CHARTERs 08-13 pueden continuar bajo v0 si urgencia, pero conviene esperar v1 para tener un dataset Phase 2 coherente. Decisión del operador. + +**Post-release v1:** + +- Sentinel re-corre CHARTER-07 audit bajo v1. +- Sentinel continúa Etapa 2 desde CHARTER-08 bajo v1. +- Phase 2 telemetría agregada al cierre de CHARTER-13 incluye CHARTER-07 v1 + CHARTERs 08-13 v1 — dataset coherente, ~7 cycles audit en un solo flujo unificado. +- Esa data alimenta las decisiones §9 promote/defer/discard del rollout audit-skills. + +--- + +## 9. Riesgos + +**R1 — La plantilla unificada con disciplina tool use es más larga que la v0.** Más tokens de input por audit cycle. +*Mitigación:* la disciplina justifica el costo (substantive findings vs vacuamente vacíos). El operador puede decidir no auditar Charters de bajo riesgo (heurística NO del checkpoint sigue aplicando). + +**R2 — Adoptantes sin CLI auditora disponible.** Algunos adoptantes solo tienen acceso a chat web (claude.ai, chatgpt, gemini.google.com). +*Mitigación:* el flujo agnóstico de modo (D10) permite paste manual: el operador genera el prompt, lo pega en chat, copia el response al path canónico con el naming correcto, y `audit-review` lo procesa igual. Funciona, solo sin la garantía de tool use. + +**R3 — Diferentes CLIs auditoras tienen conventions distintas para invocar skills.** `claude-code` lee `.claude/skills/`, `gemini-cli` lee `.gemini/skills/`, etc. +*Mitigación:* StrayMark ya distribuye los skills en las 3 ubicaciones. CLIs no soportadas usan el `.agent/workflows/` genérico. Si un adoptante usa una CLI no cubierta, levanta issue, agregamos. + +**R4 — El operador puede mezclar reports v0 y v1 accidentalmente.** Si un adoptante upgrade mid-Charter y queda con `auditor-primary.md` (v0) y `report-claude-sonnet-4-6.md` (v1) en directorios paralelos. +*Mitigación:* el skill `audit-review` v1 solo busca en `.straymark/audits//`. Los archivos v0 quedan en `audit/charters//` ignorados. Documentación adopter explica. + +**R5 — La eliminación de la plantilla `calibrator-reconciler.md` puede confundir a operadores que esperaban verla.** +*Mitigación:* CHANGELOG explícito + sección en CLI-REFERENCE explicando que el rol calibrator ahora lo cumple el agente principal in-conversation, no una plantilla separada. + +**R6 — Disciplina de `path:line` puede generar friction si el modelo audita pero olvida citar.** Findings se marcan low-confidence aunque sean válidos. +*Mitigación:* el prompt unificado lo enuncia tres veces (en Disciplina, en Output Format, en Examples). Si aún así fail, telemetría lo captura (`evidence_citations: 0` en frontmatter). + +--- + +## 10. Criterios de éxito + +La iteración v1 cierra con éxito cuando: + +- [ ] Sentinel re-corre CHARTER-07 audit bajo v1 y reporta findings substantivos (≥1 finding `implementation_gap` o `real_debt` con citas `path:line` válidas) — confirma que la limitación R11(B) se resolvió. +- [ ] Sentinel completa Etapa 2 (CHARTERs 08-13) bajo v1 y la telemetría agregada del snapshot final tiene ≥6 records audit, todos con `evidence_citations: > 0` en al menos uno de los reports — confirma que la disciplina tool use es operativa en el flujo. +- [ ] Cero issues abiertas en el repo StrayMark atribuibles a regresión introducida por v1 — confirma que el bump no rompió funcionalidad existente. +- [ ] El skill `straymark-audit-execute` se ejecuta correctamente en al menos 2 CLIs auditoras distintas (claude-code, gemini-cli o copilot-cli) — confirma multi-CLI compatibility. +- [ ] El `review.md` consolidado producido por v1 contiene las 6 secciones (Resumen ejecutivo / Definición de alcance / Evaluación por auditoría / Plan de remediación P0-P4 / Hallazgos descartados / Calificación de auditores) y al menos 1 ítem en el plan de remediación con archivo:línea, descripción concreta y complejidad estimada — confirma que el delivery al humano supera al YAML mergeado del v0. +- [ ] El operador completa al menos 1 cycle audit sin escribir manualmente ningún path en cualquier comando ni copiar-pegar contenido entre CLIs — confirma que el flujo zero-friction de D14 funciona. + +Si todo lo anterior se cumple, v1 es señal fuerte para considerar transición v0 → v1 estable del schema audit en el siguiente cycle de roadmap (gated por segundo dominio según principio #12, pero la evidencia operativa de Sentinel es suficiente para preparar la propuesta). + +--- + +*v0.2 cierra la design phase. Los 14 puntos de §2 (decisiones de diseño) están aprobados por el operador en sesión de revisión post-issue #102; las consecuencias operativas en §3-§7 fluyen de ellas. La implementación que sigue ejecuta esto, no diseña sobre la marcha. La próxima versión (v0.3) se escribirá tras la implementación completa y el primer re-run de CHARTER-07 en Sentinel, con observaciones operativas que la implementación generó pero que el diseño no anticipó.* diff --git a/docs/i18n/es/README.md b/docs/i18n/es/README.md index 5b1fa03..667db82 100644 --- a/docs/i18n/es/README.md +++ b/docs/i18n/es/README.md @@ -87,7 +87,7 @@ Las decisiones de producto de StrayMark se anclan en doce principios explícitos 11. **La comunidad cuida la herramienta, no al revés.** Las contribuciones y el feedback se toman en serio sin volverse democracia. 12. **La velocidad del producto es la velocidad del aprendizaje.** Sin cristalización prematura; los schemas marcados `v0` hasta validarse contra un segundo dominio. -El documento completo, con anotaciones empíricas de los ciclos de validación, vive en [`Propuesta/straymark-design-principles.md`](https://github.com/StrangeDaysTech/straymark/blob/main/Propuesta/straymark-design-principles.md). +El documento completo, con anotaciones empíricas de los ciclos de validación, vive en [`docs/i18n/es/contributors/DESIGN-PRINCIPLES.md`](https://github.com/StrangeDaysTech/straymark/blob/main/docs/i18n/es/contributors/DESIGN-PRINCIPLES.md). --- diff --git a/Propuesta/devtrail-design-principles.md b/docs/i18n/es/contributors/DESIGN-PRINCIPLES.md similarity index 77% rename from Propuesta/devtrail-design-principles.md rename to docs/i18n/es/contributors/DESIGN-PRINCIPLES.md index 71b686d..52618ac 100644 --- a/Propuesta/devtrail-design-principles.md +++ b/docs/i18n/es/contributors/DESIGN-PRINCIPLES.md @@ -1,10 +1,11 @@ -# DevTrail — Principios de diseño +# StrayMark — Principios de diseño **Versión:** 0.2.2 (anotaciones empíricas + pase editorial para legibilidad pública: las referencias internas a artefactos de Sentinel se generalizan; rename Plan → Charter en vocabulario going-forward) **Fecha:** 2 de mayo de 2026 **Autor:** Jose Villaseñor Montfort — StrangeDaysTech **Propósito:** Articular la filosofía del producto en forma compacta, para servir como referencia frente a decisiones de diseño y como criterio para decir no a features que no encajan. -**Documentos relacionados:** `devtrail-thesis-validation.md` (cuerpo de evidencia que motivó las anotaciones de v0.2). +**Documentos relacionados:** `straymark-thesis-validation.md` (cuerpo de evidencia que motivó las anotaciones de v0.2; preservado en `docs/decisions/proposals/`). +**Idiomas:** [English](../../../contributors/DESIGN-PRINCIPLES.md) | Español | [简体中文](../../zh-CN/contributors/DESIGN-PRINCIPLES.md) --- @@ -12,17 +13,17 @@ Los productos de software derivan, con el tiempo, hacia donde los empuja el incentivo más cercano. Si la presión es revenue, derivan hacia features que venden. Si la presión es adopción, derivan hacia features que viralizan. Si la presión es competencia, derivan hacia paridad con el competidor más visible. Cada una de esas derivas es individualmente racional y colectivamente destructiva: el producto pierde su forma original y se convierte en otro punto promediado del mercado. -Este documento existe para que DevTrail tenga un ancla explícita. Las decisiones futuras deben poder contrastarse contra estos principios. Una feature que viole un principio puede aún ser buena idea, pero requiere una conversación consciente sobre qué principio se está flexibilizando y por qué. La existencia del documento no garantiza disciplina; la pregunta consciente que genera, sí. +Este documento existe para que StrayMark tenga un ancla explícita. Las decisiones futuras deben poder contrastarse contra estos principios. Una feature que viole un principio puede aún ser buena idea, pero requiere una conversación consciente sobre qué principio se está flexibilizando y por qué. La existencia del documento no garantiza disciplina; la pregunta consciente que genera, sí. Los principios están ordenados por jerarquía: cuando dos entran en conflicto, gana el que viene antes. -**Versión 0.2 — anotaciones empíricas.** Esta versión incorpora aprendizajes del primer experimento que estresa los principios contra evidencia: seis ciclos de ejecución sobre un proyecto adoptante real (Sentinel — un sistema Go backend), con tres iteraciones del formato del Charter (v1 → v2 → v3) y dos auditorías externas duales por ciclo. Las anotaciones por principio se concentran en los tres que el experimento ejercitó directamente (#6, #9, #12); la jerarquía y la redacción de los doce principios no cambian. La evidencia detallada vive en `devtrail-thesis-validation.md`. +**Versión 0.2 — anotaciones empíricas.** Esta versión incorpora aprendizajes del primer experimento que estresa los principios contra evidencia: seis ciclos de ejecución sobre un proyecto adoptante real (Sentinel — un sistema Go backend), con tres iteraciones del formato del Charter (v1 → v2 → v3) y dos auditorías externas duales por ciclo. Las anotaciones por principio se concentran en los tres que el experimento ejercitó directamente (#6, #9, #12); la jerarquía y la redacción de los doce principios no cambian. La evidencia detallada vive en `straymark-thesis-validation.md`. --- ## 1. La herramienta sirve al oficio, no al producto -DevTrail existe para que el ingeniero que trabaja con agentes de IA produzca trabajo del que se sienta orgulloso. Esa es la métrica final. Cualquier feature que mejore métricas de adopción, retención o revenue a costa de degradar la calidad del trabajo del usuario es una feature que viola el principio fundacional. +StrayMark existe para que el ingeniero que trabaja con agentes de IA produzca trabajo del que se sienta orgulloso. Esa es la métrica final. Cualquier feature que mejore métricas de adopción, retención o revenue a costa de degradar la calidad del trabajo del usuario es una feature que viola el principio fundacional. En la práctica, esto significa que las decisiones se toman con la pregunta *"¿esto ayuda al ingeniero a hacer mejor ingeniería?"*, no con la pregunta *"¿esto crece el producto?"*. Las dos preguntas a veces convergen y a veces no. Cuando divergen, gana la primera. @@ -40,7 +41,7 @@ Cuando exista una capa comercial (Cloud, hosting, servicios), debe ofrecer valor ## 4. El cumplimiento regulatorio es un side effect, no el producto -ISO/IEC 42001, EU AI Act, NIST AI RMF, GDPR son frameworks útiles que dan estructura a la documentación. DevTrail los soporta como capa opcional porque son valiosos para usuarios que los necesitan. Pero el producto no es "una herramienta de compliance". El producto es una herramienta de ingeniería que produce, como subproducto, evidencia compatible con esos frameworks. +ISO/IEC 42001, EU AI Act, NIST AI RMF, GDPR son frameworks útiles que dan estructura a la documentación. StrayMark los soporta como capa opcional porque son valiosos para usuarios que los necesitan. Pero el producto no es "una herramienta de compliance". El producto es una herramienta de ingeniería que produce, como subproducto, evidencia compatible con esos frameworks. Esta distinción importa porque el comprador de compliance y el ingeniero que usa la herramienta tienen necesidades distintas. Cuando el producto se posiciona como compliance, las decisiones de diseño se sesgan hacia el comprador de compliance y degradan el flujo del ingeniero. Mantener el cumplimiento como side effect protege la calidad del flujo principal. @@ -52,11 +53,11 @@ Las consecuencias prácticas son que cambios breaking en schemas son raros y del ## 6. Disciplina cognitiva sobre productividad bruta -DevTrail no compite con herramientas que prometen *"haz código 10x más rápido con IA"*. Compite, si compite con algo, contra el caos que el código rápido con IA genera en proyectos serios. La métrica que importa no es velocidad bruta del agente sino calidad sostenida del sistema producido. +StrayMark no compite con herramientas que prometen *"haz código 10x más rápido con IA"*. Compite, si compite con algo, contra el caos que el código rápido con IA genera en proyectos serios. La métrica que importa no es velocidad bruta del agente sino calidad sostenida del sistema producido. Esto significa que features que añaden fricción justificada (validaciones, gates, requerimientos de documentación, pre-trabajo antes de planning) son aceptables y a veces deseables. Features que prometen quitar fricción a costa de la calidad del razonamiento del agente son sospechosas por defecto. -**Anotación v0.2 — distinción virtud vs ceremonia.** La evidencia empírica reveló que no toda fricción del flujo tiene el mismo carácter. La fricción es *virtuosa* cuando externaliza señal pública verificable por terceros: nombrar formalmente los riesgos emergentes durante ejecución hace que auditores externos heterogéneos los capturen; un drift-check ejecutado al cierre del trabajo detecta archivos declarados-vs-modificados con cero falsos positivos en validación empírica; la auditoría dual con dos modelos heterogéneos calibra cross-modelo y captura gaps que un solo auditor pierde. La fricción es *ceremonia atacable* cuando solo genera triage manual o prescribe sin permitir adaptación al contexto: una plantilla rígida que choca con la convención del módulo destino, o un drift-check alertando sobre divergencias ya documentadas en otra parte, son los dos casos observados. La primera se mantiene; la segunda es bug del formato, no virtud del principio. La evidencia detallada y los criterios accionables viven en `devtrail-thesis-validation.md` §5. +**Anotación v0.2 — distinción virtud vs ceremonia.** La evidencia empírica reveló que no toda fricción del flujo tiene el mismo carácter. La fricción es *virtuosa* cuando externaliza señal pública verificable por terceros: nombrar formalmente los riesgos emergentes durante ejecución hace que auditores externos heterogéneos los capturen; un drift-check ejecutado al cierre del trabajo detecta archivos declarados-vs-modificados con cero falsos positivos en validación empírica; la auditoría dual con dos modelos heterogéneos calibra cross-modelo y captura gaps que un solo auditor pierde. La fricción es *ceremonia atacable* cuando solo genera triage manual o prescribe sin permitir adaptación al contexto: una plantilla rígida que choca con la convención del módulo destino, o un drift-check alertando sobre divergencias ya documentadas en otra parte, son los dos casos observados. La primera se mantiene; la segunda es bug del formato, no virtud del principio. La evidencia detallada y los criterios accionables viven en `straymark-thesis-validation.md` §5 (preservado en `docs/decisions/proposals/`). ## 7. Local-first, Cloud como amplificador @@ -66,7 +67,7 @@ Un usuario que nunca conecta al Cloud debe poder obtener la mayor parte del valo ## 8. La memoria del proyecto vive en el repo, no en una base de datos externa -AILOGs, ADRs, AIDECs, Charters y bundles viven como archivos versionados junto al código. La razón es estructural: la memoria del proyecto debe sobrevivir al producto que la generó. Si DevTrail desaparece mañana, los `.devtrail/` siguen siendo legibles, parseable y útiles porque son markdown estructurado y JSON conformante a schemas públicos. +AILOGs, ADRs, AIDECs, Charters y bundles viven como archivos versionados junto al código. La razón es estructural: la memoria del proyecto debe sobrevivir al producto que la generó. Si StrayMark desaparece mañana, los `.straymark/` siguen siendo legibles, parseable y útiles porque son markdown estructurado y JSON conformante a schemas públicos. Esta decisión renuncia a algunas capacidades que serían más fáciles con backend centralizado (por ejemplo, búsqueda full-text instantánea sin sincronización), pero gana confiabilidad de largo plazo y control del usuario sobre sus propios datos. La asimetría es deliberada y permanente. @@ -76,29 +77,29 @@ Cuando dos diseños cumplen el mismo objetivo, gana el más simple. Cuando una f Esto se aplica tanto al producto como al lenguaje del producto. Los nombres de comandos, tipos de documento y conceptos del framework se eligen para ser inmediatamente comprensibles, no para sonar técnicamente sofisticados. Si un concepto requiere explicación larga para un usuario nuevo, probablemente está mal diseñado. -**Anotación v0.2 — bash antes que framework cuando bash basta.** La evidencia empírica demostró que un script bash de ~145 líneas (awk + grep + git) cubre el caso "drift de archivos declarados vs modificados" con cero falsos positivos sobre dos tests. La decisión consciente de no implementarlo inicialmente en el lenguaje del CLI (Rust) se justifica así: bash es zero-build, sin dependencies adicionales, inspeccionable in situ; el costo de mantenimiento es bajo. Cuando se porte al CLI en la fase 2 del roadmap (`devtrail-cli-roadmap.md`), preservar la simplicidad bash en lo posible — invocar el shell desde Rust o reimplementar con cuidado de no inflar la lógica. La complejidad solo se cristaliza cuando el patrón de uso lo demande, no por defecto. +**Anotación v0.2 — bash antes que framework cuando bash basta.** La evidencia empírica demostró que un script bash de ~145 líneas (awk + grep + git) cubre el caso "drift de archivos declarados vs modificados" con cero falsos positivos sobre dos tests. La decisión consciente de no implementarlo inicialmente en el lenguaje del CLI (Rust) se justifica así: bash es zero-build, sin dependencies adicionales, inspeccionable in situ; el costo de mantenimiento es bajo. Cuando se porte al CLI en la fase 2 del roadmap (`straymark-cli-roadmap.md`, preservado en `docs/decisions/proposals/`), preservar la simplicidad bash en lo posible — invocar el shell desde Rust o reimplementar con cuidado de no inflar la lógica. La complejidad solo se cristaliza cuando el patrón de uso lo demande, no por defecto. ## 10. Honestidad sobre lo que la herramienta no hace -DevTrail no evalúa modelos. No es un LLM gateway. No reemplaza al juicio del ingeniero. No previene todas las alucinaciones. No certifica automáticamente cumplimiento regulatorio. Las páginas del producto, la documentación y la comunicación pública son explícitas sobre estos límites. +StrayMark no evalúa modelos. No es un LLM gateway. No reemplaza al juicio del ingeniero. No previene todas las alucinaciones. No certifica automáticamente cumplimiento regulatorio. Las páginas del producto, la documentación y la comunicación pública son explícitas sobre estos límites. La razón es práctica: usuarios que adoptan la herramienta con expectativas realistas la mantienen. Usuarios que la adoptan creyendo que hace cosas que no hace la abandonan frustrados. La honestidad temprana sobre los límites es mejor inversión de marketing que las promesas amplias. ## 11. La comunidad cuida la herramienta, no al revés -Los usuarios de DevTrail son ingenieros que típicamente saben más que el equipo del producto sobre sus propios casos de uso. Las contribuciones, issues y feedback se tratan con respeto profesional, y las decisiones de roadmap se toman incorporando esa visión. No de forma democrática (el producto necesita una visión coherente), pero sí como input serio. +Los usuarios de StrayMark son ingenieros que típicamente saben más que el equipo del producto sobre sus propios casos de uso. Las contribuciones, issues y feedback se tratan con respeto profesional, y las decisiones de roadmap se toman incorporando esa visión. No de forma democrática (el producto necesita una visión coherente), pero sí como input serio. Esto no significa hacer todo lo que la comunidad pide. Significa explicar cuándo se dice no y por qué, mantener la conversación visible y pública, y aceptar que el producto será mejor por la presión inteligente de quienes lo usan en serio que por las decisiones aisladas del equipo. ## 12. La velocidad del producto es la velocidad del aprendizaje -DevTrail no debe avanzar más rápido de lo que aprendemos sobre cómo se usa realmente. Cristalizar features prematuramente, antes de tener datos de uso real en al menos tres proyectos distintos, genera costos altos de mantenimiento sobre features que pueden ser equivocadas. La paciencia de esperar evidencia es disciplina, no inacción. +StrayMark no debe avanzar más rápido de lo que aprendemos sobre cómo se usa realmente. Cristalizar features prematuramente, antes de tener datos de uso real en al menos tres proyectos distintos, genera costos altos de mantenimiento sobre features que pueden ser equivocadas. La paciencia de esperar evidencia es disciplina, no inacción. Esto se traduce en una preferencia explícita por: prototipos antes que features, observación antes que cristalización, schemas estables sobre features cambiantes, y evolución incremental sobre rewrites grandes. **Anotación v0.2 — el espíritu del N≥3 frente a evidencia inicial limitada.** La evidencia empírica disponible al momento de escribir esta versión proviene de un solo proyecto adoptante, en un solo dominio (Go backend), con un solo autor. Aplicado literalmente, el principio bloquearía cualquier cristalización a partir de esa evidencia. Aplicado al espíritu — observación rigurosa antes que cristalización, evolución incremental con datos reales — la evidencia disponible cubre tres ejes de diversidad estructural: (a) escala variable de las unidades de trabajo (XS, S, M en cinco ciclos), (b) iteración del formato bajo presión empírica (v1 → v2 → v3, cada una derivada del ciclo anterior), (c) calibración cross-modelo de auditores (dos modelos heterogéneos convergiendo a scores similares en el ciclo más estresado). Estos seis ciclos × tres formatos × tres escalas son evidencia equivalente al N≥3 que el principio busca proteger. -Lo que sigue sin diversificar es el dominio. Para preservar el principio en su forma operacional: cualquier schema que se cristalice a partir de esa evidencia se publica como `v0.json` con marca *experimental*. La transición a `v1.0` estable requiere validación con un segundo proyecto en otro dominio (frontend, ML pipeline, infra-as-code). Cualquier feature que dependa de un supuesto sin evidencia — como el supuesto de aprobaciones condicionales, que requiere flujo multi-actor y la evidencia disponible no lo ejercitó — queda explícitamente bloqueada hasta tener un proyecto que sí lo ejerza. Ver `devtrail-thesis-validation.md` §6 y §8 para el desarrollo del argumento y la lista de gaps específicos por supuesto. +Lo que sigue sin diversificar es el dominio. Para preservar el principio en su forma operacional: cualquier schema que se cristalice a partir de esa evidencia se publica como `v0.json` con marca *experimental*. La transición a `v1.0` estable requiere validación con un segundo proyecto en otro dominio (frontend, ML pipeline, infra-as-code). Cualquier feature que dependa de un supuesto sin evidencia — como el supuesto de aprobaciones condicionales, que requiere flujo multi-actor y la evidencia disponible no lo ejercitó — queda explícitamente bloqueada hasta tener un proyecto que sí lo ejerza. Ver `straymark-thesis-validation.md` §6 y §8 (preservado en `docs/decisions/proposals/`) para el desarrollo del argumento y la lista de gaps específicos por supuesto. **Patrón meta-meta detectado — auto-evolución del formato.** La evidencia empírica reveló que el formato se mejora a sí mismo: cada Charter (Plan en terminología histórica) ejecutado genera datos que refinan el formato del próximo. Esto sugiere ampliar el principio en futuras versiones: la herramienta evoluciona consigo misma; cada uso es input para la próxima versión. Por ahora se documenta como observación, no como principio adicional, hasta que un segundo proyecto confirme el patrón. diff --git a/docs/i18n/es/contributors/README.md b/docs/i18n/es/contributors/README.md new file mode 100644 index 0000000..0182689 --- /dev/null +++ b/docs/i18n/es/contributors/README.md @@ -0,0 +1,41 @@ +# Documentación para contribuidores + +Recursos para personas que contribuyen a StrayMark — ya sea leyendo el código, escribiendo traducciones, proponiendo cambios, o tratando de entender el *por qué* detrás de la forma del framework. + +**Idiomas:** [English](../../../contributors/README.md) | Español | [简体中文](../../zh-CN/contributors/README.md) + +--- + +## Conceptos + +El material atemporal — leer esto para entender *qué* es StrayMark y *por qué* tiene la forma que tiene, antes de abrir un PR que toque la superficie del framework. + +| Documento | Qué cubre | +|---|---| +| [`DESIGN-PRINCIPLES.md`](DESIGN-PRINCIPLES.md) | Los doce principios jerárquicos que gobiernan las decisiones de producto. Incluye anotaciones empíricas v0.2 de los ciclos de validación en los principios #6 (disciplina cognitiva), #9 (simplicidad) y #12 (velocidad = velocidad del aprendizaje). | +| [`WHAT-IS-A-CHARTER.md`](WHAT-IS-A-CHARTER.md) | Alcance conceptual del artefacto Charter: una declaración ex-ante de una unidad de trabajo con contrato de verificación y ancla de auditoría. Mapea la frontera entre lo que cubre el `plan.md` de GitHub SpecKit y lo que cubre un Charter de StrayMark — no son lo mismo. | + +## Guías de flujo de trabajo + +| Documento | Qué cubre | +|---|---| +| [`TRANSLATION-GUIDE.md`](../../../contributors/TRANSLATION-GUIDE.md) | Reglas y convenciones para traducir la documentación de StrayMark a idiomas adicionales. Leer antes de enviar un PR que agregue o modifique un archivo de `i18n/`. *(Solo en inglés por ahora.)* | + +## Propuestas históricas (archivadas) + +Propuestas y roadmaps de la evolución del proyecto previa al CLI, preservadas como contexto — explican cómo emergió la forma actual. **No** se mantienen hacia adelante; la fuente canónica del comportamiento actual son el código, los schemas bajo `dist/.straymark/schemas/` y el CHANGELOG. Examinarlas en [`docs/decisions/proposals/`](../../../decisions/proposals/): + +| Archivo | Fecha del snapshot | Qué capturó | +|---|---|---| +| `2026-04-30-thesis-validation.md` | 2026-04-30 | Validación empírica de la tesis del producto contra seis ciclos de Sentinel (backend Go) — el cuerpo de evidencia que motivó las anotaciones v0.2 de `DESIGN-PRINCIPLES.md`. | +| `2026-04-30-charter-telemetry.md` | 2026-04-30 | Esquema de instrumentación de telemetría para observar la ejecución de Charters en proyectos reales. La versión normativa ahora vive en `dist/.straymark/schemas/charter-telemetry.schema.v0.json`. | +| `2026-05-03-cli-roadmap.md` | 2026-05-03 | Roadmap de implementación en tres fases del CLI Rust, con criterios de cierre. Las fases 1–3 ya están shippeadas en `cli-3.x`. | +| `2026-05-03-audit-skills-design.md` | 2026-05-03 | Diseño de las skills `/straymark-audit-prompt` y `/straymark-audit-review` como checkpoints humano-en-el-loop. Implementado en `fw-4.8.0`. | +| `2026-05-03-audit-skills-rollout.md` | 2026-05-03 | Plan operacional de rollout de las audit skills (criterios de gating, telemetría, shipping por fases). | +| `2026-05-04-audit-cli-flow.md` | 2026-05-04 | Rediseño del flujo de auditoría externa tras el primer encuentro empírico con un Charter L multi-commit (Sentinel CHARTER-07). Implementado en `cli-3.10+`. | + +Los ADRs (registros de decisión arquitectónica) del código actual viven en [`docs/decisions/`](../../../decisions/) un nivel más arriba. + +--- + +*Ver también: [`../adopters/`](../adopters/) para documentación dirigida a equipos que adoptan StrayMark en sus propios proyectos, incluyendo [`ADOPTION-GUIDE.md`](../adopters/ADOPTION-GUIDE.md), [`CLI-REFERENCE.md`](../adopters/CLI-REFERENCE.md) y [`WORKFLOWS.md`](../adopters/WORKFLOWS.md).* diff --git a/Propuesta/que-es-un-charter.md b/docs/i18n/es/contributors/WHAT-IS-A-CHARTER.md similarity index 63% rename from Propuesta/que-es-un-charter.md rename to docs/i18n/es/contributors/WHAT-IS-A-CHARTER.md index 439c8a5..e1d3d40 100644 --- a/Propuesta/que-es-un-charter.md +++ b/docs/i18n/es/contributors/WHAT-IS-A-CHARTER.md @@ -1,14 +1,15 @@ -# Qué es un "Charter" en DevTrail (y dónde encaja respecto a GitHub SpecKit) +# Qué es un "Charter" en StrayMark (y dónde encaja respecto a GitHub SpecKit) **Versión:** 0.2 (rename Plan → Charter) **Fecha:** 30 de abril de 2026 **Autor:** Jose Villaseñor Montfort — StrangeDaysTech **Propósito:** Fijar el alcance conceptual del artefacto **Charter** tal como emerge del experimento Sentinel (donde se llamó *Plan*), y explicar cómo coexiste con flujos de diseño y desarrollo que ya usan SpecKit (spec → plan → tasks). -**Documentos relacionados:** `devtrail-cli-roadmap.md` (§3 Fase 1, §6 mapeo Sentinel→CLI), `devtrail-thesis-validation.md`, `devtrail-charter-telemetry.md`, `sentinel/docs/plans/TEMPLATE.md` v3, `sentinel/docs/plans/README.md`. +**Idiomas:** [English](../../../contributors/WHAT-IS-A-CHARTER.md) | Español | [简体中文](../../zh-CN/contributors/WHAT-IS-A-CHARTER.md) +**Documentos relacionados:** `straymark-cli-roadmap.md` (§3 Fase 1, §6 mapeo Sentinel→CLI), `straymark-thesis-validation.md`, `straymark-charter-telemetry.md` — todos preservados en `docs/decisions/proposals/` para referencia histórica. --- -## 1. Qué es un Charter en DevTrail +## 1. Qué es un Charter en StrayMark **Una declaración ex-ante de una unidad de trabajo, lo bastante grande como para merecer un contrato verificable y una auditoría ex-post.** @@ -16,7 +17,7 @@ El Charter tiene tres caras simultáneas: 1. **Contrato de scope** (Context + Scope in/out + Archivos a modificar + Riesgos): qué se va a tocar y, deliberadamente, qué *no*. La sección `Out of scope` existe específicamente para que auditores externos no lo clasifiquen como gap. 2. **Contrato de verificación** (Local checks + Production smoke): comandos ejecutables literal, separados por *cuándo aplican*. El split Local/Prod no es estilo — emerge de que en 3/3 ciclos los auditores externos clasificaban fallos prod-only como `real_debt`. -3. **Ancla de auditoría** (frontmatter + Cierre del Charter + drift check): el Charter es el sujeto sobre el que `devtrail charter drift` y `devtrail charter audit` operan. Sin Charter no hay nada que auditar. +3. **Ancla de auditoría** (frontmatter + Cierre del Charter + drift check): el Charter es el sujeto sobre el que `straymark charter drift` y `straymark charter audit` operan. Sin Charter no hay nada que auditar. ### 1.1 No es solo deuda técnica @@ -40,13 +41,13 @@ El patrón emergió empíricamente de PLAN-07 de Sentinel (cerrado 2026-05-02), ## 2. Por qué se llama "Charter" y no "Plan" -DevTrail llamó originalmente a este artefacto **Plan** durante el experimento Sentinel (abril 2026). El término se renombró a **Charter** antes de la implementación en el CLI por una razón pragmática: GitHub SpecKit ya usa la palabra "plan" (`/speckit.plan`, `plan.md`) para un artefacto distinto, y la colisión nominal generaba fricción en docs adopters que combinan ambos flujos. +StrayMark llamó originalmente a este artefacto **Plan** durante el experimento Sentinel (abril 2026). El término se renombró a **Charter** antes de la implementación en el CLI por una razón pragmática: GitHub SpecKit ya usa la palabra "plan" (`/speckit.plan`, `plan.md`) para un artefacto distinto, y la colisión nominal generaba fricción en docs adopters que combinan ambos flujos. Los registros históricos de Sentinel (Plans 01-06, `sentinel/docs/plans/`, `sentinel/scripts/check-plan-drift.sh`, AILOGs y telemetrías YAML `PLAN-NN.telemetry.yaml`) preservan el nombre original — son evidencia empírica de un momento puntual en el tiempo, y reescribir la historia falsificaría el registro. Las referencias a esos archivos en este documento mantienen "Plan" deliberadamente. -El concepto que SpecKit llama "plan" y el que DevTrail llama "Charter" son artefactos distintos: +El concepto que SpecKit llama "plan" y el que StrayMark llama "Charter" son artefactos distintos: -| | **SpecKit `plan.md`** | **DevTrail Charter** | +| | **SpecKit `plan.md`** | **StrayMark Charter** | |---|---|---| | Granularidad | Feature completa (semanas, varias historias) | Unidad acotada (horas a días, una rama) | | Contenido dominante | Stack, dependencias, estructura de proyecto, gates de constitución | Archivos concretos a tocar, comandos de verificación, riesgos R | @@ -54,7 +55,7 @@ El concepto que SpecKit llama "plan" y el que DevTrail llama "Charter" son artef | Validación | Constitution Check (gate ex-ante) | Drift-check + auditoría externa (gates ex-post) | | Optimización | *Claridad upfront* | *Trazabilidad ex-post* | -Lo que SpecKit llama "plan" se parece más a un **ADR + skeleton arquitectónico**. Lo que DevTrail llama "Charter" se parece más a un **task-card con verificación contractual y ancla de auditoría**. +Lo que SpecKit llama "plan" se parece más a un **ADR + skeleton arquitectónico**. Lo que StrayMark llama "Charter" se parece más a un **task-card con verificación contractual y ancla de auditoría**. --- @@ -62,20 +63,20 @@ Lo que SpecKit llama "plan" se parece más a un **ADR + skeleton arquitectónico SpecKit es lineal y top-down: `/speckit.specify` → `/speckit.plan` → `/speckit.tasks` → implementar. -| SpecKit | Qué resuelve | Equivalente más cercano en DevTrail | +| SpecKit | Qué resuelve | Equivalente más cercano en StrayMark | |---|---|---| | `spec.md` (US, FRs, SCs) | *Qué* construir, agnóstico a tech | `01-requirements/REQ-*.md` | | `plan.md` (stack, estructura) | *Cómo* arquitectarlo | `02-design/ADR-*.md` | -| `tasks.md` (T001..TNNN) | *En qué orden* ejecutarlo | sección `## Tasks` dentro de un Charter DevTrail | +| `tasks.md` (T001..TNNN) | *En qué orden* ejecutarlo | sección `## Tasks` dentro de un Charter StrayMark | | (no existe) | Bitácora de ejecución | **AILOG** | -| (no existe) | Drift declarado vs. ejecutado | **`devtrail charter drift`** | -| (no existe) | Auditoría multi-modelo ex-post | **`devtrail charter audit`** | +| (no existe) | Drift declarado vs. ejecutado | **`straymark charter drift`** | +| (no existe) | Auditoría multi-modelo ex-post | **`straymark charter audit`** | -Las tres últimas filas son la contribución específica de DevTrail. SpecKit termina al producir `tasks.md`; lo que pasa después no le importa al framework — si la implementación se desvía del plan, no hay mecanismo que lo detecte. DevTrail entra exactamente ahí. +Las tres últimas filas son la contribución específica de StrayMark. SpecKit termina al producir `tasks.md`; lo que pasa después no le importa al framework — si la implementación se desvía del plan, no hay mecanismo que lo detecte. StrayMark entra exactamente ahí. --- -## 4. Tres modos en que un Charter DevTrail puede convivir con SpecKit +## 4. Tres modos en que un Charter StrayMark puede convivir con SpecKit ### Modo A — Greenfield con SpecKit como driver @@ -90,16 +91,16 @@ spec.md → plan.md → tasks.md → ┐ drift-check + audit ``` -Cada Charter DevTrail toma un subconjunto de tasks (típicamente una user story o una fase) y le añade las tres capas que SpecKit no provee: verificación ejecutable, declaración de archivos contra la que medir drift, y enganche con AILOG/auditoría. +Cada Charter StrayMark toma un subconjunto de tasks (típicamente una user story o una fase) y le añade las tres capas que SpecKit no provee: verificación ejecutable, declaración de archivos contra la que medir drift, y enganche con AILOG/auditoría. ### Modo B — Mantenimiento / post-MVP (caso real de Sentinel) -No hay SpecKit corriendo. Los Plans 01–06 de Sentinel nacen de AILOGs y backlog post-MVP, no de specs. El campo `Origen:` del Charter apunta a un AILOG, no a un `specs/###-feature/`. Aquí el Charter DevTrail es freestanding. +No hay SpecKit corriendo. Los Plans 01–06 de Sentinel nacen de AILOGs y backlog post-MVP, no de specs. El campo `Origen:` del Charter apunta a un AILOG, no a un `specs/###-feature/`. Aquí el Charter StrayMark es freestanding. ### Modo C — Híbrido (probablemente el más realista) -- Features mayores → flujo SpecKit completo + Charters DevTrail al ejecutar tasks. -- Bug fixes, gobernanza, deuda, cambios de contrato, features chicas → solo Charter DevTrail. +- Features mayores → flujo SpecKit completo + Charters StrayMark al ejecutar tasks. +- Bug fixes, gobernanza, deuda, cambios de contrato, features chicas → solo Charter StrayMark. Esto es coherente con lo que ya muestra Sentinel: de los Plans cerrados, ninguno tenía SpecKit upstream porque el MVP ya estaba spec'd y cerrado. Lo que quedaba era trabajo evolutivo, donde el ciclo Spec→Plan→Tasks es desproporcionado. @@ -109,25 +110,25 @@ Esto es coherente con lo que ya muestra Sentinel: de los Plans cerrados, ninguno **SpecKit responde a la pregunta:** *"¿Cómo descompongo una idea de producto en trabajo ejecutable?"* — optimiza para claridad upfront y paralelización de US. -**DevTrail Charter responde a la pregunta:** *"¿Cómo hago que una unidad de trabajo sea verificable, auditable y detectable cuando se desvía de lo declarado?"* — optimiza para evidencia ex-post. +**StrayMark Charter responde a la pregunta:** *"¿Cómo hago que una unidad de trabajo sea verificable, auditable y detectable cuando se desvía de lo declarado?"* — optimiza para evidencia ex-post. -Por eso no compiten: viven en momentos distintos del ciclo. SpecKit acaba en `tasks.md`; DevTrail Charter empieza ahí (cuando se aplica) o se sostiene solo (cuando no hay spec previa). La tesis Sentinel no es "esto reemplaza SpecKit" — es "esto cubre la fase post-tasks que SpecKit no cubre, y la cubre con un patrón de tres niveles (declaración + drift + auditoría heterogénea) que tiene evidencia empírica de capturar gaps que el implementador no documentó". +Por eso no compiten: viven en momentos distintos del ciclo. SpecKit acaba en `tasks.md`; StrayMark Charter empieza ahí (cuando se aplica) o se sostiene solo (cuando no hay spec previa). La tesis Sentinel no es "esto reemplaza SpecKit" — es "esto cubre la fase post-tasks que SpecKit no cubre, y la cubre con un patrón de tres niveles (declaración + drift + auditoría heterogénea) que tiene evidencia empírica de capturar gaps que el implementador no documentó". --- ## 6. Nota sobre la visión Studio: "Stage" no es sinónimo de Charter -`devtrail-studio-vision.md` introduce un término adicional, **Stage**, que conviene no confundir con Charter. No son sinónimos: viven en niveles distintos del ciclo. +`straymark-studio-vision.md` introduce un término adicional, **Stage**, que conviene no confundir con Charter. No son sinónimos: viven en niveles distintos del ciclo. -- **Stage** = etapa de trabajo que recorre las seis fases cognitivas del Studio (Spec → Implementation → Audit → Remediation → Governance → Closure & Deliver) y se cierra con un Closure Bundle firmado y hash-chained. Comandos propuestos en la visión: `devtrail stage open/close/status` (no implementados; corresponden al Hito 2 de la evolución hacia Studio). +- **Stage** = etapa de trabajo que recorre las seis fases cognitivas del Studio (Spec → Implementation → Audit → Remediation → Governance → Closure & Deliver) y se cierra con un Closure Bundle firmado y hash-chained. Comandos propuestos en la visión: `straymark stage open/close/status` (no implementados; corresponden al Hito 2 de la evolución hacia Studio). - **Charter** = unidad acotada con verificación + drift + ancla de auditoría — el artefacto que define este documento. Los Charters viven *dentro de* un Stage; un Stage típicamente contiene uno o varios Charters más sus tasks asociados. -La taxonomía implícita de la visión es de tres niveles: **Stage > Charter > Task**. El roadmap actual del CLI (`devtrail-cli-roadmap.md`, Fases 1-3) opera enteramente al nivel de Charter (lo que Sentinel llamó "Plan"), que es el nivel donde existe evidencia empírica de Sentinel. Stage entraría al CLI más adelante como capa adicional, no como rename de Charter. +La taxonomía implícita de la visión es de tres niveles: **Stage > Charter > Task**. El roadmap actual del CLI (`straymark-cli-roadmap.md` (preservado en `docs/decisions/proposals/`), Fases 1-3) opera enteramente al nivel de Charter (lo que Sentinel llamó "Plan"), que es el nivel donde existe evidencia empírica de Sentinel. Stage entraría al CLI más adelante como capa adicional, no como rename de Charter. -## 7. Implicación para el roadmap del CLI DevTrail +## 7. Implicación para el roadmap del CLI StrayMark -Vale la pena reflejarlo en cómo se documenta el comando `devtrail charter new` cuando llegue Fase 1 (`devtrail-cli-roadmap.md` §3.2). Hoy el flag previsto `--from-ailog ID` cubre el Modo B. Probablemente convenga tener también `--from-spec specs/###-feature/` para el Modo A — pre-popula `Origen:` apuntando al `spec.md` de SpecKit, y opcionalmente hereda US relevantes a la sección Context. Eso es ejercicio para Fase 1, no para resolver hoy, pero conviene anotarlo en este documento como decisión abierta para cuando se diseñe la subcomanda. +Vale la pena reflejarlo en cómo se documenta el comando `straymark charter new` cuando llegue Fase 1 (`straymark-cli-roadmap.md` §3.2 (preservado en `docs/decisions/proposals/`)). Hoy el flag previsto `--from-ailog ID` cubre el Modo B. Probablemente convenga tener también `--from-spec specs/###-feature/` para el Modo A — pre-popula `Origen:` apuntando al `spec.md` de SpecKit, y opcionalmente hereda US relevantes a la sección Context. Eso es ejercicio para Fase 1, no para resolver hoy, pero conviene anotarlo en este documento como decisión abierta para cuando se diseñe la subcomanda. --- -*Este documento captura el alcance conceptual del artefacto Charter (originalmente llamado "Plan" en el experimento Sentinel) tal como se entiende a finales de abril de 2026. La definición seguirá evolucionando conforme adoptantes fuera de Sentinel ejerciten el patrón en otros dominios — la versión 0.3 se escribirá tras observar al menos un proyecto adoptante completar un Charter con `devtrail charter` (criterio de salida de Fase 1).* +*Este documento captura el alcance conceptual del artefacto Charter (originalmente llamado "Plan" en el experimento Sentinel) tal como se entiende a finales de abril de 2026. La definición seguirá evolucionando conforme adoptantes fuera de Sentinel ejerciten el patrón en otros dominios — la versión 0.3 se escribirá tras observar al menos un proyecto adoptante completar un Charter con `straymark charter` (criterio de salida de Fase 1).* diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md index 8039dd9..253c460 100644 --- a/docs/i18n/zh-CN/README.md +++ b/docs/i18n/zh-CN/README.md @@ -87,7 +87,7 @@ StrayMark 的产品决策基于十二条明确的原则。它们按层级排序 11. **社区维护工具，而非反过来。** 贡献和反馈被认真对待，但不会变成民主决策。 12. **产品的速度等于学习的速度。** 不过早结晶化；schema 标记为 `v0`，直到在第二个领域得到验证。 -完整文档（包含来自验证周期的实证注解）见 [`Propuesta/straymark-design-principles.md`](https://github.com/StrangeDaysTech/straymark/blob/main/Propuesta/straymark-design-principles.md)。 +完整文档（包含来自验证周期的实证注解）见 [`docs/i18n/zh-CN/contributors/DESIGN-PRINCIPLES.md`](https://github.com/StrangeDaysTech/straymark/blob/main/docs/i18n/zh-CN/contributors/DESIGN-PRINCIPLES.md)。 --- diff --git a/docs/i18n/zh-CN/contributors/DESIGN-PRINCIPLES.md b/docs/i18n/zh-CN/contributors/DESIGN-PRINCIPLES.md new file mode 100644 index 0000000..b40f582 --- /dev/null +++ b/docs/i18n/zh-CN/contributors/DESIGN-PRINCIPLES.md @@ -0,0 +1,121 @@ +# StrayMark — 设计原则 + +**版本：** 0.2.2（实证注解 + 面向公开可读性的编辑修订：对 Sentinel 工件的内部引用已通用化；在前向词汇中将 Plan → Charter 重命名） +**日期：** 2026-05-02 +**作者：** Jose Villaseñor Montfort — StrangeDaysTech +**目的：** 以紧凑形式阐明产品哲学，作为设计决策的参考依据，以及对不相契合的功能说"不"的判断标准。 +**语言：** [English](../../../contributors/DESIGN-PRINCIPLES.md) | [Español](../../es/contributors/DESIGN-PRINCIPLES.md) | 简体中文 + +--- + +## 本文档为何存在 + +软件产品会随时间漂移，朝着推动力最强的激励方向。如果压力是营收，它们就漂向能卖钱的功能。如果压力是采用率，它们就漂向能病毒式传播的功能。如果压力是竞争，它们就漂向与最显眼竞品的对等。这每一种漂移单独看都是理性的，合在一起却是破坏性的：产品失去其原有形态，沦为市场上又一个被平均化了的点。 + +本文档存在的意义，是让 StrayMark 拥有一个明确的锚点。未来的决策必须能够对照这些原则进行检验。一项违反某条原则的功能仍可能是好主意，但需要一次有意识的对话——明确*哪条*原则正在被放宽、*为什么*。文档的存在并不保证纪律；它所迫使产生的有意识发问，才能保证。 + +原则按层级排序：当两条发生冲突时，靠前者胜出。 + +**0.2 版 — 实证注解。** 本版本纳入了第一次以证据应力测试这些原则后获得的经验：在一个真实采用方项目（Sentinel — 一个 Go 后端系统）上的六个执行周期，包括 Charter 格式的三次迭代（v1 → v2 → v3）以及每周期两次双外部审计。各原则的注解集中于实验直接演练的三条（#6、#9、#12）；十二条原则的层级与措辞不变。详细证据见 `straymark-thesis-validation.md`（出于历史参考目的保存在 `docs/decisions/proposals/` 中）。 + +--- + +## 1. 工具服务于手艺，而非产品自身 + +StrayMark 的存在是为了让与 AI Agent 协作的工程师产出令自己自豪的工作。这是最终的衡量标准。任何以降低用户工作质量为代价、改善采用、留存或营收指标的功能，都是违反这条根本原则的功能。 + +实践上，这意味着决策时所问的不是*"这能让产品更壮大吗？"*，而是*"这能帮工程师做出更好的工程吗？"*。两个问题有时一致，有时不一致。当它们分歧时，前者胜出。 + +## 2. 主要用户是编排 Agent 的资深工程师 + +不是工程副总裁。不是 CISO。不是合规官。主要用户是技术判断力强、借助 AI Agent 推进自己单独无法实际承担的项目、并需要外化的认知纪律以防止 Agent 引入系统性混乱的工程师。 + +功能为这个人设计。流程为这个人优化。文档为这个人撰写。当其他人（合规官、经理、审计员）最终使用产品时，他们是在一个首先尊重工程师的基础之上使用。颠倒这一层级，是开发者工具产品变质的最常见原因。 + +## 3. 严格开源，核心毫无附加条件 + +Framework、CLI 与 TUI 现在是、并将永远是宽松许可证下的开源。OSS 中没有为推动付费而被阉割的功能。没有强制遥测。没有完整使用所必需的账户要求。没有"社区版"在核心能力上劣于"企业版"的设定。 + +当未来存在商业层（Cloud、托管、服务）时，它必须提供真正附加的价值，而不是把 OSS 中本应包含的功能搬走、人为制造需求。诚实的 open-core 与 bait-and-switch 式 open-core 的区别，就在于对"什么是附加价值"与"什么是工具本身"是否诚实。 + +## 4. 法规合规是副作用，而非产品目标 + +ISO/IEC 42001、EU AI Act、NIST AI RMF、GDPR 是为文档化提供结构的有用框架。StrayMark 将其作为可选层来支持，因为它们对需要的用户有价值。但产品本身不是"一款合规工具"。产品是一款工程工具，它作为副产品产出与那些框架兼容的证据。 + +这一区分至关重要，因为合规购买者与使用工具的工程师有不同的需求。当产品被定位为合规工具时，设计决策会偏向合规购买者，从而损害工程师的工作流。把合规当作副作用，能够保护主流程的质量。 + +## 5. Schema 驱动优先于功能驱动 + +产品的核心实体（Stage Closure Bundle、Charter、Document）首先以严格版本化的正式 schema 定义。功能基于这些 schema 构建。这带来三个结构性收益：允许多个实现共存而无需互相协调；让演化变得受控且可逆；并迫使在实现之前先思考契约。 + +实践后果是：schema 的破坏性变更稀少且经过深思；schema 是产品的一等文档；任何需要违反 schema 的功能必须先提议 schema 的演化。 + +## 6. 认知纪律优先于原始生产力 + +StrayMark 不与那些承诺*"用 AI 把代码写快 10 倍"*的工具竞争。它若与什么对抗，对抗的是 AI 快速产出的代码在严肃项目中所制造的混乱。重要的不是 Agent 的原始速度，而是所产出系统的持续质量。 + +这意味着增加合理摩擦的功能（验证、关卡、文档要求、规划前的预备工作）是可接受的，有时甚至是可取的。承诺以牺牲 Agent 推理质量为代价去除摩擦的功能，默认就是可疑的。 + +**0.2 版注解 — 美德 vs 仪式的区分。** 实证证据揭示并非所有流程摩擦都具有相同性质。摩擦是*具备美德的*，当它将可被第三方核验的公共信号外化时：在执行中正式命名涌现的风险，使异质的外部审计员能够捕获它们；工作收尾时的 drift-check 在实证验证中以零误报检测出已声明 vs 实际修改的文件错配；用两个异质模型进行的双重审计能进行跨模型校准，并捕获单个审计员会遗漏的缺口。摩擦是*可被攻击的仪式*，当它仅产生人工分诊或开出处方而不允许根据上下文调整时：与目标模块惯例相冲突的死板模板，或对已在别处记录的偏差仍发出警报的 drift-check，是观察到的两种情形。前者保留；后者是格式的 bug，而非原则的美德。详细证据与可执行的判断标准见 `straymark-thesis-validation.md` §5（保存在 `docs/decisions/proposals/` 中）。 + +## 7. Local-first，Cloud 作为放大器 + +CLI 在本地仓库中可以完全离线工作。这是初次体验，也是其上构建一切的基础。Cloud 的存在是为了放大价值（跨仓聚合、签名证据、语义化历史检索、团队协作），但绝不替代 CLI，也绝不让其变成瘦客户端。 + +从未连接 Cloud 的用户也必须能够获得产品的大部分价值。这一安排保护工具不受 Cloud 故障模式的影响、不受商业模式变更的影响，也不受"始于本地、终于强制联网"这一产品经典漂移的影响。 + +## 8. 项目记忆存活于仓库中，而非外部数据库 + +AILOG、ADR、AIDEC、Charter 与 Bundle 作为版本化文件与代码并存。原因是结构性的：项目记忆必须能在产生它的产品之外继续存在。如果 StrayMark 明天消失，`.straymark/` 目录中的文件仍可读、可解析、可使用——因为它们是结构化的 markdown 与符合公开 schema 的 JSON。 + +这一决定放弃了集中式后端会更容易实现的若干能力（例如无需同步的瞬时全文检索），但换来了长期可靠性以及用户对自身数据的控制。这种不对称是经过深思的，且是永久的。 + +## 9. 简洁优先于能力 + +当两种设计满足同一目标时，更简单的胜出。当一项功能确有用处但需要显著的复杂度时，最好等到该使用模式至少在三个真实项目中得到验证之后，再将其结晶到产品中。 + +这同时适用于产品本身与产品的语言。命令名、文档类型、framework 概念都为新用户能够立即理解而选择，不为听起来技术上精巧而选择。如果一个概念对新用户需要冗长解释，多半是设计得不好。 + +**0.2 版注解 — 当 bash 已够用时优先 bash 而非 framework。** 实证证据表明，一段约 145 行的 bash 脚本（awk + grep + git）能以零误报覆盖"已声明文件 vs 实际修改文件的偏差"这一情形（基于两次测试）。在 CLI 的语言（Rust）中不优先实现该脚本的有意识决定，理由如下：bash 零构建、无额外依赖、可就地检查；维护成本低。当其在路线图（`straymark-cli-roadmap.md`，保存在 `docs/decisions/proposals/` 中）的第二阶段移植到 CLI 时，应尽可能保留 bash 的简洁——从 Rust 调用 shell，或在重新实现时小心不要让逻辑膨胀。复杂度只在使用模式确实要求时才结晶，而不是默认就结晶。 + +## 10. 对工具不做之事保持诚实 + +StrayMark 不评估模型。不是 LLM 网关。不替代工程师的判断。不防止所有幻觉。不自动颁发法规合规认证。产品页面、文档与公开沟通对此明示无误。 + +理由是务实的：以现实期望采用工具的用户会留下来。误以为它能做它做不到的事而采用的用户会沮丧地离开。早早对边界保持诚实，是比宽泛承诺更好的市场投资。 + +## 11. 社区维护工具，而非反过来 + +StrayMark 的用户多为对自身用例了解超过产品团队的工程师。贡献、issue 与反馈以专业的尊重对待，路线图决策吸纳这些视角。但这不是民主决策（产品需要一致的愿景），而是作为认真严肃的输入。 + +这不意味着照单全收社区所求。意味着解释何时说"不"以及为何说"不"，让对话保持公开可见，并接受这一事实：认真使用者带来的智性压力，会让产品比团队孤立的决策变得更好。 + +## 12. 产品的速度等于学习的速度 + +StrayMark 的推进不应快于我们对其实际使用方式的学习。在三个不同项目中获得真实使用数据之前就过早结晶功能，会在那些可能错误的功能上产生高维护成本。等待证据的耐心是纪律，而非懈怠。 + +具体表现为对以下事项的明确偏好：原型先于功能、观察先于结晶、稳定的 schema 优先于变动的功能、增量演化优先于大规模重写。 + +**0.2 版注解 — 在初期证据有限时仍坚持 N≥3 的精神。** 撰写本版本时所掌握的实证证据仅来自一个采用方项目，在一个领域（Go 后端），由单一作者完成。若按字面应用本原则，将阻止任何由该证据出发的结晶。若按其精神应用——结晶之前先严谨观察、以真实数据驱动增量演化——则可用证据涵盖三个结构性多样化的轴向：(a) 工作单元规模的变化（五个周期中包含 XS、S、M），(b) 在实证压力下的格式迭代（v1 → v2 → v3，每一版都源于上一周期），(c) 跨模型审计员校准（两个异质模型在最受压周期中收敛到相近评分）。这六个周期 × 三种格式 × 三种规模，相当于该原则希望保护的 N≥3 等价证据。 + +仍未多样化的，是领域。为以可执行形式保留该原则：任何由该证据所结晶出的 schema，都以 `v0.json` 发布并标注*实验性*。向稳定 `v1.0` 的过渡，需要在另一领域（前端、ML 流水线、infra-as-code）的第二个项目中完成验证。任何依赖于尚无证据支持之假设的功能——例如条件审批的假设需要多角色流程，而可用证据未演练此情形——在出现确实演练它的项目之前，都被显式地阻塞。论证展开与各假设的具体缺口列表，见 `straymark-thesis-validation.md` §6 与 §8（保存在 `docs/decisions/proposals/` 中）。 + +**检测到的元-元模式 — 格式的自我演化。** 实证证据揭示该格式会自我改进：每个执行的 Charter（在历史术语中是 Plan）都会产生数据，进而精炼下一个格式。这暗示在未来版本中扩展该原则：工具与自己一同演化；每一次使用都是下一版本的输入。目前先作为一项观察记录在案，不作为附加原则；待第二个项目确认该模式后再做调整。 + +--- + +## 如何使用本文档 + +当出现非平凡的设计决策时，值得明确地将其与十二条原则对照，并记录结果。三种有用的模式： + +**满足全部原则的决策**：照常进行。 + +**与某条原则发生冲突的决策**：明确记录正在放宽哪条原则、为何放宽，以及什么样的证据会导致回退该决策。该记录应保存在 AIDEC 或 ADR 中。 + +**违反根本性原则（1、2、3、4）的决策**：在没有先审视该原则是否仍然正确之前，不予作出。如果原则仍然正确，决策被舍弃。如果原则已不正确，则在作出决策*之前*更新原则，而不是之后。 + +原则每六个月以累积的证据作正式评审。两次正式评审之间的变更也是可能的，但必须是审慎的、经过文档记录的。 + +--- + +*本文档是护栏，不是手册。其有效性以"它让我们在多少次决策面前停下来思考"来衡量——那些我们后来本会后悔的决策。* diff --git a/docs/i18n/zh-CN/contributors/README.md b/docs/i18n/zh-CN/contributors/README.md new file mode 100644 index 0000000..ab77c99 --- /dev/null +++ b/docs/i18n/zh-CN/contributors/README.md @@ -0,0 +1,41 @@ +# 贡献者文档 + +为 StrayMark 贡献者准备的资源——不论是阅读代码、撰写翻译、提议变更，还是想理解 framework 形成现貌背后的*为什么*。 + +**语言：** [English](../../../contributors/README.md) | [Español](../../es/contributors/README.md) | 简体中文 + +--- + +## 概念 + +非时变的材料——在打开一个触及 framework 表面的 PR 之前，先阅读这些以理解 StrayMark *是什么*以及它*为何*呈现现有形态。 + +| 文档 | 涵盖什么 | +|---|---| +| [`DESIGN-PRINCIPLES.md`](DESIGN-PRINCIPLES.md) | 治理产品决策的十二条层级化原则。包含来自验证周期的 v0.2 实证注解，覆盖原则 #6（认知纪律）、#9（简洁）与 #12（速度 = 学习的速度）。 | +| [`WHAT-IS-A-CHARTER.md`](WHAT-IS-A-CHARTER.md) | Charter 工件的概念范围：对一项工作单元的事前声明，带有核验契约与审计锚点。映射出 GitHub SpecKit 的 `plan.md` 所覆盖的与 StrayMark Charter 所覆盖的之间的边界——它们不是同一回事。 | + +## 工作流指南 + +| 文档 | 涵盖什么 | +|---|---| +| [`TRANSLATION-GUIDE.md`](../../../contributors/TRANSLATION-GUIDE.md) | 将 StrayMark 文档翻译为其他语言的规则与约定。在提交新增或修改 `i18n/` 文件的 PR 之前请先阅读。*（目前仅英文版。）* | + +## 历史提案（已归档） + +项目在 CLI 之前演化阶段的提案与路线图，作为上下文保留——它们解释了当前形态是如何浮现的。这些**不**在向前的方向上维护；当前行为的权威来源是代码、`dist/.straymark/schemas/` 下的 schema，以及 CHANGELOG。可在 [`docs/decisions/proposals/`](../../../decisions/proposals/) 中浏览： + +| 文件 | 快照日期 | 捕获了什么 | +|---|---|---| +| `2026-04-30-thesis-validation.md` | 2026-04-30 | 针对 Sentinel 六个周期（Go 后端）的产品论点的实证验证——即促成 `DESIGN-PRINCIPLES.md` v0.2 注解的证据体。 | +| `2026-04-30-charter-telemetry.md` | 2026-04-30 | 用于观察真实项目中 Charter 执行的遥测埋点 schema。规范版本现已存放在 `dist/.straymark/schemas/charter-telemetry.schema.v0.json`。 | +| `2026-05-03-cli-roadmap.md` | 2026-05-03 | Rust CLI 的三阶段实施路线图，带有收尾标准。阶段 1–3 现已发布于 `cli-3.x`。 | +| `2026-05-03-audit-skills-design.md` | 2026-05-03 | 将 `/straymark-audit-prompt` 与 `/straymark-audit-review` skill 作为"人在闭环中"的检查点的设计。在 `fw-4.8.0` 中实施。 | +| `2026-05-03-audit-skills-rollout.md` | 2026-05-03 | audit skill 的运营性铺开计划（gating 标准、遥测、分阶段发布）。 | +| `2026-05-04-audit-cli-flow.md` | 2026-05-04 | 在首次实际遇到一个跨多次提交的 L 级 Charter（Sentinel CHARTER-07）之后，对外部审计流程的重新设计。在 `cli-3.10+` 中实施。 | + +当前代码库的 ADR（架构决策记录）位于上一级的 [`docs/decisions/`](../../../decisions/)。 + +--- + +*另请参阅：[`../adopters/`](../adopters/) 是面向在自有项目中采用 StrayMark 的团队的文档，包括 [`ADOPTION-GUIDE.md`](../adopters/ADOPTION-GUIDE.md)、[`CLI-REFERENCE.md`](../adopters/CLI-REFERENCE.md) 与 [`WORKFLOWS.md`](../adopters/WORKFLOWS.md)。* diff --git a/docs/i18n/zh-CN/contributors/WHAT-IS-A-CHARTER.md b/docs/i18n/zh-CN/contributors/WHAT-IS-A-CHARTER.md new file mode 100644 index 0000000..fc44f30 --- /dev/null +++ b/docs/i18n/zh-CN/contributors/WHAT-IS-A-CHARTER.md @@ -0,0 +1,134 @@ +# StrayMark 中的 "Charter" 是什么（以及它相对于 GitHub SpecKit 的位置） + +**版本：** 0.2（Plan → Charter 重命名） +**日期：** 2026-04-30 +**作者：** Jose Villaseñor Montfort — StrangeDaysTech +**目的：** 锁定 **Charter** 工件的概念范围——按其在 Sentinel 实验中（彼时称为 *Plan*）所呈现的样子——并解释它如何与已使用 SpecKit（spec → plan → tasks）的设计与开发流程共存。 +**语言：** [English](../../../contributors/WHAT-IS-A-CHARTER.md) | [Español](../../es/contributors/WHAT-IS-A-CHARTER.md) | 简体中文 +**相关文档：** `straymark-cli-roadmap.md`（§3 阶段 1，§6 Sentinel→CLI 映射）、`straymark-thesis-validation.md`、`straymark-charter-telemetry.md` — 均保存在 `docs/decisions/proposals/` 中，以供历史参考。 + +--- + +## 1. 什么是 StrayMark 中的 Charter + +**一项工作单元的事前声明，规模足够大、值得签订一份可核验的契约并接受事后审计。** + +Charter 同时具有三个面向： + +1. **范围契约**（Context + Scope in/out + 待修改文件 + Risks）：要触动什么，以及——明确地——*不*触动什么。`Out of scope` 章节存在的目的就是让外部审计员不要将其分类为 gap。 +2. **核验契约**（Local checks + Production smoke）：可执行命令的字面表述，按*何时适用*分别列出。Local/Prod 的拆分不是风格选择——它源于一个事实：在 3/3 个周期中，外部审计员都将仅在生产环境中失败的情形分类为 `real_debt`。 +3. **审计锚点**（frontmatter + Charter 收尾 + drift check）：Charter 是 `straymark charter drift` 与 `straymark charter audit` 操作的对象。没有 Charter，就没有可审计的对象。 + +### 1.1 不只是技术债务 + +在 Sentinel 已关闭的 Plan（即 Charter 模式的实证依据）中，只有一个（`03-contract-bumps`）有"债务"的味道。其余是功能（`02-admin-endpoint`、`05-per-service-anomaly-thresholds`）、治理工作（`01-deploy-governance`）或运维工作（`06-baseline-recompute-job`）。`sentinel/docs/plans/` 的 README 上写得很直白：*"在 MVP 后 backlog 收尾期间识别出的工作路线图"* — 是 backlog，而不是 debt-log。 + +### 1.2 何时需要 Charter，何时仅需 AILOG + +从语料中归纳，并非正式书写： + +- **仅 AILOG**：可在单一会话内完成的变更，无需事前声明文件，结构性风险较低（typo、定点修复、局部重构）。 +- **Charter + AILOG**：触及多个文件、有可枚举的事前风险、需要以可执行命令进行核验、并能从合并后的外部审计中获益的工作。规模 XS–L（数分钟到数日）。 +- **ADR + 一个或多个 Charter**：根本性的架构决策，每个 Charter 执行该 ADR 的一部分。 + +### 1.3 原子化的 Charter 收尾（format v4） + +自 fw-4.4.2 起，`charter-template.md` 采用 **format v4**：当预提交的 drift check（Tasks #7）报告 `## Files to modify` 与实际修改文件之间的偏差时，实施者必须原子地更新 Charter——在与实施同一次的 commit/PR 中——添加一个 `## Closing notes` 块，记录改了什么、为什么改、并引用对应的 AILOG。**不延后到合并后的 housekeeping PR。** + +该模式经验性地源于 Sentinel 的 PLAN-07（2026-05-02 关闭）：一次合理的遗漏型 drift（一个 live test 结果对该变更不敏感，因此在 §Files to modify 中声明的某个文件未被触动）通过另一个独立的 housekeeping PR 进行了延后记录，导致 Plan-doc 数日处于陈旧状态。Sentinel 的 AIDEC-2026-05-02-001 形式化了该缺口并提议了 format v4；本文档反映上游的演化。PLAN-05（`docs/plans/05-per-service-anomaly-thresholds.md`）与 PLAN-07 本身是回顾性应用 `## Closing notes` 模式的典范——均在 Sentinel 中。 + +--- + +## 2. 为什么叫 "Charter" 而不是 "Plan" + +StrayMark 在 Sentinel 实验期间（2026 年 4 月）最初将该工件称为 **Plan**。在 CLI 实施之前，该术语被重命名为 **Charter**，原因务实：GitHub SpecKit 已经将"plan"一词（`/speckit.plan`、`plan.md`）用于一个不同的工件，名义上的冲突会在同时组合两套流程的采用方文档中产生摩擦。 + +Sentinel 的历史记录（Plans 01–06、`sentinel/docs/plans/`、`sentinel/scripts/check-plan-drift.sh`、AILOG 与 YAML 遥测 `PLAN-NN.telemetry.yaml`）保留了原名——它们是某一特定时刻的实证证据，重写历史会伪造记录。本文档对那些文件的引用刻意保留 "Plan"。 + +SpecKit 所称的 "plan" 与 StrayMark 所称的 "Charter" 是不同的工件： + +| | **SpecKit `plan.md`** | **StrayMark Charter** | +|---|---|---| +| 粒度 | 完整 feature（数周，多个 user story） | 有界单元（数小时到数日，一个分支） | +| 主导内容 | Stack、依赖、项目结构、宪章 gate | 具体待触动文件、核验命令、R 风险 | +| 子工件 | 生成 `research.md`、`data-model.md`、`quickstart.md`、`contracts/` | （执行时）生成一个 AILOG | +| 验证 | 宪章检查（事前 gate） | Drift 检查 + 外部审计（事后 gate） | +| 优化目标 | *预先的清晰* | *事后的可追溯* | + +SpecKit 所称的 "plan" 更像是 **ADR + 架构骨架**。StrayMark 所称的 "Charter" 更像是 **带有合同性核验和审计锚点的 task-card**。 + +--- + +## 3. SpecKit 流程的逐项映射 + +SpecKit 是线性、自上而下的：`/speckit.specify` → `/speckit.plan` → `/speckit.tasks` → 实施。 + +| SpecKit | 解决什么 | StrayMark 中最接近的等价物 | +|---|---|---| +| `spec.md`（US、FR、SC） | 构建*什么*，与技术无关 | `01-requirements/REQ-*.md` | +| `plan.md`（stack、结构） | *如何*架构 | `02-design/ADR-*.md` | +| `tasks.md`（T001..TNNN） | *按什么顺序*执行 | StrayMark Charter 内的 `## Tasks` 章节 | +|（不存在） | 执行日志 | **AILOG** | +|（不存在） | 已声明 vs 已执行的偏差 | **`straymark charter drift`** | +|（不存在） | 多模型事后审计 | **`straymark charter audit`** | + +最后三行是 StrayMark 的特定贡献。SpecKit 在产出 `tasks.md` 时即结束；之后发生了什么，框架并不关心——若实施偏离计划，框架内没有可检测它的机制。StrayMark 正是在此处介入。 + +--- + +## 4. StrayMark Charter 与 SpecKit 共存的三种模式 + +### 模式 A — SpecKit 驱动的 greenfield + +``` +spec.md → plan.md → tasks.md → ┐ + ├→ Charter-NN（覆盖 US1 + 核验 + 风险） + ├→ Charter-NN+1（覆盖 US2 + 核验 + 风险） + └→ Charter-NN+2（覆盖 US3 + 核验 + 风险） + ↓ + 每个 Charter 生成一个 AILOG + ↓ + drift 检查 + 审计 +``` + +每个 StrayMark Charter 取一组 task 的子集（通常是一个 user story 或一个阶段），并补上 SpecKit 不提供的三层：可执行核验、用以衡量 drift 的文件声明、以及 AILOG/审计的接驳。 + +### 模式 B — 维护 / MVP 之后（Sentinel 的真实情形） + +没有运行 SpecKit。Sentinel 的 Plans 01–06 来自 AILOG 与 MVP 之后的 backlog，并非来自规范。Charter 的 `Origen:` 字段指向某个 AILOG，而不是某个 `specs/###-feature/`。此时 StrayMark Charter 是独立存在的。 + +### 模式 C — 混合（很可能是最现实的） + +- 大型 feature → 完整 SpecKit 流程 + 在执行 task 时使用 StrayMark Charter。 +- Bug 修复、治理、债务、契约变更、小型 feature → 仅使用 StrayMark Charter。 + +这与 Sentinel 已展示的情况一致：在已关闭的 Plan 中，没有上游的 SpecKit，因为 MVP 早已规范化并关闭。剩下的是演化性的工作，对其而言 Spec→Plan→Tasks 周期显得过重。 + +--- + +## 5. 根本的概念差异 + +**SpecKit 回答的问题：***"如何把一个产品想法分解为可执行的工作？"* — 优化目标是预先的清晰与 user story 的并行化。 + +**StrayMark Charter 回答的问题：***"如何让一个工作单元变得可核验、可审计，并在偏离声明时可被检测？"* — 优化目标是事后的证据。 + +因此它们并不竞争：它们处于周期中的不同时刻。SpecKit 在 `tasks.md` 处结束；StrayMark Charter 从那里开始（适用时）或独立成立（无前置规范时）。Sentinel 的论点不是"这取代 SpecKit"——而是"这覆盖 SpecKit 不覆盖的 post-tasks 阶段，并以三层模式（声明 + drift + 异质审计）来覆盖；这一模式有实证证据能够捕获实施者未文档化的缺口"。 + +--- + +## 6. 关于 Studio 愿景的说明："Stage" 不是 Charter 的同义词 + +`straymark-studio-vision.md`（一份仅供内部使用的文档）引入了一个额外术语 **Stage**，不应与 Charter 混淆。它们不是同义词：所处的周期层级不同。 + +- **Stage** = 一段工作阶段，贯穿 Studio 的六个认知阶段（Spec → Implementation → Audit → Remediation → Governance → Closure & Deliver），并以一个签名且哈希链式的 Closure Bundle 收尾。愿景中提议的命令：`straymark stage open/close/status`（未实施；对应迈向 Studio 演化的里程碑 2）。 +- **Charter** = 带有核验 + drift + 审计锚点的有界单元——本文件所定义的工件。Charter 存在于 Stage *之内*；一个 Stage 通常包含一个或多个 Charter，加上其相关 task。 + +愿景所暗含的分类是三层结构：**Stage > Charter > Task**。当前 CLI 路线图（`straymark-cli-roadmap.md`，保存在 `docs/decisions/proposals/` 中，阶段 1–3）完全在 Charter 层级运作（即 Sentinel 所称的 "Plan"）——这是 Sentinel 的实证证据所在的层级。Stage 将来会作为附加层进入 CLI，而不是对 Charter 的重命名。 + +## 7. 对 StrayMark CLI 路线图的启示 + +值得在阶段 1 落地（`straymark-cli-roadmap.md` §3.2，保存在 `docs/decisions/proposals/` 中）时，反映在 `straymark charter new` 命令的文档之中。今天计划中的标志 `--from-ailog ID` 覆盖了模式 B。也许还应该有一个 `--from-spec specs/###-feature/` 标志覆盖模式 A——预填 `Origen:` 指向 SpecKit 的 `spec.md`，并可选地把相关 user story 继承到 Context 章节。这是阶段 1 的练习，而不是今天要解决的问题，但值得在本文档中作为一项开放决策记录在案，供子命令设计时参考。 + +--- + +*本文档捕获了 Charter 工件（在 Sentinel 实验中最初称为 "Plan"）在 2026 年 4 月底所被理解的概念范围。该定义将随 Sentinel 之外的采用方在其他领域演练此模式而继续演化——版本 0.3 将在观察到至少一个采用方项目以 `straymark charter` 完成一个 Charter（阶段 1 的退出标准）之后撰写。* From 3e82ea409de20678a9bf4083746d6296aa277da5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jose=20Villase=C3=B1or=20Montfort?= <195970+montfort@users.noreply.github.com> Date: Mon, 11 May 2026 13:08:36 -0600 Subject: [PATCH 2/3] =?UTF-8?q?feat(framework):=20fw-4.13.0=20=E2=80=94=20?= =?UTF-8?q?TDE=20activation=20trigger=20(closes=20#128)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the operational trigger and TDE vs R disambiguation that were missing in fw-4.12.0. Empirically motivated: Sentinel adopter created zero TDEs across 13 closed Charters despite ≥7 instances of transversal debt routed through parallel mechanisms. Governance (EN + ES + zh-CN): - AGENT-RULES.md §2 — new TDE trigger row; §3 — "TDE vs R" with the four canonical criteria (heritage from prior Charter, multi-module scope, requires dedicated Charter, requires human prioritization) - QUICK-REFERENCE.md and STRAYMARK.md §6 — surface the trigger - FOLLOW-UPS-BACKLOG-PATTERN.md — new status `promoted`, new destination `TDE-YYYY-MM-DD-NNN`, new `Promoted to:` field, full "Promotion to TDE" section with criteria + workflow Templates + skills: - TEMPLATE-TDE.md (EN + ES + zh-CN) — `promoted_from_followup: null` frontmatter, inline activation-triggers note - /straymark-new (3 surfaces) — split the TDE suggestion into code-smell trigger (TODO/FIXME/HACK) and architectural trigger Fixed — stale paths in /straymark-status (3 surfaces) and CLI-REFERENCE (3 langs). The TDE path bug (`06-operations/tech-debt/` → `06-evolution/technical-debt/`) was surfaced verifying #128: status would never have found TDEs that `new` was writing. Four sibling bugs (ADR/REQ/TES/INC) fixed in the same pass since they share the cause. Version bump fw-4.12.0 → fw-4.13.0 across manifest, footers (8 governance docs × 3 langs), README/CLI-REFERENCE/ADOPTION-GUIDE versioning tables (3 langs). Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 29 +++++++++++++ README.md | 4 +- dist/.agent/workflows/straymark-new.md | 3 +- dist/.agent/workflows/straymark-status.md | 10 ++--- dist/.claude/skills/straymark-new/SKILL.md | 3 +- dist/.claude/skills/straymark-status/SKILL.md | 10 ++--- dist/.gemini/skills/straymark-new/SKILL.md | 3 +- dist/.gemini/skills/straymark-status/SKILL.md | 10 ++--- dist/.straymark/00-governance/AGENT-RULES.md | 22 +++++++++- .../00-governance/C4-DIAGRAM-GUIDE.md | 2 +- .../00-governance/DOCUMENTATION-POLICY.md | 2 +- .../FOLLOW-UPS-BACKLOG-PATTERN.md | 41 ++++++++++++++++--- .../00-governance/QUICK-REFERENCE.md | 3 +- .../00-governance/i18n/es/AGENT-RULES.md | 22 +++++++++- .../00-governance/i18n/es/C4-DIAGRAM-GUIDE.md | 2 +- .../i18n/es/DOCUMENTATION-POLICY.md | 2 +- .../i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md | 41 ++++++++++++++++--- .../00-governance/i18n/es/QUICK-REFERENCE.md | 3 +- .../00-governance/i18n/zh-CN/AGENT-RULES.md | 22 +++++++++- .../i18n/zh-CN/C4-DIAGRAM-GUIDE.md | 2 +- .../i18n/zh-CN/DOCUMENTATION-POLICY.md | 2 +- .../i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md | 41 ++++++++++++++++--- .../i18n/zh-CN/QUICK-REFERENCE.md | 3 +- dist/.straymark/QUICK-REFERENCE.md | 2 +- dist/.straymark/templates/TEMPLATE-TDE.md | 3 ++ .../templates/i18n/es/TEMPLATE-TDE.md | 3 ++ .../templates/i18n/zh-CN/TEMPLATE-TDE.md | 3 ++ dist/STRAYMARK.md | 1 + dist/dist-manifest.yml | 2 +- docs/adopters/ADOPTION-GUIDE.md | 2 +- docs/adopters/CLI-REFERENCE.md | 16 ++++---- docs/i18n/es/README.md | 4 +- docs/i18n/es/adopters/ADOPTION-GUIDE.md | 2 +- docs/i18n/es/adopters/CLI-REFERENCE.md | 14 +++---- docs/i18n/zh-CN/README.md | 4 +- docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md | 2 +- docs/i18n/zh-CN/adopters/CLI-REFERENCE.md | 16 ++++---- 37 files changed, 274 insertions(+), 82 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 292a210..2a7f463 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,35 @@ and this project uses [independent versioning](README.md#versioning) for Framewo --- +## Framework 4.13.0 — TDE activation trigger + +Closes [#128](https://github.com/StrangeDaysTech/straymark/issues/128). The TDE (Technical Debt) document type had structural shape — template, destination folder, autonomy boundary — but no operational activation trigger in the agent-facing governance. Empirical signal from the Sentinel adopter (primary, fw-4.12.0): zero TDEs created across 13 closed Charters despite ≥7 instances of transversal debt being routed through parallel mechanisms (`R (new, not in Charter)` in AILOG `§Risk`, or follow-ups in `follow-ups-backlog.md`). This release adds the trigger and the `R` vs TDE disambiguation, plus a promotion path from the follow-ups backlog. Governance-docs-only — no CLI changes; the `straymark debt list/status/close` subcommand trio is deferred to v1 (same gate as the follow-ups CLI per `FOLLOW-UPS-BACKLOG-PATTERN.md`). + +### Added (Framework) + +- **TDE activation trigger** in `AGENT-RULES.md §2 "When to Document"` (EN + ES + zh-CN). New row routes transversal technical debt to TDE creation. +- **TDE vs `R (new, not in Charter)` disambiguation** in `AGENT-RULES.md §3` (EN + ES + zh-CN). Four canonical triggers for TDE: *heritage from prior Charter*, *applies to multiple modules/Charters*, *requires dedicated Charter outside current scope envelope*, *requires human prioritization/assignment*. If none apply, the debt is an `R` row in the current Charter's AILOG; if any apply, file a TDE. +- **TDE row in "When to Document"** quick tables: `QUICK-REFERENCE.md` (EN + ES + zh-CN) and `STRAYMARK.md §6`. Surfaces the trigger at the every-session entry points. +- **Promotion path FU → TDE** in `FOLLOW-UPS-BACKLOG-PATTERN.md` (EN + ES + zh-CN). New status `promoted`, new `Destination: TDE-YYYY-MM-DD-NNN` value, new `Promoted to:` entry field, plus a "Promotion to TDE" section with criteria (mirroring the `AGENT-RULES.md §3` heuristics) and the operator-driven workflow. Post-Charter close checklist now includes "promote un-resolved transversal entries to TDE." +- **`promoted_from_followup: FU-NNN` frontmatter field** in `TEMPLATE-TDE.md` (EN + ES + zh-CN). Optional, populated when the TDE originates from a backlog entry, preserves traceability. +- **Activation-trigger note** in the TDE template body (EN + ES + zh-CN) so the agent reading the template at creation time sees the four canonical triggers + pointer to `AGENT-RULES.md §3`. + +### Changed (Framework) + +- **`/straymark-new` skill** (3 surfaces — `.claude/skills/`, `.gemini/skills/`, `.agent/workflows/`): the TDE suggestion row split into two — `TODO`/`FIXME`/`HACK` comments remain as a code-smell trigger, and a new row covers the architectural trigger (heritage, transversal, dedicated Charter, human prioritization) pointing to `AGENT-RULES.md §3`. + +### Fixed (Framework) + +- **`/straymark-status` skill paths** (3 surfaces — `.claude/skills/`, `.gemini/skills/`, `.agent/workflows/`). Five doc types had stale directory paths that diverged from the canonical layout in `AGENT-RULES.md §5` and `STRAYMARK.md §10`: ADR (`04-architecture/decisions/` → `02-design/decisions/`), REQ (`03-requirements/` → `01-requirements/`), TES (`05-testing/` → `04-testing/`), INC (`06-operations/incidents/` → `05-operations/incidents/`), TDE (`06-operations/tech-debt/` → `06-evolution/technical-debt/`). The TDE bug was surfaced while verifying #128: `/straymark-new` would have written a TDE to the correct path, but `/straymark-status` would never have found it. The other four are pre-existing drift fixed in the same pass. +- **`/straymark-adr` shortcut path in CLI-REFERENCE.md** (EN + ES + zh-CN). Same `04-architecture/decisions/` → `02-design/decisions/` correction. + +### Adopter guidance + +- Sentinel will create the 3 TDEs surfaced during CHARTER-13 close ceremony retrospective (R7 RequireScope architectural gap, HTTP layer test coverage gap, legacy AILOGs with `review_required: false`) as empirical validation of the trigger heuristic in a follow-up PR. +- Existing projects on `fw-4.12.0` get the new framework files via `straymark update-framework`. The trigger guidance is documentation-only — no migration is required. + +--- + ## Framework 4.12.0 / CLI 3.12.0 — Charter discoverability + path alignment Closes the two Charter-related gaps surfaced by real adopters in the issue tracker: **Charter were structurally invisible to the CLI** ([#119](https://github.com/StrangeDaysTech/straymark/issues/119) — `straymark charter list/audit/close` hardcoded `docs/charters/` while the framework already validated `.straymark/charters/`) and **Charter were conceptually invisible to onboarding agents** ([#113](https://github.com/StrangeDaysTech/straymark/issues/113) — agents following the canonical entry points could not discover Charter as a workflow concept). diff --git a/README.md b/README.md index 2b2d7d2..e58416f 100644 --- a/README.md +++ b/README.md @@ -274,7 +274,7 @@ StrayMark uses independent version tags for each component: | Component | Tag prefix | Example | Includes | |-----------|-----------|---------|----------| -| Framework | `fw-` | `fw-4.12.0` | Templates (12 types), governance, directives, Charter template + schema | +| Framework | `fw-` | `fw-4.13.0` | Templates (12 types), governance, directives, Charter template + schema | | CLI | `cli-` | `cli-3.12.0` | The `straymark` binary | Check installed versions with `straymark status` or `straymark about`. @@ -307,7 +307,7 @@ See [CLI Reference](https://github.com/StrangeDaysTech/straymark/blob/main/docs/ ```bash # Download the latest framework release ZIP from GitHub # Go to https://github.com/StrangeDaysTech/straymark/releases -# and download the latest fw-* release (e.g., fw-4.12.0) +# and download the latest fw-* release (e.g., fw-4.13.0) # Extract and copy to your project unzip straymark-fw-*.zip -d your-project/ diff --git a/dist/.agent/workflows/straymark-new.md b/dist/.agent/workflows/straymark-new.md index d9d59cc..38bb92b 100644 --- a/dist/.agent/workflows/straymark-new.md +++ b/dist/.agent/workflows/straymark-new.md @@ -52,7 +52,8 @@ Based on the analysis, suggest a document type: | Files with `auth`, `user`, `privacy`, `gdpr` | ETH (draft) | | Test files (`*.test.*`, `*.spec.*`) | TES | | Bug fixes, hotfixes | INC | -| `TODO`, `FIXME`, `HACK` comments added | TDE | +| `TODO`, `FIXME`, `HACK` comments added | TDE (code-smell trigger) | +| Transversal debt — heritage from prior Charter, applies to multiple modules, requires dedicated Charter, or needs human prioritization | TDE (architectural trigger — distinct from per-Charter `R`; see AGENT-RULES.md §3) | | Requirements or spec files | REQ | | Multi-session implementation block (>1 day, >5 tasks, multi-phase) | **Charter** — redirect to `straymark-charter-new` (Charters use `straymark charter new`, not `straymark new`) | diff --git a/dist/.agent/workflows/straymark-status.md b/dist/.agent/workflows/straymark-status.md index 9582cac..9b4cc38 100644 --- a/dist/.agent/workflows/straymark-status.md +++ b/dist/.agent/workflows/straymark-status.md @@ -26,12 +26,12 @@ Check these directories for each document type: |------|--------|-----------| | AILOG | `AILOG-` | `.straymark/07-ai-audit/agent-logs/` | | AIDEC | `AIDEC-` | `.straymark/07-ai-audit/decisions/` | -| ADR | `ADR-` | `.straymark/04-architecture/decisions/` | +| ADR | `ADR-` | `.straymark/02-design/decisions/` | | ETH | `ETH-` | `.straymark/07-ai-audit/ethical-reviews/` | -| REQ | `REQ-` | `.straymark/03-requirements/` | -| TES | `TES-` | `.straymark/05-testing/` | -| INC | `INC-` | `.straymark/06-operations/incidents/` | -| TDE | `TDE-` | `.straymark/06-operations/tech-debt/` | +| REQ | `REQ-` | `.straymark/01-requirements/` | +| TES | `TES-` | `.straymark/04-testing/` | +| INC | `INC-` | `.straymark/05-operations/incidents/` | +| TDE | `TDE-` | `.straymark/06-evolution/technical-debt/` | | SEC | `SEC-` | `.straymark/08-security/` | | MCARD | `MCARD-` | `.straymark/09-ai-models/` | | SBOM | `SBOM-` | `.straymark/07-ai-audit/` | diff --git a/dist/.claude/skills/straymark-new/SKILL.md b/dist/.claude/skills/straymark-new/SKILL.md index e07600b..155561f 100644 --- a/dist/.claude/skills/straymark-new/SKILL.md +++ b/dist/.claude/skills/straymark-new/SKILL.md @@ -54,7 +54,8 @@ Based on the analysis, suggest a document type: | Files with `auth`, `user`, `privacy`, `gdpr` | ETH (draft) | | Test files (`*.test.*`, `*.spec.*`) | TES | | Bug fixes, hotfixes | INC | -| `TODO`, `FIXME`, `HACK` comments added | TDE | +| `TODO`, `FIXME`, `HACK` comments added | TDE (code-smell trigger) | +| Transversal debt — heritage from prior Charter, applies to multiple modules, requires dedicated Charter, or needs human prioritization | TDE (architectural trigger — distinct from per-Charter `R`; see AGENT-RULES.md §3) | | Requirements or spec files | REQ | | Multi-session implementation block (>1 day, >5 tasks, multi-phase) | **Charter** — redirect to `/straymark-charter-new` (Charters use the `straymark charter new` CLI, not `straymark new`) | diff --git a/dist/.claude/skills/straymark-status/SKILL.md b/dist/.claude/skills/straymark-status/SKILL.md index 1b94f5c..31c07da 100644 --- a/dist/.claude/skills/straymark-status/SKILL.md +++ b/dist/.claude/skills/straymark-status/SKILL.md @@ -28,12 +28,12 @@ Check these directories for each document type: |------|--------|-----------| | AILOG | `AILOG-` | `.straymark/07-ai-audit/agent-logs/` | | AIDEC | `AIDEC-` | `.straymark/07-ai-audit/decisions/` | -| ADR | `ADR-` | `.straymark/04-architecture/decisions/` | +| ADR | `ADR-` | `.straymark/02-design/decisions/` | | ETH | `ETH-` | `.straymark/07-ai-audit/ethical-reviews/` | -| REQ | `REQ-` | `.straymark/03-requirements/` | -| TES | `TES-` | `.straymark/05-testing/` | -| INC | `INC-` | `.straymark/06-operations/incidents/` | -| TDE | `TDE-` | `.straymark/06-operations/tech-debt/` | +| REQ | `REQ-` | `.straymark/01-requirements/` | +| TES | `TES-` | `.straymark/04-testing/` | +| INC | `INC-` | `.straymark/05-operations/incidents/` | +| TDE | `TDE-` | `.straymark/06-evolution/technical-debt/` | | SEC | `SEC-` | `.straymark/08-security/` | | MCARD | `MCARD-` | `.straymark/09-ai-models/` | | SBOM | `SBOM-` | `.straymark/07-ai-audit/` | diff --git a/dist/.gemini/skills/straymark-new/SKILL.md b/dist/.gemini/skills/straymark-new/SKILL.md index 0b4dd45..6b77dc2 100644 --- a/dist/.gemini/skills/straymark-new/SKILL.md +++ b/dist/.gemini/skills/straymark-new/SKILL.md @@ -53,7 +53,8 @@ Based on the analysis, suggest a document type: | Files with `auth`, `user`, `privacy`, `gdpr` | ETH (draft) | | Test files (`*.test.*`, `*.spec.*`) | TES | | Bug fixes, hotfixes | INC | -| `TODO`, `FIXME`, `HACK` comments added | TDE | +| `TODO`, `FIXME`, `HACK` comments added | TDE (code-smell trigger) | +| Transversal debt — heritage from prior Charter, applies to multiple modules, requires dedicated Charter, or needs human prioritization | TDE (architectural trigger — distinct from per-Charter `R`; see AGENT-RULES.md §3) | | Requirements or spec files | REQ | | Multi-session implementation block (>1 day, >5 tasks, multi-phase) | **Charter** — redirect to `/straymark-charter-new` (Charters use `straymark charter new`, not `straymark new`) | diff --git a/dist/.gemini/skills/straymark-status/SKILL.md b/dist/.gemini/skills/straymark-status/SKILL.md index a4223ad..7152cc7 100644 --- a/dist/.gemini/skills/straymark-status/SKILL.md +++ b/dist/.gemini/skills/straymark-status/SKILL.md @@ -27,12 +27,12 @@ Check these directories for each document type: |------|--------|-----------| | AILOG | `AILOG-` | `.straymark/07-ai-audit/agent-logs/` | | AIDEC | `AIDEC-` | `.straymark/07-ai-audit/decisions/` | -| ADR | `ADR-` | `.straymark/04-architecture/decisions/` | +| ADR | `ADR-` | `.straymark/02-design/decisions/` | | ETH | `ETH-` | `.straymark/07-ai-audit/ethical-reviews/` | -| REQ | `REQ-` | `.straymark/03-requirements/` | -| TES | `TES-` | `.straymark/05-testing/` | -| INC | `INC-` | `.straymark/06-operations/incidents/` | -| TDE | `TDE-` | `.straymark/06-operations/tech-debt/` | +| REQ | `REQ-` | `.straymark/01-requirements/` | +| TES | `TES-` | `.straymark/04-testing/` | +| INC | `INC-` | `.straymark/05-operations/incidents/` | +| TDE | `TDE-` | `.straymark/06-evolution/technical-debt/` | | SEC | `SEC-` | `.straymark/08-security/` | | MCARD | `MCARD-` | `.straymark/09-ai-models/` | | SBOM | `SBOM-` | `.straymark/07-ai-audit/` | diff --git a/dist/.straymark/00-governance/AGENT-RULES.md b/dist/.straymark/00-governance/AGENT-RULES.md index 8ada380..2c04a38 100644 --- a/dist/.straymark/00-governance/AGENT-RULES.md +++ b/dist/.straymark/00-governance/AGENT-RULES.md @@ -39,6 +39,7 @@ confidence: high | medium | low | Addition/removal/upgrade of security-critical dependencies | AILOG | Human review required | | Changes affecting AI system lifecycle (deployment, retirement) | AILOG + ADR | Human review required | | Changes to OTel instrumentation (spans, attributes, pipeline) | AILOG | Tag `observabilidad`, see §9 | +| Transversal technical debt discovered during implementation | TDE | See §3 "TDE vs `R` (new, not in Charter)" for the disambiguation criterion | ### PROHIBITED - Do not document @@ -99,6 +100,25 @@ confidence: high | medium | low | TDE | Technical debt | | INC | Incident conclusions | +### TDE vs `R (new, not in Charter)` + +Two surfaces exist for emergent debt. They are not interchangeable — pick the one whose lifecycle matches the work, not whichever is closer to hand. + +**File an `R (new, not in Charter)` entry in the AILOG `§Risk` section** when the debt: + +- Is *scoped to the Charter currently in execution* or the next Charter in sequence. +- Resolves as a documented deferral, a small atomic fix, or a forward-pointer to a Charter that already exists. +- Carries low-to-medium impact and the agent can describe the remediation in one bullet. + +**Create a TDE document** when the debt: + +- Is *heritage from a prior Charter* (the gap predates the work currently in flight). +- *Applies to multiple modules or multiple Charters* — fragmenting it into per-Charter `R` entries loses the architectural shape. +- *Requires a dedicated Charter outside the current scope envelope* to remediate (not the current Charter, not the next one). +- *Requires human prioritization or assignment* the agent cannot decide alone (impact × effort matrix, ownership, sprint placement). + +The four triggers above are the activation criteria for TDE under §2. When the AILOG you are about to write would carry an `R` matching any of them, write the TDE instead and reference it from the AILOG `§Risk` row. + --- ## 4. When to Request Human Review @@ -357,4 +377,4 @@ When a project accumulates a high volume of AILOGs across multiple Charters and --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/C4-DIAGRAM-GUIDE.md b/dist/.straymark/00-governance/C4-DIAGRAM-GUIDE.md index 4804365..92401fd 100644 --- a/dist/.straymark/00-governance/C4-DIAGRAM-GUIDE.md +++ b/dist/.straymark/00-governance/C4-DIAGRAM-GUIDE.md @@ -234,4 +234,4 @@ Use a Level 1 (Context) diagram to illustrate: --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/DOCUMENTATION-POLICY.md b/dist/.straymark/00-governance/DOCUMENTATION-POLICY.md index a8189c5..a9930a6 100644 --- a/dist/.straymark/00-governance/DOCUMENTATION-POLICY.md +++ b/dist/.straymark/00-governance/DOCUMENTATION-POLICY.md @@ -307,4 +307,4 @@ See also [ADR-2025-01-20-001] for architectural context. --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/FOLLOW-UPS-BACKLOG-PATTERN.md b/dist/.straymark/00-governance/FOLLOW-UPS-BACKLOG-PATTERN.md index 15e9161..a69638a 100644 --- a/dist/.straymark/00-governance/FOLLOW-UPS-BACKLOG-PATTERN.md +++ b/dist/.straymark/00-governance/FOLLOW-UPS-BACKLOG-PATTERN.md @@ -77,11 +77,12 @@ Each entry inside a bucket follows this shape: ```markdown ### FU-NNN — - **Origin**: AILOG-NNNN-NN-NN-NNN -- **Status**: open | in-progress | closed | superseded +- **Status**: open | in-progress | closed | superseded | promoted - **Trigger**: ready | | when | -- **Destination**: +- **Destination**: - **Cost**: - **Notes**: +- **Promoted to**: ``` `FU-NNN` is monotonically increasing across the registry's lifetime; do not renumber when entries close. @@ -92,8 +93,36 @@ Each entry inside a bucket follows this shape: - `in-progress` — a Charter has been declared or is executing that addresses this entry. - `closed` — entry resolved (Charter merged, operational task done, time elapsed and reviewed). - `superseded` — addressed by other work that did not reference this entry directly. +- `promoted` — the entry was elevated to a TDE document because it met the transversal-debt criteria (see "Promotion to TDE" below). The `Promoted to:` field carries the TDE id. -Closed and superseded entries stay in the file (auditable history). Operators may move them to a `## Bucket: closed` section at the bottom for visual decluttering, but they are never deleted. +Closed, superseded, and promoted entries stay in the file (auditable history). Operators may move them to a `## Bucket: closed` section at the bottom for visual decluttering, but they are never deleted. + +--- + +## Promotion to TDE + +Some FU entries are not just deferred tasks — they describe **transversal technical debt** that warrants its own governance document (TDE). The criteria for promotion mirror the TDE-vs-`R` disambiguation in `AGENT-RULES.md §3`: + +- The entry is *heritage from a prior Charter* (already lived through ≥1 Charter close without remediation). +- The entry *applies to multiple modules or multiple Charters* — the central registry has fragmented it into bullets that share a root cause. +- The entry *requires a dedicated Charter outside the current scope envelope* to remediate. +- The entry *requires human prioritization or assignment* that the periodic operator review cannot decide from the bullet alone (impact × effort matrix, ownership). + +When any of these holds, promote the FU entry to a TDE document under `.straymark/06-evolution/technical-debt/`: + +1. Create the TDE via `/straymark-new tde` (or `straymark new --type tde`). Fill `impact`, `effort`, `type`, and the body sections from the FU entry's context. +2. Add `promoted_from_followup: FU-NNN` to the TDE frontmatter for traceability. +3. In the FU entry, set `Status: promoted`, set `Destination: TDE-YYYY-MM-DD-NNN`, and add `Promoted to: TDE-YYYY-MM-DD-NNN`. Move the entry to the `## Bucket: closed` section if you maintain one; otherwise leave it in place with the new status. + +The FU entry is **not deleted** after promotion — its presence in the registry is the audit trail showing where the TDE came from. + +### When to promote + +- **Periodic review** — when the operator does the manual reclassification pass, promote any entry that has lived through ≥2 Charter closes without resolution and meets the criteria above. +- **Charter close** — when reviewing entries the just-closed Charter resolved, if you find entries that were *not* resolved and meet the criteria above, promote them rather than leaving them as `open`. +- **Pre-Charter declaration** — if you're about to declare a Charter and notice the registry contains entries that this Charter would *partially* address, the un-addressed portion may belong as a TDE rather than as another deferred FU. + +The drift script (`scripts/check-followups-drift.sh`) is **not extended** for promotion candidates in v0 — promotion is operator-driven. A future v1 enhancement could flag entries meeting the "lived through ≥2 Charters" heuristic, but that crystallizes after a second adopter validates the pattern (same gate as the rest of v0 → v1). --- @@ -135,10 +164,10 @@ The agent (Claude / Gemini / etc.) becomes the primary maintainer of the registr - **Session start**: glance at `.straymark/follow-ups-backlog.md` to know what is pending across the project. - **Pre-commit checklist**: created or modified any AILOG with `## Follow-ups` or `R (new, not in Charter)` entries? → run `scripts/check-followups-drift.sh --apply` to extend the backlog in the same commit. -- **Post-Charter close**: review entries the Charter resolved; mark them `closed` (with the closing Charter id in `Notes`) or `superseded`. +- **Post-Charter close**: review entries the Charter resolved; mark them `closed` (with the closing Charter id in `Notes`) or `superseded`. For un-resolved entries that meet the TDE criteria (heritage from prior Charter, transversal, requires dedicated Charter, needs human prioritization), promote them to a TDE document (see "Promotion to TDE" in this pattern + `AGENT-RULES.md §3`). ``` -This makes the agent the maintainer, the script the verification layer, and the operator the periodic reviewer (re-bucketing, marking closed, pruning superseded). +This makes the agent the maintainer, the script the verification layer, and the operator the periodic reviewer (re-bucketing, marking closed, pruning superseded, promoting to TDE when criteria apply). --- @@ -186,4 +215,4 @@ Contributed via [issue #111](https://github.com/StrangeDaysTech/straymark/issues --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/QUICK-REFERENCE.md b/dist/.straymark/00-governance/QUICK-REFERENCE.md index 0ce11f6..4d72a37 100644 --- a/dist/.straymark/00-governance/QUICK-REFERENCE.md +++ b/dist/.straymark/00-governance/QUICK-REFERENCE.md @@ -90,6 +90,7 @@ Charters are **not** doc types — they wrap a multi-session implementation bloc | Security-critical dependency changes | AILOG + human review | | OTel instrumentation changes | AILOG + tag `observabilidad` | | Multi-session implementation block (>1 day, >5 tasks across phases) | Declare a **Charter** (`straymark charter new`) | +| Transversal technical debt (heritage from prior Charter, applies to multiple modules, requires dedicated Charter, needs human prioritization) | **TDE** — distinct from per-Charter `R`; see AGENT-RULES.md §3 | **DO NOT document**: credentials, tokens, PII, secrets. @@ -240,4 +241,4 @@ Mark `review_required: true` when: --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/i18n/es/AGENT-RULES.md b/dist/.straymark/00-governance/i18n/es/AGENT-RULES.md index 0a455d4..f8b90f7 100644 --- a/dist/.straymark/00-governance/i18n/es/AGENT-RULES.md +++ b/dist/.straymark/00-governance/i18n/es/AGENT-RULES.md @@ -39,6 +39,7 @@ confidence: high | medium | low | Adición/eliminación/actualización de dependencias críticas de seguridad | AILOG | Revisión humana requerida | | Cambios que afectan el ciclo de vida del sistema de IA (despliegue, retirada) | AILOG + ADR | Revisión humana requerida | | Cambios en instrumentación OTel (spans, atributos, pipeline) | AILOG | Tag `observabilidad`, ver §9 | +| Deuda técnica transversal detectada durante la implementación | TDE | Ver §3 "TDE vs `R` (new, not in Charter)" para el criterio de desambiguación | ### PROHIBIDO - No documentar @@ -99,6 +100,25 @@ confidence: high | medium | low | TDE | Deuda técnica | | INC | Conclusiones de incidentes | +### TDE vs `R (new, not in Charter)` + +Existen dos superficies para la deuda emergente. No son intercambiables — elige la que coincida con el ciclo de vida del trabajo, no la que tengas más a mano. + +**Registra un `R (new, not in Charter)` en la sección `§Risk` del AILOG** cuando la deuda: + +- Está *acotada al Charter en ejecución* o al siguiente Charter en la secuencia. +- Se resuelve como un diferimiento documentado, un fix atómico pequeño, o un puntero a un Charter que ya existe. +- Tiene impacto bajo-a-medio y el agente puede describir la remediación en una sola viñeta. + +**Crea un documento TDE** cuando la deuda: + +- Es *herencia de un Charter previo* (la brecha precede al trabajo actualmente en ejecución). +- *Aplica a múltiples módulos o múltiples Charters* — fragmentarla en entradas `R` por Charter pierde la forma arquitectónica. +- *Requiere un Charter dedicado fuera del envelope de scope actual* para remediarse (no el Charter actual, no el siguiente). +- *Requiere priorización o asignación humana* que el agente no puede decidir solo (matriz impact × effort, ownership, sprint placement). + +Los cuatro triggers anteriores son los criterios de activación para TDE bajo §2. Cuando el AILOG que vas a escribir cargaría un `R` que coincida con cualquiera de ellos, escribe el TDE en su lugar y referencialo desde la fila `§Risk` del AILOG. + --- ## 4. Cuándo Solicitar Revisión Humana @@ -357,4 +377,4 @@ Cuando un proyecto acumula un volumen alto de AILOGs a lo largo de múltiples Ch --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md b/dist/.straymark/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md index dac18e2..24023e7 100644 --- a/dist/.straymark/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md +++ b/dist/.straymark/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md @@ -234,4 +234,4 @@ Usar un diagrama de Nivel 1 (Contexto) para ilustrar: --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md b/dist/.straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md index 679a774..57e724a 100644 --- a/dist/.straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md +++ b/dist/.straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md @@ -300,4 +300,4 @@ Ver también [ADR-2025-01-20-001] para contexto arquitectónico. --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md b/dist/.straymark/00-governance/i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md index c3f2b20..43452aa 100644 --- a/dist/.straymark/00-governance/i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md +++ b/dist/.straymark/00-governance/i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md @@ -77,11 +77,12 @@ Cada entrada dentro de un bucket sigue esta forma: ```markdown ### FU-NNN — - **Origin**: AILOG-NNNN-NN-NN-NNN -- **Status**: open | in-progress | closed | superseded +- **Status**: open | in-progress | closed | superseded | promoted - **Trigger**: ready | | when | -- **Destination**: +- **Destination**: - **Cost**: - **Notes**: +- **Promoted to**: ``` `FU-NNN` es monotónicamente creciente a lo largo de la vida del registro; no se renumera cuando las entradas se cierran. @@ -92,8 +93,36 @@ Cada entrada dentro de un bucket sigue esta forma: - `in-progress` — un Charter ha sido declarado o está en ejecución para atender esta entrada. - `closed` — entrada resuelta (Charter mergeado, tarea operativa hecha, tiempo transcurrido y revisado). - `superseded` — atendida por otro trabajo que no referenció esta entrada directamente. +- `promoted` — la entrada fue elevada a un documento TDE porque cumple los criterios de deuda transversal (ver "Promoción a TDE" abajo). El campo `Promoted to:` carga el id del TDE. -Las entradas closed y superseded permanecen en el archivo (historia auditable). Los operadores pueden moverlas a una sección `## Bucket: closed` al final para limpieza visual, pero nunca se eliminan. +Las entradas closed, superseded y promoted permanecen en el archivo (historia auditable). Los operadores pueden moverlas a una sección `## Bucket: closed` al final para limpieza visual, pero nunca se eliminan. + +--- + +## Promoción a TDE + +Algunas entradas FU no son solo tareas diferidas — describen **deuda técnica transversal** que merece su propio documento de gobernanza (TDE). Los criterios para promoción reflejan la desambiguación TDE-vs-`R` en `AGENT-RULES.md §3`: + +- La entrada es *herencia de un Charter previo* (ya vivió ≥1 cierre de Charter sin remediación). +- La entrada *aplica a múltiples módulos o múltiples Charters* — el registro central la ha fragmentado en bullets que comparten una causa raíz. +- La entrada *requiere un Charter dedicado fuera del envelope de scope actual* para remediarse. +- La entrada *requiere priorización o asignación humana* que la revisión periódica del operador no puede decidir desde el bullet solo (matriz impact × effort, ownership). + +Cuando cualquiera de estos se cumple, promueve la entrada FU a un documento TDE bajo `.straymark/06-evolution/technical-debt/`: + +1. Crea el TDE vía `/straymark-new tde` (o `straymark new --type tde`). Llena `impact`, `effort`, `type`, y las secciones del body desde el contexto de la entrada FU. +2. Agrega `promoted_from_followup: FU-NNN` al frontmatter del TDE para trazabilidad. +3. En la entrada FU, establece `Status: promoted`, `Destination: TDE-YYYY-MM-DD-NNN`, y agrega `Promoted to: TDE-YYYY-MM-DD-NNN`. Mueve la entrada a la sección `## Bucket: closed` si mantienes una; si no, déjala en lugar con el nuevo status. + +La entrada FU **no se elimina** tras la promoción — su presencia en el registro es el rastro auditable que muestra de dónde vino el TDE. + +### Cuándo promover + +- **Revisión periódica** — cuando el operador hace el pase manual de reclasificación, promueve cualquier entrada que haya vivido ≥2 cierres de Charter sin resolución y cumpla los criterios anteriores. +- **Cierre de Charter** — al revisar entradas que el Charter recién cerrado resolvió, si encuentras entradas que *no* fueron resueltas y cumplen los criterios anteriores, promuévelas en vez de dejarlas como `open`. +- **Pre-declaración de Charter** — si estás a punto de declarar un Charter y notas que el registro contiene entradas que este Charter *parcialmente* atendería, la porción no atendida puede pertenecer como TDE en vez de como otro FU diferido. + +El script de drift (`scripts/check-followups-drift.sh`) **no se extiende** para candidatos a promoción en v0 — la promoción es operator-driven. Una mejora futura v1 podría flagear entradas que cumplan la heurística "vivió ≥2 Charters", pero eso cristaliza tras un segundo adopter que valide el patrón (misma puerta que el resto de v0 → v1). --- @@ -135,10 +164,10 @@ El agente (Claude / Gemini / etc.) se vuelve el mantenedor primario del registro - **Inicio de sesión**: revisar `.straymark/follow-ups-backlog.md` para saber qué está pendiente en el proyecto. - **Checklist pre-commit**: ¿creaste o modificaste algún AILOG con entradas `## Follow-ups` o `R (new, not in Charter)`? → ejecuta `scripts/check-followups-drift.sh --apply` para extender el backlog en el mismo commit. -- **Post-cierre de Charter**: revisar entradas que el Charter resolvió; marcarlas `closed` (con el id del Charter de cierre en `Notes`) o `superseded`. +- **Post-cierre de Charter**: revisar entradas que el Charter resolvió; marcarlas `closed` (con el id del Charter de cierre en `Notes`) o `superseded`. Para entradas no resueltas que cumplen los criterios de TDE (herencia de Charter previo, transversal, requiere Charter dedicado, necesita priorización humana), promuévelas a un documento TDE (ver "Promoción a TDE" en este patrón + `AGENT-RULES.md §3`). ``` -Esto hace al agente el mantenedor, al script la capa de verificación, y al operador el revisor periódico (re-bucketing, marcar closed, podar superseded). +Esto hace al agente el mantenedor, al script la capa de verificación, y al operador el revisor periódico (re-bucketing, marcar closed, podar superseded, promover a TDE cuando los criterios aplican). --- @@ -186,4 +215,4 @@ Contribuido vía [issue #111](https://github.com/StrangeDaysTech/straymark/issue --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/i18n/es/QUICK-REFERENCE.md b/dist/.straymark/00-governance/i18n/es/QUICK-REFERENCE.md index 3f338d6..8f0767d 100644 --- a/dist/.straymark/00-governance/i18n/es/QUICK-REFERENCE.md +++ b/dist/.straymark/00-governance/i18n/es/QUICK-REFERENCE.md @@ -81,6 +81,7 @@ Los Charters **no** son tipos de documento — envuelven un bloque de implementa | Cambios en dependencias críticas de seguridad | AILOG + revisión humana | | Cambios en instrumentación OTel | AILOG + tag `observabilidad` | | Bloque de implementación multi-sesión (>1 día, >5 tareas en varias fases) | Declarar un **Charter** (`straymark charter new`) | +| Deuda técnica transversal (herencia de Charter previo, aplica a múltiples módulos, requiere Charter dedicado, necesita priorización humana) | **TDE** — distinto del `R` por Charter; ver AGENT-RULES.md §3 | **NO documentar**: credenciales, tokens, PII, secretos. @@ -215,4 +216,4 @@ Marcar `review_required: true` cuando: --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/i18n/zh-CN/AGENT-RULES.md b/dist/.straymark/00-governance/i18n/zh-CN/AGENT-RULES.md index fe9beb0..169c13f 100644 --- a/dist/.straymark/00-governance/i18n/zh-CN/AGENT-RULES.md +++ b/dist/.straymark/00-governance/i18n/zh-CN/AGENT-RULES.md @@ -39,6 +39,7 @@ confidence: high | medium | low | 添加/移除/升级安全关键依赖 | AILOG | 需要人工审查 | | 影响 AI 系统生命周期的变更（部署、退役） | AILOG + ADR | 需要人工审查 | | OTel 仪表化变更（spans、attributes、pipeline） | AILOG | 标签 `observabilidad`，参见 §9 | +| 实施过程中发现的横向技术债务 | TDE | 参见 §3 "TDE vs `R`（new, not in Charter）" 的判定标准 | ### 禁止事项 - 不得记录 @@ -99,6 +100,25 @@ confidence: high | medium | low | TDE | 技术债务 | | INC | 事故总结 | +### TDE vs `R（new, not in Charter）` + +对于涌现的债务存在两个记录面。它们不可互换——根据工作的生命周期来选择，而不是就手的那一个。 + +**在 AILOG 的 `§Risk` 节中登记一条 `R（new, not in Charter）`**，当该债务： + +- *局限于正在执行的 Charter* 或序列中的下一个 Charter。 +- 可作为已记录的延期、一个小的原子修复，或指向一个已存在的 Charter 的前向引用来解决。 +- 影响为低到中等，且代理可用一条要点描述修复方式。 + +**创建 TDE 文档**，当该债务： + +- 是 *先前 Charter 的遗留*（该缺陷早于当前正在执行的工作）。 +- *横跨多个模块或多个 Charter* —— 将其拆分为各 Charter 的 `R` 条目会丢失其架构形态。 +- *需要在当前 scope 包络之外的专用 Charter* 来修复（不是当前 Charter，也不是下一个）。 +- *需要人工决定优先级或分配*，代理无法独自决定（impact × effort 矩阵、所有权、Sprint 安排）。 + +上述四项触发条件即 §2 中 TDE 的激活标准。当你即将编写的 AILOG 中的 `R` 命中上述任一条件时，转而编写 TDE，并在该 AILOG 的 `§Risk` 行中引用它。 + --- ## 4. 何时请求人工审查 @@ -352,4 +372,4 @@ confidence: high | medium | low --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md b/dist/.straymark/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md index 978ef16..7107ac4 100644 --- a/dist/.straymark/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md +++ b/dist/.straymark/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md @@ -234,4 +234,4 @@ Rel(api, db, "Reads/Writes", "SQL") --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md b/dist/.straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md index c49ebba..91b5b76 100644 --- a/dist/.straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md +++ b/dist/.straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md @@ -299,4 +299,4 @@ review_outcome: approved # approved | revisions_requested | rejec --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md b/dist/.straymark/00-governance/i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md index 8be31e7..8b0a7c9 100644 --- a/dist/.straymark/00-governance/i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md +++ b/dist/.straymark/00-governance/i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md @@ -77,11 +77,12 @@ bucket 内的每个条目遵循以下形式: ```markdown ### FU-NNN — <简短描述> - **Origin**: AILOG-NNNN-NN-NN-NNN <指向源部分的指针> -- **Status**: open | in-progress | closed | superseded +- **Status**: open | in-progress | closed | superseded | promoted - **Trigger**: ready | <日历日期> | when | <其他> -- **Destination**: +- **Destination**: - **Cost**: <工作量估计> - **Notes**: <自由格式上下文> +- **Promoted to**: ``` `FU-NNN` 在注册表整个生命周期内单调递增;条目关闭时不重新编号。 @@ -92,8 +93,36 @@ bucket 内的每个条目遵循以下形式: - `in-progress` — 已声明或正在执行的 Charter 处理此条目。 - `closed` — 条目已解决(Charter 已合并、操作任务已完成、时间已过且已审查)。 - `superseded` — 由其他工作处理,该工作未直接引用此条目。 +- `promoted` — 条目因满足横向债务标准而被提升为 TDE 文档(见下方"提升为 TDE")。`Promoted to:` 字段携带 TDE id。 -closed 和 superseded 条目保留在文件中(可审计的历史)。操作员可以将它们移到底部的 `## Bucket: closed` 部分以进行视觉整理,但绝不删除。 +closed、superseded 和 promoted 条目保留在文件中(可审计的历史)。操作员可以将它们移到底部的 `## Bucket: closed` 部分以进行视觉整理,但绝不删除。 + +--- + +## 提升为 TDE + +某些 FU 条目不仅仅是延期任务 —— 它们描述的是值得拥有自己治理文档的**横向技术债务**(TDE)。提升标准与 `AGENT-RULES.md §3` 中的 TDE-vs-`R` 判定一致: + +- 该条目是*先前 Charter 的遗留*(已经历 ≥1 次 Charter 关闭仍未修复)。 +- 该条目*横跨多个模块或多个 Charter* —— 中央注册表已将其碎片化为共享同一根本原因的多个 bullet。 +- 该条目*需要在当前 scope 包络之外的专用 Charter* 来修复。 +- 该条目*需要人工决定优先级或分配*,操作员的周期性审查无法仅从 bullet 决定(impact × effort 矩阵、所有权)。 + +当上述任一条件成立时,将该 FU 条目提升为 `.straymark/06-evolution/technical-debt/` 下的 TDE 文档: + +1. 通过 `/straymark-new tde`(或 `straymark new --type tde`)创建 TDE。从 FU 条目的上下文填入 `impact`、`effort`、`type` 与正文各节。 +2. 在 TDE 的 frontmatter 中添加 `promoted_from_followup: FU-NNN` 以便溯源。 +3. 在 FU 条目中,设置 `Status: promoted`、`Destination: TDE-YYYY-MM-DD-NNN`,并添加 `Promoted to: TDE-YYYY-MM-DD-NNN`。如果你维护 `## Bucket: closed` 节,则将条目移过去;否则保持原位并更新状态。 + +FU 条目在提升后**不会被删除** —— 它在注册表中的存在就是显示 TDE 来源的审计轨迹。 + +### 何时提升 + +- **周期性审查** —— 当操作员做人工重新分类时,提升任何已经历 ≥2 次 Charter 关闭仍未解决且符合上述标准的条目。 +- **Charter 关闭** —— 在审查刚关闭的 Charter 所解决的条目时,如果发现*未*被解决且符合上述标准的条目,则提升它们,而不是保留为 `open`。 +- **Charter 声明前** —— 如果你即将声明一个 Charter,并注意到注册表中包含此 Charter 仅会*部分*处理的条目,那么未处理的部分可能应作为 TDE,而不是作为另一个被延期的 FU。 + +Drift 脚本(`scripts/check-followups-drift.sh`)在 v0 **不扩展**支持提升候选 —— 提升由操作员驱动。未来 v1 增强可标记符合"经历 ≥2 个 Charter"启发式的条目,但这等到第二个 adopter 验证模式后才会固化(与 v0 → v1 其余部分相同的门槛)。 --- @@ -135,10 +164,10 @@ AILOG_DIR=".straymark/07-ai-audit/agent-logs" - **会话开始**: 浏览 `.straymark/follow-ups-backlog.md` 以了解项目中所有待处理事项。 - **Pre-commit 检查**: 创建或修改了任何带有 `## Follow-ups` 或 `R (new, not in Charter)` 条目的 AILOG 吗? → 在同一个 commit 中运行 `scripts/check-followups-drift.sh --apply` 以扩展 backlog。 -- **Charter 关闭后**: 审查 Charter 解决的条目;将其标记为 `closed`(在 `Notes` 中带有关闭 Charter id)或 `superseded`。 +- **Charter 关闭后**: 审查 Charter 解决的条目;将其标记为 `closed`(在 `Notes` 中带有关闭 Charter id)或 `superseded`。对于未解决但符合 TDE 标准的条目(先前 Charter 的遗留、横向、需要专用 Charter、需要人工优先级),将其提升为 TDE 文档(见本模式的"提升为 TDE"以及 `AGENT-RULES.md §3`)。 ``` -这使代理成为维护者,脚本成为验证层,操作员成为周期性审查者(重新分类、标记 closed、修剪 superseded)。 +这使代理成为维护者,脚本成为验证层,操作员成为周期性审查者(重新分类、标记 closed、修剪 superseded、在符合标准时提升为 TDE)。 --- @@ -186,4 +215,4 @@ AILOG_DIR=".straymark/07-ai-audit/agent-logs" --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/00-governance/i18n/zh-CN/QUICK-REFERENCE.md b/dist/.straymark/00-governance/i18n/zh-CN/QUICK-REFERENCE.md index 32fb3ff..b458e50 100644 --- a/dist/.straymark/00-governance/i18n/zh-CN/QUICK-REFERENCE.md +++ b/dist/.straymark/00-governance/i18n/zh-CN/QUICK-REFERENCE.md @@ -81,6 +81,7 @@ Charter **不是**文档类型——它包裹一个跨多个会话的实施块 | 安全关键依赖变更 | AILOG + 人工审核 | | OTel 埋点变更 | AILOG + 标签 `observabilidad` | | 跨多个会话的实施块（>1 天，跨多个阶段 >5 个任务） | 声明一个 **Charter**（`straymark charter new`） | +| 横向技术债务（先前 Charter 的遗留、横跨多个模块、需要专用 Charter、需要人工优先级） | **TDE** —— 与单 Charter 的 `R` 不同；参见 AGENT-RULES.md §3 | **不要记录**：凭据、令牌、PII、机密信息。 @@ -215,4 +216,4 @@ risk_level: low | medium | high | critical --- -*StrayMark v4.12.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/QUICK-REFERENCE.md b/dist/.straymark/QUICK-REFERENCE.md index ef9044c..e6ac38c 100644 --- a/dist/.straymark/QUICK-REFERENCE.md +++ b/dist/.straymark/QUICK-REFERENCE.md @@ -168,4 +168,4 @@ Mark `review_required: true` when: --- -*StrayMark v4.12.0 | [GitHub](https://github.com/StrangeDaysTech/straymark) | [Strange Days Tech](https://strangedays.tech)* +*StrayMark v4.13.0 | [GitHub](https://github.com/StrangeDaysTech/straymark) | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.straymark/templates/TEMPLATE-TDE.md b/dist/.straymark/templates/TEMPLATE-TDE.md index 9dbce6f..91aef9f 100644 --- a/dist/.straymark/templates/TEMPLATE-TDE.md +++ b/dist/.straymark/templates/TEMPLATE-TDE.md @@ -15,11 +15,14 @@ tags: [] related: [] priority: null assigned_to: null +promoted_from_followup: null # FU-NNN if promoted from .straymark/follow-ups-backlog.md --- # TDE: [Technical Debt Title] > **IDENTIFIED BY AGENT**: Prioritization and assignment require human decision. +> +> **Activation triggers** (any one suffices — file as `R (new, not in Charter)` in an AILOG instead if none apply): heritage from a prior Charter, applies to multiple modules/Charters, requires a dedicated Charter outside the current scope envelope, or requires human prioritization/assignment the agent cannot decide alone. See `.straymark/00-governance/AGENT-RULES.md` §3 for the full disambiguation. ## Summary diff --git a/dist/.straymark/templates/i18n/es/TEMPLATE-TDE.md b/dist/.straymark/templates/i18n/es/TEMPLATE-TDE.md index e38d713..cf1ddd9 100644 --- a/dist/.straymark/templates/i18n/es/TEMPLATE-TDE.md +++ b/dist/.straymark/templates/i18n/es/TEMPLATE-TDE.md @@ -15,11 +15,14 @@ tags: [] related: [] priority: null assigned_to: null +promoted_from_followup: null # FU-NNN si fue promovido desde .straymark/follow-ups-backlog.md --- # TDE: [Título de la Deuda Técnica] > **IDENTIFICADO POR AGENTE**: La priorización y asignación requieren decisión humana. +> +> **Triggers de activación** (basta con cualquiera — si ninguno aplica, registra como `R (new, not in Charter)` en un AILOG en su lugar): herencia de un Charter previo, aplica a múltiples módulos/Charters, requiere un Charter dedicado fuera del envelope de scope actual, o requiere priorización/asignación humana que el agente no puede decidir solo. Ver `.straymark/00-governance/AGENT-RULES.md` §3 para la desambiguación completa. ## Resumen diff --git a/dist/.straymark/templates/i18n/zh-CN/TEMPLATE-TDE.md b/dist/.straymark/templates/i18n/zh-CN/TEMPLATE-TDE.md index 3aee4f8..a275933 100644 --- a/dist/.straymark/templates/i18n/zh-CN/TEMPLATE-TDE.md +++ b/dist/.straymark/templates/i18n/zh-CN/TEMPLATE-TDE.md @@ -15,11 +15,14 @@ tags: [] related: [] priority: null assigned_to: null +promoted_from_followup: null # FU-NNN，如果从 .straymark/follow-ups-backlog.md 提升而来 --- # TDE: [技术债务标题] > **由代理识别**：优先级排序和任务分配需要人工决策。 +> +> **激活触发条件**（任意一条满足即可——若均不满足，请改在 AILOG 中以 `R (new, not in Charter)` 记录）：先前 Charter 的遗留、横跨多个模块/Charter、需要当前 scope 包络之外的专用 Charter、或需要代理无法独自决定的人工优先级或分配。完整判定请参见 `.straymark/00-governance/AGENT-RULES.md` §3。 ## 摘要 diff --git a/dist/STRAYMARK.md b/dist/STRAYMARK.md index f57fd41..fa4a1d2 100644 --- a/dist/STRAYMARK.md +++ b/dist/STRAYMARK.md @@ -146,6 +146,7 @@ gh pr create --title "fix: description" --body "..." | Security-critical dependency changes | Create AILOG + human review | | OTel instrumentation changes | Create AILOG + tag `observabilidad` | | Multi-session implementation block (>1 day, >5 tasks across phases) | Declare a **Charter** — `straymark charter new`. See section 15. | +| Transversal technical debt — heritage from prior Charter, applies to multiple modules, or requires dedicated Charter to remediate | Create **TDE** — distinct from per-Charter `R`. See `.straymark/00-governance/AGENT-RULES.md` §3 for TDE vs `R` disambiguation. | ### DO NOT DOCUMENT diff --git a/dist/dist-manifest.yml b/dist/dist-manifest.yml index 8db1278..3e9f8db 100644 --- a/dist/dist-manifest.yml +++ b/dist/dist-manifest.yml @@ -1,4 +1,4 @@ -version: "4.12.0" +version: "4.13.0" description: "StrayMark distribution manifest" repository: "https://github.com/StrangeDaysTech/straymark" diff --git a/docs/adopters/ADOPTION-GUIDE.md b/docs/adopters/ADOPTION-GUIDE.md index a4eb43f..51ab38d 100644 --- a/docs/adopters/ADOPTION-GUIDE.md +++ b/docs/adopters/ADOPTION-GUIDE.md @@ -239,7 +239,7 @@ The CLI automatically: 1. **Download the latest release** - Go to [GitHub Releases](https://github.com/StrangeDaysTech/straymark/releases) and download the latest `fw-*` release ZIP (e.g., `fw-4.12.0`). + Go to [GitHub Releases](https://github.com/StrangeDaysTech/straymark/releases) and download the latest `fw-*` release ZIP (e.g., `fw-4.13.0`). 2. **Extract to your project** ```bash diff --git a/docs/adopters/CLI-REFERENCE.md b/docs/adopters/CLI-REFERENCE.md index 52af4c7..56324cb 100644 --- a/docs/adopters/CLI-REFERENCE.md +++ b/docs/adopters/CLI-REFERENCE.md @@ -48,7 +48,7 @@ StrayMark uses **independent version tags** for each component: | Component | Tag prefix | Example | What it includes | |-----------|-----------|---------|------------------| -| Framework | `fw-` | `fw-4.12.0` | Templates (12 types), governance docs, directives, Charter template + schema | +| Framework | `fw-` | `fw-4.13.0` | Templates (12 types), governance docs, directives, Charter template + schema | | CLI | `cli-` | `cli-3.12.0` | The `straymark` binary | Framework and CLI are released independently. A framework update does not require a CLI update, and vice versa. @@ -88,7 +88,7 @@ Initialize StrayMark in a project directory. ```bash $ straymark init . -✔ Downloaded StrayMark fw-4.12.0 +✔ Downloaded StrayMark fw-4.13.0 ✔ Created .straymark/ directory structure ✔ Created STRAYMARK.md ✔ Configured AI agent directives @@ -110,7 +110,7 @@ If `.straymark/` does not exist in the current directory, the framework update i ```bash $ straymark update Updating framework... -✔ Framework updated to fw-4.12.0 +✔ Framework updated to fw-4.13.0 Updating CLI... ✔ CLI updated to cli-3.5.2 ``` @@ -127,7 +127,7 @@ Update only the framework files. Looks for the latest `fw-*` release on GitHub. ```bash $ straymark update-framework -✔ Framework updated to fw-4.12.0 +✔ Framework updated to fw-4.13.0 ``` --- @@ -211,7 +211,7 @@ $ straymark status Project ┌───────────┬──────────────────────────┐ │ Path │ /home/user/my-project │ - │ Framework │ fw-4.12.0 │ + │ Framework │ fw-4.13.0 │ │ CLI │ cli-3.5.2 │ │ Language │ en │ └───────────┴──────────────────────────┘ @@ -268,7 +268,7 @@ Repairing StrayMark in /home/user/my-project → Restoring 1 missing directory... ✓ Restored .straymark/templates/ → Downloading framework to restore missing files... - Using version: fw-4.12.0 + Using version: fw-4.13.0 ✓ Restored 16 file(s) from framework → Updating checksums... @@ -1053,7 +1053,7 @@ Show version, authorship, and license information. $ straymark about StrayMark CLI CLI version: cli-3.5.2 - Framework version: fw-4.12.0 + Framework version: fw-4.13.0 Author: Strange Days Tech, S.A.S. License: MIT Repository: https://github.com/StrangeDaysTech/straymark @@ -1076,7 +1076,7 @@ StrayMark ships a set of skills (slash commands) for use inside an AI assistant | `/straymark-new` | Create any document type interactively. Suggests best fit from context. | `.straymark//-YYYY-MM-DD-NNN-*.md` | | `/straymark-ailog` | Quick AILOG creation shortcut. | `.straymark/07-ai-audit/agent-logs/AILOG-*.md` | | `/straymark-aidec` | Quick AIDEC creation shortcut. | `.straymark/07-ai-audit/decisions/AIDEC-*.md` | -| `/straymark-adr` | Quick ADR creation shortcut. | `.straymark/04-architecture/decisions/ADR-*.md` | +| `/straymark-adr` | Quick ADR creation shortcut. | `.straymark/02-design/decisions/ADR-*.md` | | `/straymark-mcard` | Interactive Model Card creation flow. | `.straymark/09-ai-models/MCARD-*.md` | | `/straymark-sec` | Interactive SEC (security assessment) flow. | `.straymark/08-security/SEC-*.md` | | `/straymark-audit-prompt CHARTER-ID` *(fw-4.9.0+, refactored in fw-4.9.0)* | Generate the unified audit prompt for a Charter at the canonical path. Wraps `straymark charter audit --prepare`. The operator then opens N auditor CLIs in the same repo and invokes `/straymark-audit-execute` in each — no copy/paste. | `.straymark/audits//audit-prompt.md` | diff --git a/docs/i18n/es/README.md b/docs/i18n/es/README.md index 667db82..9f3043c 100644 --- a/docs/i18n/es/README.md +++ b/docs/i18n/es/README.md @@ -237,7 +237,7 @@ StrayMark usa tags de versión independientes para cada componente: | Componente | Prefijo de tag | Ejemplo | Incluye | |------------|---------------|---------|---------| -| Framework | `fw-` | `fw-4.12.0` | Plantillas (12 tipos), gobernanza, directivas, plantilla + schema de Charter | +| Framework | `fw-` | `fw-4.13.0` | Plantillas (12 tipos), gobernanza, directivas, plantilla + schema de Charter | | CLI | `cli-` | `cli-3.12.0` | El binario `straymark` | Verifica las versiones instaladas con `straymark status` o `straymark about`. @@ -270,7 +270,7 @@ Ver [Referencia CLI](adopters/CLI-REFERENCE.md) para uso detallado. ```bash # Descargar el último release ZIP del framework desde GitHub # Ve a https://github.com/StrangeDaysTech/straymark/releases -# y descarga el último release fw-* (ej. fw-4.12.0) +# y descarga el último release fw-* (ej. fw-4.13.0) # Extraer y copiar a tu proyecto unzip straymark-fw-*.zip -d tu-proyecto/ diff --git a/docs/i18n/es/adopters/ADOPTION-GUIDE.md b/docs/i18n/es/adopters/ADOPTION-GUIDE.md index 453f060..9411d80 100644 --- a/docs/i18n/es/adopters/ADOPTION-GUIDE.md +++ b/docs/i18n/es/adopters/ADOPTION-GUIDE.md @@ -230,7 +230,7 @@ El CLI automáticamente: 1. **Descargar el último release** - Ve a [GitHub Releases](https://github.com/StrangeDaysTech/straymark/releases) y descarga el último release `fw-*` (ej. `fw-4.12.0`). + Ve a [GitHub Releases](https://github.com/StrangeDaysTech/straymark/releases) y descarga el último release `fw-*` (ej. `fw-4.13.0`). 2. **Extraer en tu proyecto** ```bash diff --git a/docs/i18n/es/adopters/CLI-REFERENCE.md b/docs/i18n/es/adopters/CLI-REFERENCE.md index 7b7fc20..ab70b25 100644 --- a/docs/i18n/es/adopters/CLI-REFERENCE.md +++ b/docs/i18n/es/adopters/CLI-REFERENCE.md @@ -48,7 +48,7 @@ StrayMark usa **tags de versión independientes** para cada componente: | Componente | Prefijo de tag | Ejemplo | Qué incluye | |------------|---------------|---------|-------------| -| Framework | `fw-` | `fw-4.12.0` | Plantillas (12 tipos), docs de gobernanza, directivas | +| Framework | `fw-` | `fw-4.13.0` | Plantillas (12 tipos), docs de gobernanza, directivas | | CLI | `cli-` | `cli-3.12.0` | El binario `straymark` | Framework y CLI se publican de forma independiente. Una actualización del framework no requiere actualización del CLI, y viceversa. @@ -88,7 +88,7 @@ Inicializa StrayMark en un directorio de proyecto. ```bash $ straymark init . -✔ Downloaded StrayMark fw-4.12.0 +✔ Downloaded StrayMark fw-4.13.0 ✔ Created .straymark/ directory structure ✔ Created STRAYMARK.md ✔ Configured AI agent directives @@ -109,7 +109,7 @@ Si `.straymark/` no existe en el directorio actual, la actualización del framew ```bash $ straymark update Updating framework... -✔ Framework updated to fw-4.12.0 +✔ Framework updated to fw-4.13.0 Updating CLI... ✔ CLI updated to cli-3.5.2 ``` @@ -126,7 +126,7 @@ Actualiza solo los archivos del framework. Busca el último release `fw-*` en Gi ```bash $ straymark update-framework -✔ Framework updated to fw-4.12.0 +✔ Framework updated to fw-4.13.0 ``` --- @@ -205,7 +205,7 @@ $ straymark status StrayMark Status ─────────────── Path: /home/user/my-project -Framework version: fw-4.12.0 +Framework version: fw-4.13.0 CLI version: cli-3.5.2 Language: en Structure: ✔ Complete @@ -859,7 +859,7 @@ Muestra información de versión, autoría y licencia. $ straymark about StrayMark CLI CLI version: cli-3.5.2 - Framework version: fw-4.12.0 + Framework version: fw-4.13.0 Author: Strange Days Tech, S.A.S. License: MIT Repository: https://github.com/StrangeDaysTech/straymark @@ -882,7 +882,7 @@ StrayMark incluye un conjunto de skills (slash commands) para usar dentro de un | `/straymark-new` | Crear cualquier tipo de documento interactivamente. Sugiere el más adecuado al contexto. | `.straymark//-YYYY-MM-DD-NNN-*.md` | | `/straymark-ailog` | Atajo de creación rápida de AILOG. | `.straymark/07-ai-audit/agent-logs/AILOG-*.md` | | `/straymark-aidec` | Atajo de creación rápida de AIDEC. | `.straymark/07-ai-audit/decisions/AIDEC-*.md` | -| `/straymark-adr` | Atajo de creación rápida de ADR. | `.straymark/04-architecture/decisions/ADR-*.md` | +| `/straymark-adr` | Atajo de creación rápida de ADR. | `.straymark/02-design/decisions/ADR-*.md` | | `/straymark-mcard` | Flujo interactivo de creación de Model Card. | `.straymark/09-ai-models/MCARD-*.md` | | `/straymark-sec` | Flujo interactivo SEC (security assessment). | `.straymark/08-security/SEC-*.md` | | `/straymark-audit-prompt CHARTER-ID` *(fw-4.9.0+, refactorizada en fw-4.9.0)* | Genera la plantilla unificada del audit prompt para un Charter en el path canónico. Envuelve `straymark charter audit --prepare`. El operador entonces abre N CLIs auditoras en el mismo repo e invoca `/straymark-audit-execute` en cada una — sin copy/paste. | `.straymark/audits//audit-prompt.md` | diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md index 253c460..5dfab6a 100644 --- a/docs/i18n/zh-CN/README.md +++ b/docs/i18n/zh-CN/README.md @@ -255,7 +255,7 @@ StrayMark 为每个组件使用独立的版本标签： | 组件 | 标签前缀 | 示例 | 包含内容 | |------|----------|------|----------| -| Framework | `fw-` | `fw-4.12.0` | 模板（12 种类型）、治理文档、指令、Charter 模板 + schema | +| Framework | `fw-` | `fw-4.13.0` | 模板（12 种类型）、治理文档、指令、Charter 模板 + schema | | CLI | `cli-` | `cli-3.12.0` | `straymark` 二进制文件 | 使用 `straymark status` 或 `straymark about` 查看已安装的版本。 @@ -288,7 +288,7 @@ StrayMark 为每个组件使用独立的版本标签： ```bash # 从 GitHub 下载最新的框架发布 ZIP # 前往 https://github.com/StrangeDaysTech/straymark/releases -# 下载最新的 fw-* 发布（例如 fw-4.12.0） +# 下载最新的 fw-* 发布（例如 fw-4.13.0） # 解压并复制到你的项目 unzip straymark-fw-*.zip -d your-project/ diff --git a/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md b/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md index 88033e2..a2c1368 100644 --- a/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md +++ b/docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md @@ -239,7 +239,7 @@ CLI 自动完成： 1. **下载最新版本** - 前往 [GitHub Releases](https://github.com/StrangeDaysTech/straymark/releases)，下载最新的 `fw-*` 版本 ZIP（例如 `fw-4.12.0`）。 + 前往 [GitHub Releases](https://github.com/StrangeDaysTech/straymark/releases)，下载最新的 `fw-*` 版本 ZIP（例如 `fw-4.13.0`）。 2. **解压到你的项目** ```bash diff --git a/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md b/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md index 1ba31a5..e76d431 100644 --- a/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md +++ b/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md @@ -48,7 +48,7 @@ StrayMark 为每个组件使用**独立的版本标签**： | 组件 | 标签前缀 | 示例 | 包含内容 | |------|----------|------|----------| -| Framework | `fw-` | `fw-4.12.0` | 模板（12 种类型）、治理文档、指令 | +| Framework | `fw-` | `fw-4.13.0` | 模板（12 种类型）、治理文档、指令 | | CLI | `cli-` | `cli-3.12.0` | `straymark` 二进制文件 | Framework 和 CLI 独立发布。Framework 更新不需要 CLI 更新，反之亦然。 @@ -88,7 +88,7 @@ straymark status # 显示完整的安装状态，包括版本 ```bash $ straymark init . -✔ Downloaded StrayMark fw-4.12.0 +✔ Downloaded StrayMark fw-4.13.0 ✔ Created .straymark/ directory structure ✔ Created STRAYMARK.md ✔ Configured AI agent directives @@ -110,7 +110,7 @@ Next: git add .straymark/ STRAYMARK.md && git commit -m "chore: adopt StrayMark" ```bash $ straymark update Updating framework... -✔ Framework updated to fw-4.12.0 +✔ Framework updated to fw-4.13.0 Updating CLI... ✔ CLI updated to cli-3.5.2 ``` @@ -127,7 +127,7 @@ Updating CLI... ```bash $ straymark update-framework -✔ Framework updated to fw-4.12.0 +✔ Framework updated to fw-4.13.0 ``` --- @@ -211,7 +211,7 @@ $ straymark status Project ┌───────────┬──────────────────────────┐ │ Path │ /home/user/my-project │ - │ Framework │ fw-4.12.0 │ + │ Framework │ fw-4.13.0 │ │ CLI │ cli-3.5.2 │ │ Language │ en │ └───────────┴──────────────────────────┘ @@ -268,7 +268,7 @@ Repairing StrayMark in /home/user/my-project → Restoring 1 missing directory... ✓ Restored .straymark/templates/ → Downloading framework to restore missing files... - Using version: fw-4.12.0 + Using version: fw-4.13.0 ✓ Restored 16 file(s) from framework → Updating checksums... @@ -993,7 +993,7 @@ $ straymark explore --lang es # 会话内切换到西班牙语 $ straymark about StrayMark CLI CLI version: cli-3.5.2 - Framework version: fw-4.12.0 + Framework version: fw-4.13.0 Author: Strange Days Tech, S.A.S. License: MIT Repository: https://github.com/StrangeDaysTech/straymark @@ -1016,7 +1016,7 @@ StrayMark 提供一组 skills（slash 命令）供 AI 助手内使用（Claude C | `/straymark-new` | 交互式创建任意类型的文档。从上下文建议最佳匹配。 | `.straymark//-YYYY-MM-DD-NNN-*.md` | | `/straymark-ailog` | 快速 AILOG 创建快捷方式。 | `.straymark/07-ai-audit/agent-logs/AILOG-*.md` | | `/straymark-aidec` | 快速 AIDEC 创建快捷方式。 | `.straymark/07-ai-audit/decisions/AIDEC-*.md` | -| `/straymark-adr` | 快速 ADR 创建快捷方式。 | `.straymark/04-architecture/decisions/ADR-*.md` | +| `/straymark-adr` | 快速 ADR 创建快捷方式。 | `.straymark/02-design/decisions/ADR-*.md` | | `/straymark-mcard` | 交互式 Model Card 创建流程。 | `.straymark/09-ai-models/MCARD-*.md` | | `/straymark-sec` | 交互式 SEC（安全评估）流程。 | `.straymark/08-security/SEC-*.md` | | `/straymark-audit-prompt CHARTER-ID` *(fw-4.9.0+，在 fw-4.9.0 中重构)* | 在规范路径处生成章程的统一审计 prompt。封装 `straymark charter audit --prepare`。操作员随后在同一仓库中打开 N 个审计员 CLI，在每个中调用 `/straymark-audit-execute` — 无需复制/粘贴。 | `.straymark/audits//audit-prompt.md` | From e128b2862f47ff8de0839eaeac73b356ec26c128 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Villase=C3=B1or=20Montfort?= <195970+montfort@users.noreply.github.com> Date: Mon, 11 May 2026 13:39:21 -0600 Subject: [PATCH 3/3] =?UTF-8?q?fix(cli):=20cli-3.12.1=20=E2=80=94=20valida?= =?UTF-8?q?tor=20accepts=20TDE=20`identified`=20status=20(closes=20#130)?= =?UTF-8?q?=20(#131)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Latent bug exposed by #129's TDE activation trigger: `straymark new --doc-type tde` shipped documents with the canonical `status: identified` (per TEMPLATE-TDE.md and DOCUMENTATION-POLICY.md §6), but `straymark validate` rejected them with META-003. The validator's hardcoded VALID_STATUSES was missing the only non-`draft`/non-`accepted` default in the type matrix. Fixed (CLI): - validation.rs:45 — VALID_STATUSES now includes `identified` alongside draft/review/accepted/superseded/deprecated. Flat enum still applies to all 12+ doc types; per-type validation sets deferred to v1 against the same second-adopter gate as the follow-ups CLI. - cli/tests/validate_test.rs — new regression test `test_validate_tde_document_valid()` exercises `status: identified`. TDD red→green verified: test fails on unpatched validator, passes after the fix. Changed (Framework, no separate version bump — ships with fw-4.13.0): - DOCUMENTATION-POLICY.md §3 "Document Statuses" (EN + ES + zh-CN): lifecycle diagram extended to show `identified` as a TDE-only entry state. Reconciles §3 prose with the §6 per-type defaults table that already declared TDE → `identified`. Co-authored-by: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 20 ++++++++++++++++ README.md | 2 +- cli/Cargo.lock | 2 +- cli/Cargo.toml | 2 +- cli/src/validation.rs | 14 +++++++++-- cli/tests/validate_test.rs | 23 +++++++++++++++++++ .../00-governance/DOCUMENTATION-POLICY.md | 14 +++++++---- .../i18n/es/DOCUMENTATION-POLICY.md | 14 +++++++---- .../i18n/zh-CN/DOCUMENTATION-POLICY.md | 14 +++++++---- docs/adopters/CLI-REFERENCE.md | 2 +- docs/i18n/es/README.md | 2 +- docs/i18n/es/adopters/CLI-REFERENCE.md | 2 +- docs/i18n/zh-CN/README.md | 2 +- docs/i18n/zh-CN/adopters/CLI-REFERENCE.md | 2 +- 14 files changed, 93 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2a7f463..9380d8a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,26 @@ and this project uses [independent versioning](README.md#versioning) for Framewo --- +## CLI 3.12.1 — Validator accepts TDE `identified` status + +Closes [#130](https://github.com/StrangeDaysTech/straymark/issues/130). Latent in `cli-3.12.0` and earlier; fully exposed by the `fw-4.13.0` TDE activation trigger (which makes TDE creation likely). Surfaced empirically while verifying #128: a freshly-created TDE via `straymark new --doc-type tde` shipped with the canonical `status: identified` per `TEMPLATE-TDE.md` + `DOCUMENTATION-POLICY.md §6`, but `straymark validate` immediately rejected it with `META-003 Invalid status 'identified'`. Validator's hardcoded enumeration was missing the only non-`draft`/non-`accepted` default in the type matrix. + +### Fixed (CLI) + +- **`validation.rs:45`** — `VALID_STATUSES` now includes `identified` alongside `draft`, `review`, `accepted`, `superseded`, `deprecated`. No per-doc-type dispatch yet — flat list still applies to all 12+ document types, but every documented default now lives in the list. A per-type validation set is deferred to v1 against a second-adopter validation gate (same gate as the follow-ups CLI per `FOLLOW-UPS-BACKLOG-PATTERN.md`). +- **`cli/tests/validate_test.rs`** — new regression test `test_validate_tde_document_valid()` exercises the canonical `status: identified` flow. The test fails against unpatched validators (proven during TDD) and would have caught the bug at `fw-4.13.0` ship time. + +### Changed (Framework) + +- **`DOCUMENTATION-POLICY.md §3 "Document Statuses"`** (EN + ES + zh-CN) — lifecycle diagram and table extended to document `identified` as the TDE-only entry state. Functionally equivalent to `draft` for lifecycle gating, semantically distinct so adopter analytics can distinguish "agent-discovered debt" from "human-drafted document". Reconciles §3 prose with the §6 per-type default table that already declared TDE → `identified`. Ships as part of `fw-4.13.0` — no separate framework bump. + +### Adopter guidance + +- Adopters on `cli-3.12.0` or earlier with one or more TDE documents in `06-evolution/technical-debt/` will see `straymark validate` start passing once they upgrade via `straymark update-cli`. No document edits required; the canonical `status: identified` is now accepted. +- Operators who manually changed TDE documents to `status: draft` to work around the bug may revert to `status: identified` for semantic clarity, but the workaround keeps working too. + +--- + ## Framework 4.13.0 — TDE activation trigger Closes [#128](https://github.com/StrangeDaysTech/straymark/issues/128). The TDE (Technical Debt) document type had structural shape — template, destination folder, autonomy boundary — but no operational activation trigger in the agent-facing governance. Empirical signal from the Sentinel adopter (primary, fw-4.12.0): zero TDEs created across 13 closed Charters despite ≥7 instances of transversal debt being routed through parallel mechanisms (`R (new, not in Charter)` in AILOG `§Risk`, or follow-ups in `follow-ups-backlog.md`). This release adds the trigger and the `R` vs TDE disambiguation, plus a promotion path from the follow-ups backlog. Governance-docs-only — no CLI changes; the `straymark debt list/status/close` subcommand trio is deferred to v1 (same gate as the follow-ups CLI per `FOLLOW-UPS-BACKLOG-PATTERN.md`). diff --git a/README.md b/README.md index e58416f..5ba0b14 100644 --- a/README.md +++ b/README.md @@ -275,7 +275,7 @@ StrayMark uses independent version tags for each component: | Component | Tag prefix | Example | Includes | |-----------|-----------|---------|----------| | Framework | `fw-` | `fw-4.13.0` | Templates (12 types), governance, directives, Charter template + schema | -| CLI | `cli-` | `cli-3.12.0` | The `straymark` binary | +| CLI | `cli-` | `cli-3.12.1` | The `straymark` binary | Check installed versions with `straymark status` or `straymark about`. diff --git a/cli/Cargo.lock b/cli/Cargo.lock index 9f17009..ebf6e75 100644 --- a/cli/Cargo.lock +++ b/cli/Cargo.lock @@ -2318,7 +2318,7 @@ checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f" [[package]] name = "straymark-cli" -version = "3.12.0" +version = "3.12.1" dependencies = [ "anyhow", "arborist-metrics", diff --git a/cli/Cargo.toml b/cli/Cargo.toml index 1d4e19d..970648f 100644 --- a/cli/Cargo.toml +++ b/cli/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "straymark-cli" -version = "3.12.0" +version = "3.12.1" edition = "2021" description = "CLI for StrayMark — the cognitive discipline your AI-assisted projects need" license = "MIT" diff --git a/cli/src/validation.rs b/cli/src/validation.rs index a2de761..5078ab2 100644 --- a/cli/src/validation.rs +++ b/cli/src/validation.rs @@ -41,8 +41,18 @@ impl ValidationResult { } } -/// Valid status values per DOCUMENTATION-POLICY.md -const VALID_STATUSES: &[&str] = &["draft", "review", "accepted", "superseded", "deprecated"]; +/// Valid status values per DOCUMENTATION-POLICY.md §3 lifecycle + §6 per-type defaults. +/// `identified` is the canonical TDE entry state (agent-driven discovery, awaits +/// human prioritization); functionally equivalent to `draft` for lifecycle gating +/// but semantically distinct in adopter analytics. +const VALID_STATUSES: &[&str] = &[ + "draft", + "identified", + "review", + "accepted", + "superseded", + "deprecated", +]; /// Valid risk levels const VALID_RISK_LEVELS: &[&str] = &["low", "medium", "high", "critical"]; diff --git a/cli/tests/validate_test.rs b/cli/tests/validate_test.rs index 805f73d..b3355f5 100644 --- a/cli/tests/validate_test.rs +++ b/cli/tests/validate_test.rs @@ -349,6 +349,29 @@ fn test_validate_dpia_document_valid() { .stdout(predicate::str::contains("passed validation")); } +/// Regression test for issue #130: TDE documents ship with `status: identified` +/// per TEMPLATE-TDE.md and DOCUMENTATION-POLICY.md §6 — the validator must accept +/// it as a valid lifecycle entry state. +#[test] +fn test_validate_tde_document_valid() { + let dir = TempDir::new().unwrap(); + setup_straymark(dir.path()); + + create_doc( + dir.path(), + "06-evolution/technical-debt", + "TDE-2026-05-11-001-architectural-refactor.md", + "id: TDE-2026-05-11-001\ntitle: Architectural Refactor Debt\nstatus: identified\ncreated: 2026-05-11\nagent: claude-code-v1.0\nconfidence: high\nreview_required: false\nrisk_level: medium\ntype: architecture\nimpact: high\neffort: medium\ntags:\n - architecture\nrelated: []\npriority: null\nassigned_to: null", + ); + + let mut cmd = Command::cargo_bin("straymark").unwrap(); + cmd.arg("validate") + .arg(dir.path().to_str().unwrap()) + .assert() + .success() + .stdout(predicate::str::contains("passed validation")); +} + /// F2.QA.02.01 — Also verify that MCARD and DPIA fail without review_required: true #[test] fn test_validate_mcard_requires_review() { diff --git a/dist/.straymark/00-governance/DOCUMENTATION-POLICY.md b/dist/.straymark/00-governance/DOCUMENTATION-POLICY.md index a9930a6..6bc5bb7 100644 --- a/dist/.straymark/00-governance/DOCUMENTATION-POLICY.md +++ b/dist/.straymark/00-governance/DOCUMENTATION-POLICY.md @@ -149,19 +149,25 @@ related: ## 3. Document Statuses ``` -draft ──────► accepted ──────► deprecated - │ │ - │ ▼ - └──────► superseded +identified ──┐ + ├──► draft ──────► accepted ──────► deprecated + │ │ │ + │ │ ▼ + │ └──────► superseded + │ + └──► (TDE-only entry state, see §6) ``` | Status | Description | |--------|-------------| +| `identified` | Entry state for agent-driven discovery types (TDE today). Functionally equivalent to `draft` for lifecycle gating — a human reviewer is expected to prioritize and promote it. Semantically distinct so adopter analytics can distinguish "agent found this debt" from "human is drafting a deliberate doc". | | `draft` | In draft, pending review | | `accepted` | Approved and current | | `deprecated` | Obsolete, but kept as reference | | `superseded` | Replaced by another document | +The per-type default status mapping lives in §6 — most types enter at `draft` or `accepted`, but TDE enters at `identified` per the agent-autonomy boundary (agent identifies, human prioritizes). + --- ## 3.5 Recording Approval diff --git a/dist/.straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md b/dist/.straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md index 57e724a..0dfee6f 100644 --- a/dist/.straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md +++ b/dist/.straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md @@ -149,19 +149,25 @@ related: ## 3. Estados de Documentos ``` -draft ──────► accepted ──────► deprecated - │ │ - │ ▼ - └──────► superseded +identified ──┐ + ├──► draft ──────► accepted ──────► deprecated + │ │ │ + │ │ ▼ + │ └──────► superseded + │ + └──► (estado de entrada TDE-only, ver §6) ``` | Estado | Descripción | |--------|-------------| +| `identified` | Estado de entrada para los tipos de descubrimiento dirigidos por agente (TDE hoy). Funcionalmente equivalente a `draft` para el lifecycle gating — se espera que un revisor humano lo priorice y lo promueva. Semánticamente distinto para que las analíticas del adopter puedan distinguir "el agente encontró esta deuda" de "un humano está redactando un documento deliberado". | | `draft` | En borrador, pendiente de revisión | | `accepted` | Aprobado y vigente | | `deprecated` | Obsoleto, pero se mantiene como referencia | | `superseded` | Reemplazado por otro documento | +El mapeo de status por defecto por tipo vive en §6 — la mayoría de tipos entran en `draft` o `accepted`, pero TDE entra en `identified` por la frontera de autonomía del agente (el agente identifica, el humano prioriza). + --- ## 3.5 Registro de Aprobación diff --git a/dist/.straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md b/dist/.straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md index 91b5b76..4de39d0 100644 --- a/dist/.straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md +++ b/dist/.straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md @@ -149,19 +149,25 @@ related: ## 3. 文档状态 ``` -draft ──────► accepted ──────► deprecated - │ │ - │ ▼ - └──────► superseded +identified ──┐ + ├──► draft ──────► accepted ──────► deprecated + │ │ │ + │ │ ▼ + │ └──────► superseded + │ + └──► (TDE 专用入口状态，见 §6) ``` | 状态 | 说明 | |------|------| +| `identified` | 由代理驱动发现的类型的入口状态（今日仅 TDE）。在生命周期校验上等同于 `draft`——期望人工审阅者来排定优先级并推进。语义上有所区分，以便 adopter 的分析能够区分"代理发现了此债务"与"人工正在起草一份有意识的文档"。 | | `draft` | 草稿中，待审核 | | `accepted` | 已批准且为当前有效版本 | | `deprecated` | 已废弃，但保留作为参考 | | `superseded` | 已被其他文档替代 | +按类型的默认 status 映射位于 §6——大多数类型以 `draft` 或 `accepted` 进入，但 TDE 因代理自主权边界（代理识别、人工排序）以 `identified` 进入。 + --- ## 3.5 审批记录 diff --git a/docs/adopters/CLI-REFERENCE.md b/docs/adopters/CLI-REFERENCE.md index 56324cb..174e771 100644 --- a/docs/adopters/CLI-REFERENCE.md +++ b/docs/adopters/CLI-REFERENCE.md @@ -49,7 +49,7 @@ StrayMark uses **independent version tags** for each component: | Component | Tag prefix | Example | What it includes | |-----------|-----------|---------|------------------| | Framework | `fw-` | `fw-4.13.0` | Templates (12 types), governance docs, directives, Charter template + schema | -| CLI | `cli-` | `cli-3.12.0` | The `straymark` binary | +| CLI | `cli-` | `cli-3.12.1` | The `straymark` binary | Framework and CLI are released independently. A framework update does not require a CLI update, and vice versa. diff --git a/docs/i18n/es/README.md b/docs/i18n/es/README.md index 9f3043c..6351490 100644 --- a/docs/i18n/es/README.md +++ b/docs/i18n/es/README.md @@ -238,7 +238,7 @@ StrayMark usa tags de versión independientes para cada componente: | Componente | Prefijo de tag | Ejemplo | Incluye | |------------|---------------|---------|---------| | Framework | `fw-` | `fw-4.13.0` | Plantillas (12 tipos), gobernanza, directivas, plantilla + schema de Charter | -| CLI | `cli-` | `cli-3.12.0` | El binario `straymark` | +| CLI | `cli-` | `cli-3.12.1` | El binario `straymark` | Verifica las versiones instaladas con `straymark status` o `straymark about`. diff --git a/docs/i18n/es/adopters/CLI-REFERENCE.md b/docs/i18n/es/adopters/CLI-REFERENCE.md index ab70b25..1e73402 100644 --- a/docs/i18n/es/adopters/CLI-REFERENCE.md +++ b/docs/i18n/es/adopters/CLI-REFERENCE.md @@ -49,7 +49,7 @@ StrayMark usa **tags de versión independientes** para cada componente: | Componente | Prefijo de tag | Ejemplo | Qué incluye | |------------|---------------|---------|-------------| | Framework | `fw-` | `fw-4.13.0` | Plantillas (12 tipos), docs de gobernanza, directivas | -| CLI | `cli-` | `cli-3.12.0` | El binario `straymark` | +| CLI | `cli-` | `cli-3.12.1` | El binario `straymark` | Framework y CLI se publican de forma independiente. Una actualización del framework no requiere actualización del CLI, y viceversa. diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md index 5dfab6a..0b72787 100644 --- a/docs/i18n/zh-CN/README.md +++ b/docs/i18n/zh-CN/README.md @@ -256,7 +256,7 @@ StrayMark 为每个组件使用独立的版本标签： | 组件 | 标签前缀 | 示例 | 包含内容 | |------|----------|------|----------| | Framework | `fw-` | `fw-4.13.0` | 模板（12 种类型）、治理文档、指令、Charter 模板 + schema | -| CLI | `cli-` | `cli-3.12.0` | `straymark` 二进制文件 | +| CLI | `cli-` | `cli-3.12.1` | `straymark` 二进制文件 | 使用 `straymark status` 或 `straymark about` 查看已安装的版本。 diff --git a/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md b/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md index e76d431..ada975b 100644 --- a/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md +++ b/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md @@ -49,7 +49,7 @@ StrayMark 为每个组件使用**独立的版本标签**： | 组件 | 标签前缀 | 示例 | 包含内容 | |------|----------|------|----------| | Framework | `fw-` | `fw-4.13.0` | 模板（12 种类型）、治理文档、指令 | -| CLI | `cli-` | `cli-3.12.0` | `straymark` 二进制文件 | +| CLI | `cli-` | `cli-3.12.1` | `straymark` 二进制文件 | Framework 和 CLI 独立发布。Framework 更新不需要 CLI 更新，反之亦然。