fix(framework+cli): fw-4.16.2 / cli-3.14.1 — straymark repair per-target restore (#159)

Issue #156 closure-comment follow-up. The CLI bug surfaced as: `straymark
repair` ignored a single missing injection target (e.g. a deleted AGENTS.md)
when STRAYMARK.md was still present. Both the download trigger and the inject
path were gated on STRAYMARK.md being absent. From this release both gates
are removed and `repair` mirrors `straymark update-framework`'s per-target
behavior for files declared under `dist-manifest.yml::injections:`.

CLI (cli-3.14.1):
- `check_needs_download()` now reads the local dist-manifest.yml and flags
  the download as needed if any declared injection target is missing.
- `restore_missing_files()` replaces the `if !straymark_md.exists()` gate
  with a per-target presence filter — each missing injection target loads
  its template from the ZIP and runs through `inject::inject_directive`.
  Targets already present are left untouched.
- 5 new unit tests in `repair.rs::tests` cover `check_needs_download`
  branches and the `missing_injections` filter behavior.

Framework (fw-4.16.2):
- STRAYMARK.md §Directive Injection Markers rewritten to describe the
  post-fix behavior: init, update-framework, AND repair all walk
  manifest.injections and create any missing target.
- Governance footers + version tables bumped.
- Fix asymmetry: EN CLI-REFERENCE CLI row had been at cli-3.13.2 since
  the fw-4.15.0 cycle — corrected.

All 530 tests pass.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: montfort

CHANGELOG.md

@@ -7,6 +7,29 @@ and this project uses [independent versioning](README.md#versioning) for Framewo
 
 ---
 
+## Framework 4.16.2 / CLI 3.14.1 — `straymark repair` per-target restore (Issue #156 follow-up)
+
+Fixes the underlying CLI bug surfaced in the [Issue #156 closure comment](https://github.com/StrangeDaysTech/straymark/issues/156#issuecomment-4465050814): `straymark repair` ignored a single missing injection target (e.g. a deleted `AGENTS.md`) when `STRAYMARK.md` was still present, because both the download trigger and the inject path were gated on `STRAYMARK.md` being absent. From this release, both gates are removed and `repair` mirrors `straymark update-framework`'s per-target behavior for the set of files declared under `dist-manifest.yml::injections:`.
+
+### Fixed (CLI)
+
+- **`straymark repair` per-target restore** (`cli/src/commands/repair.rs`) — two gating bugs removed:
+  - `check_needs_download()` now reads the local `dist-manifest.yml` and flags the download as needed if any declared injection target is missing. Before this change a deleted directive file (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.cursorrules`, `.cursor/rules/straymark.md`) was silently ignored because the function only looked at essential framework files.
+  - `restore_missing_files()` replaces the `if !straymark_md.exists()` gate around the inject loop with a per-target filter (`missing_injections`). Each declared injection target is now checked individually; only the missing ones load their template from the ZIP and run through `inject::inject_directive`. Targets already present are left untouched — `repair` does not overwrite an installed file.
+- **`cli/src/commands/repair.rs::tests`** — five new unit tests cover the helper-level behavior: `check_needs_download` returns true for a missing injection target / false when all are present / still true for missing essential files (regression for the prior behavior); `missing_injections` filter identifies per-target gaps and is empty when all targets are present. End-to-end coverage of the download + extract path remains out of scope for the unit suite (it requires a real release ZIP and network); the release workflow exercises that path on every tag.
+
+### Changed (Framework)
+
+- **`dist/STRAYMARK.md §Directive Injection Markers`** — the missing-target behavior bullet added in `fw-4.16.1` is rewritten to describe the post-`cli-3.14.1` behavior: `init`, `update-framework`, AND `repair` all walk `manifest.injections` and create any missing target file. A short historical note preserves the pre-fix behavior for adopters running older CLIs.
+- **Governance footers** bumped to `v4.16.2` across `QUICK-REFERENCE.md`, `AGENT-RULES.md`, `DOCUMENTATION-POLICY.md`, `C4-DIAGRAM-GUIDE.md` (EN + ES + zh-CN) and the `CHARTER-CHAIN-EVOLUTION.md` footer (3 languages).
+- **Version tables** in `README.md` + i18n and `CLI-REFERENCE.md` + i18n bumped to `fw-4.16.2` / `cli-3.14.1`. The EN `CLI-REFERENCE.md` CLI row had been left at `cli-3.13.2` since the `fw-4.15.0` cycle — corrected in this patch.
+
+### Adopter guidance
+
+`straymark update-cli` brings `cli-3.14.1` with the fix. `straymark update-framework` brings the docs sync. Adopters who had been working around the bug by manually re-creating a deleted `AGENTS.md` before running `repair` no longer need that step — `straymark repair` will restore any single missing injection target without requiring the rest of the install to be broken.
+
+---
+
 ## Framework 4.16.1 — docs polish (Issue #156 follow-up)
 
 Documentation-only patch addressing two non-blocking observations raised in the [Issue #156 closure comment](https://github.com/StrangeDaysTech/straymark/issues/156#issuecomment-4465050814) after the adopter pulled `fw-4.16.0` / `cli-3.14.0`. No CLI bump.

README.md

@@ -276,8 +276,8 @@ StrayMark uses independent version tags for each component:
 
 | Component | Tag prefix | Example | Includes |
 | --- | --- | --- | --- |
-| Framework | `fw-` | `fw-4.16.1` | Templates (12 types), governance, directives, Charter template + schema |
-| CLI | `cli-` | `cli-3.14.0` | The `straymark` binary |
+| Framework | `fw-` | `fw-4.16.2` | Templates (12 types), governance, directives, Charter template + schema |
+| CLI | `cli-` | `cli-3.14.1` | The `straymark` binary |
 
 Check installed versions with `straymark status` or `straymark about`.
 
@@ -309,7 +309,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.16.1)
+# and download the latest fw-* release (e.g., fw-4.16.2)
 
 # Extract and copy to your project
 unzip straymark-fw-*.zip -d your-project/

