Skip to main content

fallow_types/
task_matrix.rs

1//! Single source of truth for the agent-discoverability task-to-command matrix
2//! (R2/R3). One const slice drives every render surface: the `fallow schema`
3//! manifest (`task_matrix`), the `init --agents` AGENTS.md template, the
4//! `hooks install --target agent` managed block, the root `--help` cheat
5//! sheet, and the `fallow://task-matrix` MCP resource. The
6//! `scripts/generate-agent-docs.mjs` generator renders the same table into
7//! SKILL.md from the schema-serialized form, so the Markdown surfaces stay
8//! consistent without duplicating the rows.
9//!
10//! This module carries data only. The Markdown renderer and the clap probe
11//! drift test live in `crates/cli`, which owns the command tree; the MCP
12//! server projects the rows without `probe`.
13//!
14//! Read-only-evidence principle (R1): the matrix carries NO mutating commands
15//! (`fix`, `init`, `hooks`, `migrate`, `setup-hooks`, `watch`). Unit tests in
16//! this crate and in `crates/cli` pin that contract, mirroring the
17//! `next_steps[]` builder in the CLI report layer.
18
19/// One task-to-command row for the agent-discoverability cheat sheet (R2/R3).
20///
21/// `command` MAY contain `<placeholder>` or glob tokens because it renders
22/// into docs and help text, unlike the runnable-only `next_steps[]` contract.
23/// `probe` is the runnable clap token sequence (placeholders and values
24/// replaced with concrete dummies) that the CLI schema drift test parses
25/// through `Cli::try_parse_from`, so a row can never name a flag or subcommand
26/// that does not exist. A row whose command is a bare flag fragment (no
27/// leading subcommand) carries an empty `probe`; the drift test skips it and a
28/// dedicated test asserts the flags exist on the live global arg set instead.
29#[derive(Debug, Clone, Copy, PartialEq, Eq)]
30pub struct TaskRow {
31    /// The agent intent, phrased as "when the agent is about to ...".
32    pub task: &'static str,
33    /// The command to run, render-ready (may contain `<placeholder>` tokens).
34    pub command: &'static str,
35    /// Optional clarifying note appended in parentheses in the rendered table.
36    pub note: Option<&'static str>,
37    /// Runnable clap token sequence the CLI drift test parses, or empty for a
38    /// flag-fragment row that is covered by the global-flag existence test.
39    pub probe: &'static [&'static str],
40}
41
42/// The canonical task-to-command matrix. Verified against the live clap
43/// command tree; the CLI schema drift test re-checks every non-empty `probe`.
44pub const TASK_MATRIX: &[TaskRow] = &[
45    TaskRow {
46        task: "delete an \"unused\" export or file",
47        command: "fallow dead-code --trace <file>:<export>",
48        note: None,
49        probe: &["dead-code", "--trace", "src/index.ts:foo"],
50    },
51    TaskRow {
52        task: "prove a TypeScript symbol's exact consumers before refactoring",
53        command: "fallow dead-code --type-aware --symbol-impact <file>:<export-or-class.method>",
54        note: None,
55        probe: &[
56            "dead-code",
57            "--type-aware",
58            "--symbol-impact",
59            "src/index.ts:foo",
60        ],
61    },
62    TaskRow {
63        task: "find how one module reaches another",
64        command: "fallow trace --path <from> <to>",
65        note: Some(
66            "Reports `reachable: false` instead of failing when no import path exists; type-only hops are reported, not skipped.",
67        ),
68        probe: &["trace", "--path", "src/app.ts", "src/db.ts"],
69    },
70    TaskRow {
71        task: "delete an \"unused\" dependency",
72        command: "fallow dead-code --trace-dependency <name>",
73        note: None,
74        probe: &["dead-code", "--trace-dependency", "lodash"],
75    },
76    TaskRow {
77        task: "migrate a dependency",
78        command: "fallow trace --dependency <name> --sites",
79        note: Some(
80            "Counts each imported name, follows one hop through project wrappers, and counts each use that it cannot resolve.",
81        ),
82        probe: &["trace", "--dependency", "lodash", "--sites"],
83    },
84    TaskRow {
85        task: "commit or open a PR",
86        command: "fallow audit --base <ref>",
87        note: None,
88        probe: &["audit", "--base", "main"],
89    },
90    TaskRow {
91        task: "read a diff before approving it",
92        command: "fallow review --base <ref> --brief",
93        note: Some(
94            "orientation, never gates: deterministic and always exit 0, unlike the audit row",
95        ),
96        probe: &["review", "--base", "main", "--brief"],
97    },
98    TaskRow {
99        task: "prioritize refactoring",
100        command: "fallow health --hotspots --targets",
101        note: None,
102        probe: &["health", "--hotspots", "--targets"],
103    },
104    TaskRow {
105        task: "ask who owns code",
106        command: "fallow health --ownership",
107        note: None,
108        probe: &["health", "--ownership"],
109    },
110    TaskRow {
111        task: "check untested-but-reachable code",
112        command: "fallow health --coverage-gaps",
113        note: None,
114        probe: &["health", "--coverage-gaps"],
115    },
116    TaskRow {
117        task: "improve or check the tests of a change",
118        command: "fallow mutation --plan --base <ref>",
119        note: Some(
120            "The plan runs no code. Without `--plan`, the command runs the project tests against each mutant, so ask the user first.",
121        ),
122        probe: &["mutation", "--plan", "--base", "main"],
123    },
124    TaskRow {
125        task: "consolidate duplication",
126        command: "fallow dupes --trace dup:<fingerprint>",
127        note: None,
128        probe: &["dupes", "--trace", "dup:abc123"],
129    },
130    TaskRow {
131        task: "find feature flags",
132        command: "fallow flags",
133        note: None,
134        probe: &["flags"],
135    },
136    TaskRow {
137        task: "check which architecture rules apply to a file before changing it",
138        command: "fallow guard <files>",
139        note: None,
140        probe: &["guard", "src/index.ts"],
141    },
142    TaskRow {
143        task: "check import cycles, boundaries and policy rules after changing code",
144        command: "fallow architecture",
145        note: None,
146        probe: &["architecture"],
147    },
148    TaskRow {
149        task: "surface security candidates",
150        command: "fallow security",
151        note: None,
152        probe: &["security"],
153    },
154    TaskRow {
155        task: "understand a finding",
156        command: "fallow explain <issue-type>",
157        note: None,
158        probe: &["explain", "unused-export"],
159    },
160    TaskRow {
161        task: "scope a monorepo",
162        command: "--workspace <glob> / --changed-workspaces <ref>",
163        note: Some("global flags, prefix any command"),
164        // Flag-fragment row: no leading subcommand. Covered by
165        // `task_matrix_workspace_flags_are_global` in the CLI schema tests.
166        probe: &[],
167    },
168];
169
170impl TaskRow {
171    /// The `fallow schema` `task_matrix` row: `task`, `command`, and `note`
172    /// (`null` when absent, honoring the manifest's no-absent-key convention).
173    /// `probe` is a test-only concern and never serializes.
174    #[must_use]
175    pub fn to_json(&self) -> serde_json::Value {
176        serde_json::json!({
177            "task": self.task,
178            "command": self.command,
179            "note": self.note,
180        })
181    }
182}
183
184/// Mutating command tokens the matrix must never reference (R1 read-only
185/// principle). Shared with the CLI schema exclusion test.
186pub const MUTATING_COMMANDS: &[&str] = &[
187    "agent",
188    "fix",
189    "init",
190    "hooks",
191    "migrate",
192    "setup-hooks",
193    "watch",
194];
195
196#[cfg(test)]
197mod tests {
198    use super::*;
199
200    /// The first command token after the `fallow` prefix, or the empty string
201    /// for a bare flag-fragment row.
202    fn leading_command_token(row: &TaskRow) -> &'static str {
203        let after_fallow = row.command.strip_prefix("fallow ").unwrap_or(row.command);
204        after_fallow.split_whitespace().next().unwrap_or("")
205    }
206
207    #[test]
208    fn matrix_is_non_empty() {
209        assert!(!TASK_MATRIX.is_empty());
210    }
211
212    /// Read-only-evidence contract (R1): no row may name a mutating command.
213    #[test]
214    fn matrix_excludes_mutating_commands() {
215        for row in TASK_MATRIX {
216            let first_token = leading_command_token(row);
217            assert!(
218                !MUTATING_COMMANDS.contains(&first_token),
219                "task matrix row '{}' names mutating command '{first_token}'",
220                row.task
221            );
222        }
223    }
224
225    #[test]
226    fn to_json_omits_probe_and_keeps_note_key() {
227        let row = TaskRow {
228            task: "t",
229            command: "fallow flags",
230            note: None,
231            probe: &["flags"],
232        };
233        let value = row.to_json();
234        assert_eq!(value["task"], "t");
235        assert_eq!(value["command"], "fallow flags");
236        assert!(value["note"].is_null());
237        assert!(value.get("probe").is_none());
238    }
239
240    #[test]
241    fn tasks_are_unique() {
242        let mut tasks: Vec<&str> = TASK_MATRIX.iter().map(|row| row.task).collect();
243        let total = tasks.len();
244        tasks.sort_unstable();
245        tasks.dedup();
246        assert_eq!(tasks.len(), total, "duplicate task in TASK_MATRIX");
247    }
248
249    #[test]
250    fn leading_token_skips_the_fallow_prefix() {
251        let row = TaskRow {
252            task: "t",
253            command: "fallow audit --base main",
254            note: None,
255            probe: &[],
256        };
257        assert_eq!(leading_command_token(&row), "audit");
258        let fragment = TaskRow {
259            task: "t",
260            command: "--workspace <glob>",
261            note: None,
262            probe: &[],
263        };
264        assert_eq!(leading_command_token(&fragment), "--workspace");
265    }
266}