manual_slop/conductor/code_styleguides/feature_flags.md

Feature Flags (file presence vs config)

Status: Styleguide; codifies when to use file-presence flags ("delete to turn off") vs config flags ([ai_settings.toml] / [manual_slop.toml]). Date: 2026-06-12 Cross-refs: conductor/code_styleguides/knowledge_artifacts.md §5; conductor/code_styleguides/data_oriented_design.md.

What this is. Manual Slop has two patterns for "turning a feature on or off": (a) file presence (the file is the switch; rm to turn off); (b) config flag (the [ai_settings.toml] toggle or the GUI checkbox). They're both valid; each is right in different contexts. This styleguide codifies when to use which.

---

0. The two patterns (the one-glance table)

Pattern	How it works	How to turn off	How to turn on
File presence	The feature checks for the file's existence; the file is the switch	rm <file>	Touch the file (or run the generator that creates it)
Config flag	The feature checks a setting in [ai_settings.toml] / [manual_slop.toml]; the GUI checkbox is the surface	Set enabled = false in the config; or uncheck the GUI box	Set enabled = true; or check the GUI box
CLI flag (a sub-pattern of config)	The CLI accepts a flag like --no-cache; the default behavior is "on"	Pass --no-cache on the CLI	Omit the flag (use the default)
Feature flag in metadata (a sub-pattern)	A metadata.json field for the feature's track declares uses_rag: true	Edit the metadata	Edit the metadata

---

1. When to use file presence (the "delete to turn off" pattern)

Use file presence when:

• The feature generates a side artifact that the user might want to turn off by deleting the artifact
• The "off" state is recoverable — the artifact can be regenerated by running a command
• The user expects to be able to manage the feature via the filesystem (the user is on the command line; they know rm)
• The feature is opt-in by default-off (deleting the artifact means the feature is off; the absence of the file is the "off" state)

Examples in Manual Slop:

Feature	The "on" state	The "off" state	The regeneration command
Knowledge digest injection	~/.manual_slop/knowledge/digest.md exists	File is deleted	python -m src.knowledge_harvest --apply
Per-file knowledge for file X	~/.manual_slop/knowledge/files/{file_id}.md exists	File is deleted	(the next harvest regenerates)
Saved conversations index	~/.manual_slop/conversations/index-saved-conversations-*.json exists	File is deleted	(n/a; user manually saves)
RAG index for project	~/.manual_slop/.slop_cache/chroma_<provider>/ exists	Directory is deleted	python -m src.rag_engine --rebuild-index
Audit log	~/.manual_slop/logs/sessions/<session>/comms.log exists	File is deleted	(n/a; the log is auto-generated per turn)

The principle (per the data-oriented foundation): the data is the thing. If the feature produces a file, the file is the switch. Deleting the file is the natural way to turn off the feature.

The discovery surface: the user can ls ~/.manual_slop/knowledge/ and see digest.md (or not) and understand the state.

The ux surface: the GUI shows the file state and provides a [Delete to turn off] button that does the same rm underneath.

---

2. When to use config flags (the [ai_settings.toml] pattern)

Use config flags when:

• The feature is always on by default; the flag is a way to opt out in special circumstances
• The "off" state is not recoverable by a single command (it's a persistent preference)
• The user expects to manage the feature via the GUI (they're not on the command line)
• The feature's behavior is complex (multiple settings, not just on/off)
• The setting is user-specific (different users might have different preferences)

Examples in Manual Slop:

Feature	The config	The default	The GUI surface
RAG enabled	[ai_settings.toml] rag.enabled	false (new projects)	[X] Enable RAG checkbox
RAG source	[ai_settings.toml] rag.source	project	(project / global / none) radio
RAG embedding provider	[ai_settings.toml] rag.embedding_provider	gemini	dropdown
RAG chunk size	[ai_settings.toml] rag.chunk_size	1000	integer input
Auto-aggregate	[ai_settings.toml] aggregate.auto_aggregate	true	[X] Auto-aggregate files
Force full	[ai_settings.toml] aggregate.force_full	false	[ ] Force full content
Cache TTL (Anthropic)	[ai_settings.toml] cache.anthropic_ttl_seconds	300 (5 min)	integer input
Cache TTL (Gemini)	[ai_settings.toml] cache.gemini_ttl_seconds	3600 (1 h)	integer input
Knowledge harvest enabled	[ai_settings.toml] knowledge.harvest_enabled	true	[X] Enable knowledge harvest
Project context file	[manual_slop.toml] agent.context_files	(none)	file picker

The principle (per the data-oriented foundation): configuration is data. The GUI checkbox is a projection of the config file; the config file is the source of truth.

The discovery surface: the user can read [ai_settings.toml] and see the state. The TOML is human-readable.

The ux surface: the GUI has a settings panel that reads from the TOML, displays it, and writes back on change.

---

3. When to use a CLI flag (the sub-pattern)

Use CLI flags when:

• The feature is invoked from the command line (not from the GUI)
• The flag is a one-shot setting (the user doesn't want to edit a config file for a one-time run)
• The default is "on" and the flag is the "off" override

Examples in Manual Slop:

CLI	Flag	Default	Effect
python -m src.knowledge_harvest	--apply	off (dry-run)	Mutate: harvest + reclaim
python -m src.knowledge_harvest	--no-harvest	off (harvest)	Reclaim only; skip LLM
python -m src.knowledge_harvest	--max-harvest-bytes N	unlimited	Cap the conversation bytes sent to the LLM
python -m src.knowledge_harvest	--root PATH	~/.manual_slop	Use a custom knowledge root
pytest	--no-header	off	Don't print the header
pytest	-x	off	Stop on first failure

The principle (per the data-oriented foundation): the CLI flag is data. The user types a flag; the value is passed to the function; the function behaves accordingly.

---

4. When to use a feature flag in metadata.json (the track flag)

Use metadata feature flags when:

• A track's implementation depends on a feature (e.g., uses RAG); this is static metadata about the track
• The flag is documented in the track's metadata.json for reviewers
• The flag is not a runtime setting (it doesn't change behavior at runtime; it documents intent)

Examples in Manual Slop:

// In conductor/tracks/<track_id>/metadata.json
{
  "uses_rag": true,
  "uses_mma": false,
  "tier": "tier-2",
  "uses_knowledge_harvest": true
}

The principle: the metadata documents the track's dependencies. A reviewer can read the metadata to understand "this track uses RAG; if you don't have RAG enabled, the track might not work."

---

5. The decision tree (the 1-question test)

When adding a new feature, ask this single question:

Q: Is the feature's "off" state recoverable by a single command?
   │
   ├── yes (e.g., regenerate the artifact) ──► File presence
   │
   └── no (the "off" is a persistent preference)
        │
        ├── Q: Is the feature invoked from the CLI?
        │   │
        │   ├── yes ──► CLI flag (sub-pattern of config)
        │   │
        │   └── no ──► Config flag + GUI checkbox

The decision is the kind of flag, not the implementation. The file presence vs config choice is about user expectations, not technical constraints.

---

6. The interaction between file presence and config (the layered)

A feature can have both. Example:

• The knowledge digest is gated by file presence (digest.md exists) for the injection of the {knowledge} block.
• The knowledge harvest is gated by config ([ai_settings.knowledge] harvest_enabled = true) for the automatic regeneration of the digest after a discussion ends.

The two flags are layered:

• File presence controls whether the digest is injected (a per-turn decision)
• Config flag controls whether the digest is regenerated (a per-discussion decision)

The user can turn off the entire feature by both rm digest.md AND setting harvest_enabled = false. The feature is fully off.

The user can turn on a single layer by:

• touch digest.md to turn on injection (but the file is empty; the next harvest populates it)
• Setting harvest_enabled = true to turn on auto-regeneration

The GUI surface (per layer) is separate:

• The Knowledge panel shows the digest file state and provides [Delete to turn off] and [Regenerate] buttons
• The AI Settings > Knowledge panel has the harvest_enabled checkbox

The ux: the user has two knobs (file presence for "what's injected now"; config for "what gets regenerated"). Each is explicit about what it controls.

---

7. The forbidden patterns (the "don't do this" list)

Pattern	Why it's forbidden
File presence for a feature with no regeneration path	The user can't turn the feature back on without manual intervention
Config flag for a side artifact	The user can't rm the artifact to clean up disk
File presence and config flag for the same behavior	Confusing; the user doesn't know which to use
CLI flag that has no default ("off" by default)	The user has to remember the flag every time
GUI checkbox that doesn't write to the config file	The change is lost on restart
metadata.json flag that changes runtime behavior	The metadata is for documentation, not for behavior
Hidden file (in ~/.cache/ or /tmp/) as a flag	The user can't find it
Symlink-based flag	Platform-specific; debugging nightmare
Env var as the only flag	The user can't discover it via the GUI or the docs

---

8. The cross-references

• conductor/code_styleguides/knowledge_artifacts.md §5 — the knowledge digest "delete to turn off" example
• conductor/code_styleguides/data_oriented_design.md §1.2 — "Design around a model of the world" (the anti-pattern)
• conductor/code_styleguides/cache_friendly_context.md — the cache TTL GUI surface (a config flag + GUI checkbox)
• conductor/code_styleguides/rag_integration_discipline.md — the RAG opt-in (a config flag + GUI checkbox)
• src/paths.py — the path resolution; the file-presence flags live under ~/.manual_slop/
• docs/Readme.md (human-facing) — the high-level overview
• ./docs/AGENTS.md (agent-facing) — the per-tier reading path