cli/Cargo.lock

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

cli/Cargo.toml

@@ -6,7 +6,7 @@ use std::path::{Path, PathBuf};
 use crate::config::Checksums;
 use crate::download;
 use crate::inject;
-use crate::manifest::DistManifest;
+use crate::manifest::{DistManifest, Injection};
 use crate::utils;
 
 /// Expected directories inside .straymark/ (same as init.rs)
@@ -184,6 +184,21 @@ fn check_needs_download(target: &Path) -> bool {
         }
     }
 
+    // Check injection targets declared in the local manifest (fw-4.16.2 / cli-3.14.1).
+    // Before this version, `repair` only triggered the framework download when one
+    // of the essential framework files was missing — a single deleted injection
+    // target (e.g. `AGENTS.md` while `STRAYMARK.md` remained intact) was a silent
+    // no-op. Walking `manifest.injections` here brings the download phase in line
+    // with the restore phase, which now checks each target individually.
+    let manifest_path = target.join(".straymark/dist-manifest.yml");
+    if let Ok(manifest) = DistManifest::load(&manifest_path) {
+        for injection in &manifest.injections {
+            if !target.join(&injection.target).exists() {
+                return true;
+            }
+        }
+    }
+
     false
 }
 
@@ -227,12 +242,26 @@ fn restore_missing_files(zip_path: &Path, target: &Path) -> Result<()> {
         restored += extract_missing_files(&mut archive, &prefix, pattern, target)?;
     }
 
