Update documentation with 40 changed files (#1025)

[rysweet]

Summary

Concise workflow-generated PR for documentation.

Issue

Closes #1025

Changed files

• docs/architecture/reflective-cognitive-threads.md
• docs/concepts/graceful-ooda-completion.md
• docs/concepts/salience-and-decide.md
• docs/howto/add-a-new-cognitive-thread.md
• docs/howto/configure-cognitive-thread-batch.md
• docs/howto/configure-graceful-ooda-completion.md
• docs/howto/configure-reflective-cognitive-threads.md
• docs/reference/cognitive-thread-scheduling.md
• docs/reference/cognitive-threads-catalog.md
• docs/reference/ooda-graceful-completion-api.md
• docs/reference/recipe-invoker-seam.md
• docs/reference/simard-cognition-salience-signal-cli.md
• mkdocs.yml
• prompt_assets/simard/recipes/analogy-map.yaml
• prompt_assets/simard/recipes/consolidate-sleep.yaml
• prompt_assets/simard/recipes/metacognition-appraise.yaml
• prompt_assets/simard/recipes/narrative-identity.yaml
• prompt_assets/simard/recipes/operator-model.yaml
• prompt_assets/simard/recipes/prospect-foresight.yaml
• prompt_assets/simard/recipes/reflect-postmortem.yaml
• prompt_assets/simard/recipes/salience-appraise.yaml
• prompt_assets/simard/recipes/values-deliberate.yaml
• src/cognitive_threads/mod.rs
• src/cognitive_threads/recipe_rail.rs
• src/cognitive_threads/salience_signal.rs
• src/cognitive_threads/schedule.rs
• src/cognitive_threads/tests.rs
• src/cognitive_threads/tests_catalog.rs
• src/cognitive_threads/tests_rework_contract.rs
• src/cognitive_threads/thread.rs
• src/cognitive_threads/threads/analogy.rs
• src/cognitive_threads/threads/consolidation.rs
• src/cognitive_threads/threads/engineer_log_analysis.rs
• src/cognitive_threads/threads/interoception.rs
• src/cognitive_threads/threads/maintenance.rs
• src/cognitive_threads/threads/metacognition.rs
• src/cognitive_threads/threads/mod.rs
• src/cognitive_threads/threads/narrative.rs
• src/cognitive_threads/threads/ooda.rs
• src/cognitive_threads/threads/operator_model.rs

Diff stat

 src/cognitive_threads/threads/interoception.rs     |  293 -----
 src/cognitive_threads/threads/maintenance.rs       |    4 +-
 src/cognitive_threads/threads/metacognition.rs     |  179 ----
 src/cognitive_threads/threads/mod.rs               |   78 --
 src/cognitive_threads/threads/narrative.rs         |  178 ----
 src/cognitive_threads/threads/ooda.rs              |    2 +-
 src/cognitive_threads/threads/operator_model.rs    |  179 ----
 src/cognitive_threads/threads/prospection.rs       |  186 ----
 src/cognitive_threads/threads/reflection.rs        |  198 ----
 src/cognitive_threads/threads/salience.rs          |  187 ----
 .../threads/values_deliberation.rs                 |  202 ----
 src/ooda_loop/completion.rs                        |  487 +++++++++
 src/ooda_loop/cycle.rs                             |   29 -
 src/ooda_loop/mod.rs                               |    6 +
 src/operator_cli/cognition.rs                      |  209 ----
 src/operator_cli/mod.rs                            |    2 -
 src/operator_commands_ooda/daemon/mod.rs           |  333 ++++--
 tests/install_real.rs                              |  124 ---
 tests/issue_1025_graceful_achieved_completion.rs   |  139 +++
 52 files changed, 1373 insertions(+), 7361 deletions(-)

Behavior

Implemented behavior through these branch commits:
7496332 chore(docs): drop misplaced P1018 manifest-pin docs from #1025 branch
ca89eb6 refactor(ooda): trim dead completion re-exports + correct #1025 reference doc
c4d81bb wip: checkpoint after implementation (steps 7-8)
fe456c3 fix(ooda): graceful ACHIEVED completion + bounded reflection safeguard (#1025)

Validation

ℹ NODE_OPTIONS=--max-old-space-size=32768 (saved preference). To change: /home/azureuser/.amplihack/config
I'll start by inspecting the branch and the actual changes to test.

● Get branch, diff stat, and status (shell)
│ cd /home/azureuser/src/Simard-deploy-4049/worktrees/feat/issue-1025-nodeoptions-max-old-space-si
│ ze32768-saved-preferen && git branch --show-current && echo "---DIFF STAT---" && git --no-pager
│ diff --stat HEAD~1 2>/dev/null | tail -30 && echo "---STATUS---" && git status --short
└ 7 lines…

● Show log and diff against merge base (shell)
│ cd /home/azureuser/src/Simard-deploy-4049/worktrees/feat/issue-1025-nodeoptions-max-old-space-si
│ ze32768-saved-preferen && echo "---LOG---" && git --no-pager log --oneline -10 && echo "---MERGE

Risk

No high-risk subsystem pattern detected from changed paths.

Checklist

• Branch has 4 commit(s) ahead of main
• Code review completed
• Philosophy check passed

---

This PR was created as a draft for review before merging.

---

Step 16b: Outside-In Testing Results

Detected toolchains: Rust CLI (Cargo.toml at root, cargo 1.95.0 / rustc 1.95.0); Node wrapper (package.json + bin.js) is a thin launcher only. Changed surface is entirely Rust (src/ooda_loop/completion.rs, src/ooda_loop/mod.rs, src/operator_commands_ooda/daemon/mod.rs) plus docs.

Chosen strategy: Per the qa-team skill's repo-type detection, Rust CLI repos use native cargo test for outside-in validation. Exercised the pure decision contract at the crate's public consumer boundary (simard::ooda_loop::completion) that the daemon consumes, plus the daemon-side glue that wires it into run_ooda_daemon.

Scenario	Command	Result	Key output
Simple — public API terminal/running/bound contract	cargo test --test issue_1025_graceful_achieved_completion	✅ PASS	7 passed; 0 failed — green PR ⇒ GracefulComplete; criteria unmet ⇒ Continue; stuck non-perpetual ⇒ BoundExceeded; perpetual exempt
Edge — completion decision unit tests	cargo test --lib ooda_loop::completion	✅ PASS	22 passed; 0 failed — precedence of achievement over bound, env parsing/degradation, goals_all_achieved
Integration — daemon glue (consumer of the decision layer)	cargo test --lib operator_commands_ooda::daemon	✅ PASS	73 passed; 0 failed — idle_stop_requires_opt_in_and_drained_board, reflection_bound_yields_stuck_non_perpetual_goal, reflection_bound_exempts_perpetual_and_terminal_goals, reflection_bound_leaves_moving_goal_alone

Fix count: 0 code fixes required. One transient object-write error (No such file or directory writing an incremental .rcgu.o) surfaced during the daemon compile — root cause was the build volume at 92% capacity, not a code defect. A clean re-run of the identical command passed 73/73.

Verdict: The graceful ACHIEVED completion + bounded reflection safeguard behaves correctly at the outside-in consumer boundary: a gate-verified goal (green PR) terminates the loop instead of re-reflecting indefinitely (#1025), while perpetual/standing goals remain exempt and the safeguard is opt-in by default (non-breaking).

[rysweet]

Step 17b — Comprehensive Code Review (PR #4745, issue #1025)

Reviewed the real diff (8 files, +1325): pure completion decision layer + daemon glue + docs + integration tests. Local cargo build --release and the #1025 test suites pass (22 unit + 7 integration + daemon glue units). Below are the findings.

✅ Strengths

• Pure, side-effect-free decision layer (src/ooda_loop/completion.rs): introduces no new evidence source, never lets a model self-report "done", derives completion solely from the existing gate CompletionVerdict. Good separation from I/O.
• Perpetual-safe, opt-in defaults: max_reflection_cycles = 0 (bound disabled) and stop_when_idle = false. With env unset, behavior is unchanged — non-breaking, PRD preserved.
• Correct precedence: achievement is checked before the bound (evaluate), so a goal that becomes gate-verified on the same cycle it would trip the cap completes gracefully instead of yielding BoundExceeded. Covered by evaluate_achievement_takes_precedence_over_bound.
• Robust env parsing: malformed/blank values degrade to defaults with tracing::warn!, no panics/unwraps in new code.
• No new print!/println!: new code uses daemon_log + structured tracing. Complies with the output constraint.
• Strong test coverage of the truth tables, bound predicate, perpetual/terminal exemptions, and daemon glue (reflection_bound_yields, should_graceful_idle_stop).
• References and closes feat(ws-2): subagent tmux tracking with dashboard attach links (#1015) #1025.

🔴 Blockers to "merge-ready" (CI green + mergeable)

1. Merge conflict — PR is CONFLICTING / mergeStateStatus: DIRTY. main has advanced (issue identity-and-bootstrap-refactor #5 "reflective cognitive threads") and now conflicts with this branch in:

   • src/operator_commands_ooda/daemon/mod.rs (both sides edited the daemon registration/loop region)
   • mkdocs.yml (both sides added nav entries)

   This must be rebased onto / merged with current main and the conflicts resolved before it can land. The daemon conflict is the higher-risk one — please re-verify the feat(ws-2): subagent tmux tracking with dashboard attach links (#1015) #1025 loop hooks still sit correctly relative to the new thread-registration block after resolving.

2. PR is still a draft. Mark "Ready for review" once conflicts are resolved.

3. pre-commit check is pending (not yet green). Required check must pass.

🟡 Non-blocking suggestions

4. Inaccurate PR title. "Update documentation with 40 changed files" — the real change is an 8-file code feature (graceful OODA completion + bounded reflection), not a 40-file docs update. The auto-generated title/body diff-stat (52 files / -7361) does not match the actual PR (8 files / +1325, 0 deletions). Please correct the title/body so reviewers and history reflect reality.
5. Two parallel completion decision paths. Production run_ooda_daemon consumes ReflectionBounds::bound_exhausted (via reflection_bound_yields) and should_graceful_idle_stop directly; the public evaluate() / goals_all_achieved() / LoopDecision are exercised only by tests, not called by the daemon. The bound arm is guarded against drift by bound_exhausted_matches_evaluate_bound_arm, but the idle-stop path (should_graceful_idle_stop vs goals_all_achieved) has no equivalent cross-check. Either wire evaluate/goals_all_achieved into the daemon as the single source of truth, or add a guard test asserting should_graceful_idle_stop agrees with goals_all_achieved, and document in the module header that completion.rs is the contract spec the daemon mirrors.

Checklist

• Code quality and standards — good; idiomatic, well-documented
• Test coverage adequate — yes for the pure layer + glue
• No TODOs, stubs, or swallowed exceptions — none in new code
• No unimplemented functions — none
• Logic correctness — decision precedence and exemptions correct
• Edge-case handling — empty board, missing verdict, malformed env, at/above cap all covered
• Mergeable / CI green — NO: merge conflicts + draft + pending pre-commit (see blockers)

Verdict: Implementation quality is solid and the design is sound, but the PR is not merge-ready: it conflicts with current main, is a draft, and has a pending required check. Resolve the conflicts (re-verify the daemon loop integration), push, mark ready, and confirm all checks green.

[rysweet]

Step 17c — Security Review (PR #4745, issue #1025)

Scope: 8-file diff (+1325/-0) — a pure OODA graceful-completion decision layer (src/ooda_loop/completion.rs), daemon glue (src/operator_commands_ooda/daemon/mod.rs), module wiring, docs, and integration tests. Reviewed the real diff plus full source of the new/changed Rust files.

Checklist

• Security requirements met — no new attack surface introduced
• No new vulnerabilities identified
• Sensitive-data handling — no secrets/tokens/credentials touched or logged
• AuthN/AuthZ — N/A (no auth-adjacent code paths)
• Injection vectors — none (no shell, SQL, HTML, deserialization sinks)

Attack-surface analysis

External inputs: exactly two, both environment variables read in ReflectionBounds::from_env:

• SIMARD_OODA_MAX_REFLECTION_CYCLES → parsed as u32
• SIMARD_OODA_STOP_WHEN_ACHIEVED → parsed as bool

Both are trimmed and parsed with total functions. Malformed/empty/unset values degrade to safe perpetual defaults (0 / false) and emit a tracing::warn! — no panic, no unbounded allocation, no unwrap/expect on the untrusted value. The parse core (from_env_values) is side-effect-free and unit-tested. ✅

Sinks: all format! uses are tracing/log or a GoalProgress::Blocked status string, interpolating internal integers and internal goal IDs — not attacker-controlled data reaching a shell/SQL/exec sink. Structured logging uses fields (value = raw), so a malformed env value cannot inject a format directive. ✅

Absent risk classes (verified by scan):

• No unsafe blocks.
• No panic! / .unwrap() / .expect() / process::exit in the new decision or daemon code → no DoS-via-panic surface.
• No Command:: / spawn / subprocess execution.
• No filesystem writes, no network I/O, no serde/deserialization of untrusted input.
• No secrets, tokens, credentials, or Authorization material in code or the three new docs.

DoS / resource considerations

The feature is a bounding mechanism: it caps runaway no-progress reflection cycles (opt-in) and allows graceful idle-stop on an all-ACHIEVED board. Net effect is reduced resource-exhaustion risk vs. the prior uncapped loop. Defaults preserve existing perpetual behavior, so it is not a behavior/DoS regression for operators who don't opt in. ✅

Verdict

No security findings (P0/P1/P2). APPROVED on security grounds.

Note (carried from Step 17b, non-security): the PR is still DIRTY/draft with pre-commit pending — merge-blocking on process grounds, but nothing security-related. Security posture is clean and ready.

[rysweet]

Step 17d — Philosophy Guardian Review (PR #4745, issue #1025)

Assessed the completion decision layer against the project philosophy (ruthless simplicity, bricks & studs, zero-BS, no over-engineering, clean boundaries). Grounded in the actual 8-file diff.

Principle	Status	Evidence
Ruthless simplicity	✅ Pass	completion.rs is 487 lines of pure decision logic — no I/O, no async, no hidden state. Decisions expressed as small pure functions (goal_achieved, goals_all_achieved, bound_exhausted, evaluate) returning a plain LoopDecision enum.
Bricks & studs	✅ Pass	Clean brick: input = verdicts + bounds + streak; output = LoopDecision. The "stud" is the narrow public surface (ReflectionBounds, LoopDecision, 6 pub fns). Daemon consumes via that contract; the module has zero knowledge of daemon internals.
Zero-BS	✅ Pass	No unimplemented!/todo!/TODO/FIXME, no panic!, no .unwrap() in production paths, no print!/eprintln!. Env parsing degrades gracefully (from_env_values handles None/invalid). No swallowed exceptions.
No over-engineering	✅ Pass	Opt-in, perpetual-safe defaults; no speculative config, no premature abstraction. Bounds are a flat struct, not a strategy hierarchy.
Clean module boundaries	✅ Pass	Logic lives in ooda_loop/completion.rs, wired via ooda_loop/mod.rs; daemon integration isolated in daemon/mod.rs. Decision layer is unit-testable in isolation (22 unit tests) independent of the daemon.

Compliance verdict: ✅ PASS — philosophy-compliant

The implementation embodies ruthless simplicity and the brick/stud model well. It is a side-effect-free decision core with a narrow contract, fully regeneratable from its spec.

One philosophy-adjacent note (non-blocking, carried from Step 17b)

Two completion-decision entry points coexist: the daemon drives bound_exhausted + should_graceful_idle_stop, while the public evaluate/goals_all_achieved are exercised only by tests. This is a mild single-source-of-truth smell — two paths that must agree. The bound arm is drift-guarded; the idle-stop path is not. Prefer wiring evaluate in as the SoT (or add a cross-check) so the tested API and the production path cannot diverge. Not a blocker for merge, but worth closing to preserve the brick's integrity.

Note: merge-readiness blockers (merge conflict vs main, draft status, pending pre-commit) are tracked separately in the Step 17b review — orthogonal to philosophy compliance.

[rysweet]

Auto-closing this stale CONFLICTING auto-generated documentation draft: it can no longer merge cleanly and is superseded by the canonical open auto-doc PR #4826. Enforcing the single-open auto-doc PR invariant (goal_hygiene).