Merge pull request #336 from StrangeDaysTech:feat/baton-work-verb-framework-graduation

feat(framework): graduate work_verb/design_provenance to first-class fields (fw-4.31.0 / cli-3.30.0, #332)

Author: montfort

CHANGELOG.md

@@ -7,6 +7,37 @@ and this project uses [independent versioning](README.md#versioning) for Framewo
 
 ---
 
+## Framework 4.31.0 / CLI 3.30.0 — 2026-06-28
+
+Graduate the Baton experiment's declared work-classification fields to the
+framework (#332 step 2). After the schema was ratified
+(`experiment-baton/06-work-verb-schema-ratification.md`), `work_verb` and
+`design_provenance` become optional, additive, first-class Charter / follow-up
+fields — declarable at authoring (cost ≈ 0) and surfaced by the validator as an
+advisory nudge. No existing document changes shape; the 100%-undeclared legacy
+corpus stays quiet.
+
+### Added (Framework)
+
+- **`work_verb` and `design_provenance` Charter frontmatter fields** (#332).
+  Added to `charter.schema.v0.json` as optional `string` properties (documented
+  vocabulary, intentionally **not** an `enum` so an out-of-vocabulary value is an
+  advisory warning, never a blocking schema error) and to the Charter template
+  (EN/es/zh-CN) as commented guidance. `work_verb`: design | implement | audit |
+  operate. `design_provenance`: new | upstream (only meaningful for implement —
+  upstream degrades the routing tier to operator).
+- **Follow-up entry schema gains `Work verb` / `Design provenance` lines**
+  (`FOLLOW-UPS-BACKLOG-PATTERN.md`, EN/es/zh-CN). Optional; documents the same
+  controlled vocabulary at the follow-up grain.
+
+### Added (CLI)
+
+- **`straymark validate` advisory for declared classification** (#332). New
+  warning-only rules `CHARTER-WORK-VERB` and `CHARTER-DESIGN-PROVENANCE` fire
+  only when a Charter declares the field with a value outside the controlled
+  vocabulary. An absent field emits nothing (anti-noise for legacy corpora); the
+  check never affects the exit code.
+
 ## Framework 4.30.0 / CLI 3.29.0 / Core 0.9.0 — 2026-06-20
 
 Adopter-feedback consolidation: four validator gaps from a 150-doc housekeeping

Cargo.lock

@@ -277,8 +277,8 @@ StrayMark uses independent version tags for each component:
 
 | Component | Tag prefix | Example | Includes |
 | --- | --- | --- | --- |
-| Framework | `fw-` | `fw-4.30.0` | Templates (12 types), governance, directives, Charter template + schema |
-| CLI | `cli-` | `cli-3.29.0` | The `straymark` binary |
+| Framework | `fw-` | `fw-4.31.0` | Templates (12 types), governance, directives, Charter template + schema |
+| CLI | `cli-` | `cli-3.30.0` | The `straymark` binary |
 | Loom (EXPERIMENTAL) | `loom-` | `loom-0.4.2` | The `straymark-loom` visualization server, downloaded on demand by `straymark loom serve` |
 
 Check installed versions with `straymark status` or `straymark about`.

README.md

@@ -1,6 +1,6 @@
 [package]
 name = "straymark-cli"
-version = "3.29.0"
+version = "3.30.0"
 edition = "2021"
 description = "CLI for StrayMark — the cognitive discipline your AI-assisted projects need"
 license = "MIT"

cli/Cargo.toml

@@ -170,6 +170,13 @@ pub fn validate_charters(project_root: &Path, straymark_dir: &Path) -> (Validati
             }
         }
 
+        // Step 2b: work_verb / design_provenance advisory (Baton #332 graduation).
+        // Declared classification fields. ADVISORY ONLY: a *present* value outside
+        // the controlled vocabulary is a warning (never an error / exit-1, per the
+        // schema-ratification posture §5); an *absent* field emits nothing — the
+        // 100%-undeclared legacy corpus must stay quiet.
+        check_charter_work_verb(&raw_yaml, path, &mut result);
+
         // Step 3: typed parse for referential-integrity checks. If schema
         // validation already caught problems, the typed parse may also fail —
         // in that case we skip ref checks (cannot trust the structure) but
@@ -274,6 +281,54 @@ pub fn validate_charters(project_root: &Path, straymark_dir: &Path) -> (Validati
     (result, charter_count)
 }
 
+/// Advisory check for the declared classification fields `work_verb` /
+/// `design_provenance` (Baton #332, schema ratification `06-work-verb-schema-
+/// ratification.md`). Reads the raw frontmatter (the fields are intentionally
+/// absent from the typed `CharterFrontmatter` — they are optional and additive).
+///
+/// Anti-noise by design: a value *present but outside* the controlled vocabulary
+/// is a Warning; an *absent* field emits nothing. The vocabulary is enforced here
+/// (CLI semantics) rather than via a schema `enum` (which would make it a blocking
+/// Error), keeping the posture advisory per the ratification §5.
+fn check_charter_work_verb(raw_yaml: &serde_yaml::Value, path: &Path, result: &mut ValidationResult) {
+    const WORK_VERBS: &[&str] = &["design", "implement", "audit", "operate"];
+    const PROVENANCES: &[&str] = &["new", "upstream"];
+
+    let Some(map) = raw_yaml.as_mapping() else {
+        return;
+    };
+
+    for (key, valid, rule) in [
+        ("work_verb", WORK_VERBS, "CHARTER-WORK-VERB"),
+        ("design_provenance", PROVENANCES, "CHARTER-DESIGN-PROVENANCE"),
+    ] {
+        // Absent field → nothing (anti-noise). Only a *present* value is checked.
+        let Some(value) = map.get(serde_yaml::Value::String(key.to_string())) else {
+            continue;
+        };
+        let Some(declared) = value.as_str() else {
+            continue;
+        };
+        if valid.contains(&declared.trim()) {
+            continue;
+        }
+        result.add(ValidationIssue {
+            file: path.to_path_buf(),
+            rule: rule.to_string(),
+            message: format!(
+                "`{key}: {declared}` is outside the controlled vocabulary (expected one of: {}).",
+                valid.join(", ")
+            ),
+            severity: Severity::Warning,
+            fix_hint: Some(format!(
+                "Declare `{key}` as one of: {}. Leave it unset if undeclared — \
+                 the field is optional and only a wrong value is flagged.",
+                valid.join(", ")
+            )),
+        });
+    }
+}
+
 /// True if an AILOG file matching the given ID exists under
 /// `.straymark/07-ai-audit/agent-logs/`. The match is by filename prefix:
 /// `AILOG-2026-04-28-021` matches `AILOG-2026-04-28-021-anything.md` but not

cli/src/validation.rs

@@ -855,3 +855,84 @@ fn test_charter_files_exist_detects_spanish_heading() {
         .stdout(predicate::str::contains("CHARTER-FILES-EXIST"))
         .stdout(predicate::str::contains("src/no-existe.rs"));
 }
+
+// --- CHARTER-WORK-VERB / CHARTER-DESIGN-PROVENANCE (Baton #332 graduation) ---
+
+/// Write a minimal Charter whose frontmatter carries the given extra YAML lines
+/// (e.g. `work_verb: implement`). Used to exercise the declared-classification
+/// advisory.
+fn create_charter_with_frontmatter(dir: &std::path::Path, extra_frontmatter: &str) {
+    let charters = dir.join(".straymark").join("charters");
+    std::fs::create_dir_all(&charters).unwrap();
+    let content = format!(
+        "---\ncharter_id: CHARTER-01\nstatus: declared\neffort_estimate: M\ntrigger: \"test trigger\"\n{}---\n\n# Charter: Work Verb Test\n\n## Tasks\n\n1. Run.\n",
+        extra_frontmatter
+    );
+    std::fs::write(charters.join("01-work-verb.md"), content).unwrap();
+}
+
+#[test]
+fn test_charter_work_verb_invalid_value_warns() {
+    let dir = TempDir::new().unwrap();
+    setup_straymark(dir.path());
+    create_charter_with_frontmatter(dir.path(), "work_verb: refactor\n");
+
+    let mut cmd = cargo_bin_cmd!("straymark");
+    cmd.arg("validate")
+        .arg(dir.path().to_str().unwrap())
+        .arg("--include-charters")
+        .assert()
+        .success() // advisory: must NOT fail the exit code
+        .stdout(predicate::str::contains("CHARTER-WORK-VERB"));
+}
+
+#[test]
+fn test_charter_work_verb_valid_value_is_quiet() {
+    let dir = TempDir::new().unwrap();
+    setup_straymark(dir.path());
+    create_charter_with_frontmatter(dir.path(), "work_verb: implement\ndesign_provenance: upstream\n");
+
+    let mut cmd = cargo_bin_cmd!("straymark");
+    cmd.arg("validate")
+        .arg(dir.path().to_str().unwrap())
+        .arg("--include-charters")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("CHARTER-WORK-VERB").not())
+        .stdout(predicate::str::contains("CHARTER-DESIGN-PROVENANCE").not());
+}
+
+#[test]
+fn test_charter_work_verb_absent_is_quiet() {
+    // Anti-noise: an undeclared field must emit nothing (the legacy corpus is
+    // 100% undeclared and must stay quiet).
+    let dir = TempDir::new().unwrap();
+    setup_straymark(dir.path());
+    create_charter_with_frontmatter(dir.path(), "");
+
+    let mut cmd = cargo_bin_cmd!("straymark");
+    cmd.arg("validate")
+        .arg(dir.path().to_str().unwrap())
+        .arg("--include-charters")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("CHARTER-WORK-VERB").not());
+}
+
+#[test]
+fn test_charter_design_provenance_invalid_value_warns() {
+    let dir = TempDir::new().unwrap();
+    setup_straymark(dir.path());
+    create_charter_with_frontmatter(
+        dir.path(),
+        "work_verb: implement\ndesign_provenance: inherited\n",
+    );
+
+    let mut cmd = cargo_bin_cmd!("straymark");
+    cmd.arg("validate")
+        .arg(dir.path().to_str().unwrap())
+        .arg("--include-charters")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("CHARTER-DESIGN-PROVENANCE"));
+}

cli/tests/validate_test.rs

@@ -412,4 +412,4 @@ When a project accumulates a high volume of AILOGs across multiple Charters and
 
 ---
 
-*StrayMark fw-4.30.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*

dist/.straymark/00-governance/AGENT-RULES.md

@@ -234,4 +234,4 @@ Use a Level 1 (Context) diagram to illustrate:
 
 ---
 
-*StrayMark fw-4.30.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*

dist/.straymark/00-governance/C4-DIAGRAM-GUIDE.md

@@ -319,4 +319,4 @@ See also [ADR-2025-01-20-001] for architectural context.
 
 ---
 
-*StrayMark fw-4.30.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*

dist/.straymark/00-governance/DOCUMENTATION-POLICY.md

@@ -107,6 +107,8 @@ Each entry inside a bucket follows this shape (v1 fields marked; all of them opt
 - **Origin-class**: ex-ante-planning | testing | telemetry | staging | real-env-bug   (v1, optional)
 - **Status**: open | in-progress | suspected-closed | closed | superseded | promoted
 - **Severity**: normal | blocking                                                     (v1, optional; default normal)
+- **Work verb**: design | implement | audit | operate                                 (optional; declared work-classification, Baton #332)
+- **Design provenance**: new | upstream                                               (optional; only for implement — upstream degrades to operator)
 - **Trigger**: ready | <calendar date> | when <X> | <other>
 - **Destination**: chore | mini-charter | charter-replanning | operations | <charter-id> | <TDE id>
 - **Cost**: <effort estimate>
@@ -314,4 +316,4 @@ Contributed via [issue #111](https://github.com/StrangeDaysTech/straymark/issues
 
 ---
 
-*StrayMark fw-4.30.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*