-    // Restore injections if STRAYMARK.md or directive files are missing
-    let straymark_md = target.join("STRAYMARK.md");
-    if !straymark_md.exists() {
-        // Read templates for injection
+    // Restore each missing injection target individually (fw-4.16.2 / cli-3.14.1).
+    // Before this version, this block was gated on `!STRAYMARK.md.exists()` — which
+    // meant a single missing injection target (e.g. `AGENTS.md` while `STRAYMARK.md`
+    // remained intact) was silently skipped, contradicting the `straymark repair`
+    // promise to restore broken installations. The per-target presence check below
+    // brings repair in line with the documented intent and with what `straymark
+    // update-framework` already does for the same set of files.
+    let missing_injections: Vec<&Injection> = manifest
+        .injections
+        .iter()
+        .filter(|inj| !target.join(&inj.target).exists())
+        .collect();
+
+    if !missing_injections.is_empty() {
+        // Load only the templates we will actually re-inject.
         let mut templates: HashMap<String, String> = HashMap::new();
-        for injection in &manifest.injections {
+        for injection in &missing_injections {
+            if templates.contains_key(&injection.template) {
+                continue;
+            }
             let zip_entry_name = format!("{}{}", prefix, injection.template);
             for i in 0..archive.len() {
                 let mut entry = archive.by_index(i)?;
@@ -245,8 +274,8 @@ fn restore_missing_files(zip_path: &Path, target: &Path) -> Result<()> {
             }
         }
 
-        // Re-inject directives
-        for injection in &manifest.injections {
+        // Re-inject only the missing ones.
+        for injection in &missing_injections {
             let template_content = match templates.get(&injection.template) {
                 Some(content) => content,
                 None => continue,
@@ -378,3 +407,140 @@ fn walkdir(dir: PathBuf) -> Result<Vec<PathBuf>> {
     }
     Ok(files)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::manifest::Injection;
+    use tempfile::TempDir;
+
+    fn write_manifest(target: &Path, injection_targets: &[&str]) {
+        let manifest_path = target.join(".straymark/dist-manifest.yml");
+        std::fs::create_dir_all(manifest_path.parent().unwrap()).unwrap();
+        let injections_yaml: String = injection_targets
+            .iter()
+            .map(|t| {
+                format!(
+                    "  - target: {t}\n    template: dist-templates/directives/dummy.md\n"
+                )
+            })
+            .collect();
+        let body = format!(
+            "version: \"4.16.2\"\ndescription: \"test\"\nrepository: \"x\"\nfiles: []\ninjections:\n{injections_yaml}"
+        );
+        std::fs::write(&manifest_path, body).unwrap();
+    }
+
+    fn write_essential_framework_files(target: &Path) {
+        // Files `check_needs_download` requires to be present in order to NOT
+        // already short-circuit to true for other reasons (we want to isolate
+        // the "missing injection target" branch).
+        std::fs::create_dir_all(target.join(".straymark/templates")).unwrap();
+        std::fs::write(target.join(".straymark/templates/template.md"), "x").unwrap();
+        std::fs::create_dir_all(target.join(".straymark/00-governance")).unwrap();
+        std::fs::write(target.join(".straymark/00-governance/AGENT-RULES.md"), "x").unwrap();
+        std::fs::write(target.join(".straymark/config.yml"), "language: en\n").unwrap();
+        std::fs::write(target.join("STRAYMARK.md"), "# StrayMark\n").unwrap();
+    }
+
+    #[test]
+    fn check_needs_download_true_when_injection_target_missing() {
+        let dir = TempDir::new().unwrap();
+        write_essential_framework_files(dir.path());
+        write_manifest(dir.path(), &["AGENTS.md", "CLAUDE.md"]);
+        // Pre-create one target, leave the other missing.
+        std::fs::write(dir.path().join("AGENTS.md"), "existing\n").unwrap();
+
+        assert!(
+            check_needs_download(dir.path()),
+            "must trigger download when an injection target listed in the manifest is missing"
+        );
+    }
+
+    #[test]
+    fn check_needs_download_false_when_all_injection_targets_present() {
+        let dir = TempDir::new().unwrap();
+        write_essential_framework_files(dir.path());
+        write_manifest(dir.path(), &["AGENTS.md", "CLAUDE.md"]);
+        std::fs::write(dir.path().join("AGENTS.md"), "x").unwrap();
+        std::fs::write(dir.path().join("CLAUDE.md"), "x").unwrap();
+
+        assert!(
+            !check_needs_download(dir.path()),
+            "must NOT trigger download when nothing is missing"
+        );
+    }
+
+    #[test]
+    fn check_needs_download_true_when_essential_file_missing_independent_of_injections() {
+        // Regression: pre-fw-4.16.2 behavior must still hold for the essential-file path.
+        let dir = TempDir::new().unwrap();
+        write_essential_framework_files(dir.path());
+        write_manifest(dir.path(), &[]);
+        std::fs::remove_file(dir.path().join("STRAYMARK.md")).unwrap();
+
+        assert!(
+            check_needs_download(dir.path()),
+            "missing STRAYMARK.md must still trigger a download"
+        );
+    }
+
+    #[test]
+    fn missing_injections_filter_identifies_per_target_gaps() {
+        // Exercises the same filter expression used in `restore_missing_files`
+        // (and verifies it does not regress to the pre-fw-4.16.2 STRAYMARK.md gate).
+        let dir = TempDir::new().unwrap();
+        write_essential_framework_files(dir.path());
+        std::fs::write(dir.path().join("AGENTS.md"), "x").unwrap();
+        // CLAUDE.md intentionally missing.
+
+        let injections = vec![
+            Injection {
+                target: "AGENTS.md".to_string(),
+                template: "dist-templates/directives/AGENTS.md".to_string(),
+                embed: None,
+            },
+            Injection {
+                target: "CLAUDE.md".to_string(),
+                template: "dist-templates/directives/CLAUDE.md".to_string(),
+                embed: None,
+            },
+        ];
+
+        let missing: Vec<&Injection> = injections
+            .iter()
+            .filter(|inj| !dir.path().join(&inj.target).exists())
+            .collect();
+
+        assert_eq!(missing.len(), 1, "exactly one target should be flagged missing");
+        assert_eq!(missing[0].target, "CLAUDE.md");
+    }
+
+    #[test]
+    fn missing_injections_filter_is_empty_when_all_present() {
+        let dir = TempDir::new().unwrap();
+        write_essential_framework_files(dir.path());
+        std::fs::write(dir.path().join("AGENTS.md"), "x").unwrap();
+        std::fs::write(dir.path().join("CLAUDE.md"), "x").unwrap();
+
+        let injections = vec![
+            Injection {
+                target: "AGENTS.md".to_string(),
+                template: "x".to_string(),
+                embed: None,
+            },
+            Injection {
+                target: "CLAUDE.md".to_string(),
+                template: "x".to_string(),
+                embed: None,
+            },
+        ];
+
+        let missing: Vec<&Injection> = injections
+            .iter()
+            .filter(|inj| !dir.path().join(&inj.target).exists())
+            .collect();
+
+        assert!(missing.is_empty());
+    }
+}

cli/src/commands/repair.rs

@@ -379,4 +379,4 @@ When a project accumulates a high volume of AILOGs across multiple Charters and
 
 ---
 
-*StrayMark v4.16.1 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark v4.16.2 | [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 v4.16.1 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark v4.16.2 | [Strange Days Tech](https://strangedays.tech)*

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

@@ -193,4 +193,4 @@ This document is itself the output of the acceptance flow Sentinel walked throug
 
 ---
 
-*StrayMark fw-4.16.1 | [GitHub](https://github.com/StrangeDaysTech/straymark) | Issue [#156](https://github.com/StrangeDaysTech/straymark/issues/156)*
+*StrayMark fw-4.16.2 | [GitHub](https://github.com/StrangeDaysTech/straymark) | Issue [#156](https://github.com/StrangeDaysTech/straymark/issues/156)*

dist/.straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md

@@ -318,4 +318,4 @@ See also [ADR-2025-01-20-001] for architectural context.
 
 ---
 
-*StrayMark v4.16.1 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark v4.16.2 | [Strange Days Tech](https://strangedays.tech)*

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

@@ -241,4 +241,4 @@ Mark `review_required: true` when:
 
 ---
 
-*StrayMark v4.16.1 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark v4.16.2 | [Strange Days Tech](https://strangedays.tech)*