Instruction file imported from pkirsanov/research-lab (.github/instructions/terminal-discipline.instructions.md). Copyright stays with the author.

Terminal Discipline Policy (NON-NEGOTIABLE)

1. No Piping/Redirecting Output Into Files (ABSOLUTE)

FORBIDDEN: Using shell pipes or redirects to write files.

# ❌ FORBIDDEN
echo "content" > /path/to/file.txt
cat source.txt > dest.txt
command | tee output.log
command > output.txt 2>&1

REQUIRED: Use the dedicated file creation/editing tools provided by the IDE.

2. No Truncating Command Output (ABSOLUTE)

FORBIDDEN: Filtering, truncating, or limiting command output with pipes.

# ❌ FORBIDDEN
command | head -20
command | tail -50
command | grep "pattern" | head

REQUIRED: Always capture and display the FULL unfiltered output.

3. Build-Free Project Command Surface (ABSOLUTE)

Research Lab has no build step, service lifecycle, deploy CLI, or ./research-lab.sh. Do not invent one.

REQUIRED: Run product checks from the repository root using the exact Node commands declared by the repository or active spec. The baseline project check is:

node scripts/selftest.mjs

Scenario-specific validators and live checks use their exact committed script paths and arguments. Do not substitute a different command or silently reduce the requested category.

REQUIRED: Run Bubbles governance through the installed downstream CLI:

bash .github/bubbles/scripts/cli.sh doctor
bash .github/bubbles/scripts/cli.sh framework-write-guard
bash .github/bubbles/scripts/cli.sh repo-readiness .

Exception: Read-only inspection commands that don't build, test, or modify state are allowed:

• ls, cat, find, grep, wc for exploring the filesystem
• git log, git diff, git status for version control inspection
• docker ps, docker logs for observing running containers
• curl --max-time 5 for quick health checks (always with timeout)

5. Stateless Shell Sessions

Agent terminal invocations are independent shell sessions. State does NOT persist across calls:

• Environment variables set in one invocation are GONE in the next
• Working directory resets to repo root for each invocation
• Background jobs from a previous invocation cannot be referenced
• Shell history is not shared

Implication: every terminal command MUST be self-contained. Use absolute paths or cd && ... chains. Pass values as CLI arguments, not via env vars set in a prior call. If a script needs persistent state, write to a file (using IDE file tools, NOT shell redirection) and read it on the next invocation.

Exception: within a SINGLE persistent terminal session (the same run_in_terminal invocation with mode=async or interactive), the shell is stateful. But across DIFFERENT calls, treat each as fresh.

6. Empty Output Sentinel Convention

When a script/tool produces NO output to stdout, this MUST be unambiguous:

• Exit 0 + empty stdout → "no findings, all clean" (success case for a lint/grep)
• Exit non-zero + empty stdout → ERROR (likely crash or timeout — investigate)
• Exit 0 + at least one line of output → either info ("scanned N files") or findings (depending on tool semantics)

Scripts that intentionally print nothing on success SHOULD print a sentinel line [<tool-name>] OK — zero findings. RECOMMENDED for every new lint/guard.

Evidence collection: ALWAYS pair empty output with explicit $? capture. Example: bash <tool>; echo "exit=$?". Never record "no output" as the only evidence.

Summary Table

Violations of this policy are blocking issues.