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