examples/mcp: add a shared-state config for the anti-pattern 5 case

[drexthealpha]

docs/anti-patterns.md #5 — "Three loops append to one unstructured STATE.md → state rot, conflicting actions, ghost items." The recommended fix there is one state file per pattern. This adds an example for the other half of that case: when the loops are genuinely working the same surface and need one record rather than separate ones.

What's in the PR

• examples/mcp/knos.mcp.json — one server, three tools, stdio. No ports, no account, no model download.
• .knos/decisions.md — the record itself, seeded from this repo's own documented rules (each line cites the file it came from: anti-patterns.md, safe-write-pattern.md, examples/mcp/README.md). Plain markdown, it diffs, and a fresh clone reads it with nothing installed.
• Two lines in examples/mcp/README.md — one Quick Patterns row, one entry in Example Configurations, matching the existing format.

Why the record is in the repo rather than a database

It follows safe-write-pattern.md step 6, "record in state". The file is the whole interface — no server to run, no protocol to adopt. A loop that has no idea what Knos is still gets the context, because the file is already in the checkout.

Disclosure: I wrote Knos. I've kept this to the documented contribution path for a tool example and seeded the record from your docs rather than mine, so it's inspectable rather than promotional. If a third-party tool example isn't wanted here, close it — no hard feelings, and the anti-pattern write-up stands on its own either way.

🤖 Generated with Claude Code

[github-actions]

Thanks @drexthealpha for contributing a tool example — visible, reviewable PRs like this grow the reference for everyone.

What happens next

• Maintainer aims for same-day review on story, adopter, and scoped docs/example PRs (CONTRIBUTING.md).
• good first issue PRs: comment on the linked issue so we can assign and close on merge.

More ways to help

• Contributor quickstart + open issues
• Good first issue backlog

— loop-engineering maintainers

[github-actions]

This PR changes paths that must run the real validate and audit workflows (tools, patterns, scripts, or CI).

Fork PRs from first-time contributors start with those workflows waiting for approval. A maintainer needs to open the Checks tab and click Approve and run workflows. Until that happens, branch protection will show the PR as blocked even after a review.

Content-only PRs (docs/, examples/, stories/, skills/, root markdown) skip this step — required checks are posted from this workflow instead.

— loop-engineering fork-pr-gate

[cobusgreyling]

Thanks for a scoped MCP cookbook entry — examples/mcp/knos.mcp.json plus the README table/config rows match the existing connector pattern.

Please keep the example inside examples/mcp/ and drop the repo-root .knos/ directory.

CONTRIBUTING requires live state to stay out of the tree (STATE.md examples use a .example suffix and live state is gitignored). Anti-pattern 5's fix is one pattern state file (or clearly separated sections), not a third-party working directory at the root of this reference repo. Every clone would then carry Knos's decision log as if it were this project's source of truth.

Suggested shape:

• Keep examples/mcp/knos.mcp.json (local python -m knos.mcp is fine).
• If a sample record is needed, put it next to the config, e.g. examples/mcp/knos-decisions.example.md, and point the README at that path.
• Do not add .knos/ at the repository root.

The rest of the cookbook row is useful once the record is relocated.

[cobusgreyling]

This file should not land at the repo root. It reads as live Knos state for this project ("Written by knos export. Commit this file.", claims footer, decisions copied from our docs).

Please delete .knos/ from the PR. If a sample record is needed to show the shared-state shape, add something like examples/mcp/knos-decisions.example.md next to knos.mcp.json so it stays a cookbook artifact rather than this repo's working state. CONTRIBUTING.md: live STATE files are gitignored and examples use a .example suffix.

[cobusgreyling]

Please describe the sample record as a file under examples/mcp/ (e.g. knos-decisions.example.md), not .knos/decisions.md in the repo root. The JSON config here is the right layer for the cookbook; the root-level Knos directory is not.

[drexthealpha]

Done — the repo-root .knos/ directory is gone. The PR is now three files, all under examples/mcp/:

• examples/mcp/knos.mcp.json
• examples/mcp/knos-decisions.example.md — the .example suffix per CONTRIBUTING, so no live state is in the tree
• examples/mcp/README.md — the table and config rows

You were right that a clone carrying Knos's decision log at the root would read as this project's source of truth. The example file shows the format instead.

Required checks are green (the paths are content-only now, so the gate posts them directly). Ready for another look whenever you have a minute.

[drexthealpha]

Closing this - it was the wrong approach. Sorry for the noise.

[drexthealpha]

Reopened - I closed this too broadly while clearing out a batch of my own low-quality PRs, and this one does not belong in that batch. It is an example file you asked for a change on, and that change was made. Sorry for the churn; leaving it with you.