v0.33.0

Prefixed task IDs, a gated command surface, and the end of operations that report success and do nothing

Knowns v0.33.0 is a minor release that gives every generated task ID a project prefix, gates docs and source against the real command tree, and closes a family of bugs where a call reported success while changing nothing.

That last theme is the one worth reading. task create over MCP accepted acceptance criteria and discarded them, checkAc skipped indexes the task did not have, and a task could therefore reach done against criteria that were never recorded, with every call along the way returning success. Doctor had the same shape from the other side: warnings that no remediation could clear, because a full reindex never wrote the file doctor reads. Silent success is worse than an error, so each of these now fails and names what went wrong.

Added

• Prefixed task IDs by default: A project that never configured defaultTaskIdPrefix used to mint bare six-character IDs, so a task file was anonymous once the title left its name. The prefix is derived from the project name (Knowns gives KN, My Cool Project gives MCP), with a fallback when a name yields nothing legal. An explicit --prefix and a configured default both still win. IDs already written without a prefix are untouched: an ID is an identity, and rewriting one breaks every @task- reference to it.
• reviewEvaluatedHash on decisions: reviewEvaluatedAt says when a review ran but not which text the reviewer saw, so two edits landing close together left a finding indistinguishable from a current one. The hash pins the content, each reviewMatch pins the decision it was compared against, and decision get and inbox report REVIEW_STALE so the field has a reader.
• Command surface gates: tools/gendocs renders docs/en/cli-reference from the cobra tree and make cli-docs-check fails CI once they diverge. TestCommandContract snapshots the whole surface including hidden commands. The lint reads doctor remediations and UI strings too, not just markdown: 1050 invocations across docs, Go and TypeScript.
• KNOWNS_EMBED_MOCK: A deterministic in-process embedder that derives each vector from a hash of the text, so CI can gate the semantic and hybrid paths with no network, no model and no daemon. It is distinct from the constant-vector stub in the unit tests, which gives every document the same direction and makes ranking a tie. This one keeps ranking well defined, which is what exercises the similarity threshold, the RRF constant and the candidate window. It gates behaviour, not retrieval quality.
• Skill retirement: The System Decision Impact checkpoint recorded supersession but never retired what the work replaced, so the repo accumulated specs that still read as current instructions. Fully superseded docs are now deleted in the same change; partially superseded ones are kept with their void parts named.

Changed

• Task files are named after the ID alone: The title used to be part of the file name, which put a copy of a mutable field into a path that is never rewritten, so a renamed task advertised its old title for the rest of its life. Both task-<id> - <slug>.md and task-<id>.md are still located and read, so nothing needs migrating. TaskFileMatches is exported because three hand-rolled copies of that rule had already drifted apart.
• knowns runtime memory: The command is grouped under the noun it belongs to. The old runtime-memory path stays runnable but hidden, because runtimeinstall baked that exact string into hook files already on users' machines. lifecycle.go records the retirement schedule, so a deprecated command cannot vanish without leaving a tombstone naming its replacement.
• MCP task actions validate their arguments: taskActionParams declares what each action accepts as the single source for both help text and validation, so an argument an action does not take is now an error naming it.

Fixed

• --plain and NO_COLOR are honoured everywhere: lipgloss v2 emits full ANSI and downsamples only at its writer, but the CLI prints through fmt.Print*, so the flags reached nothing on the write paths. SetPlainOutput swaps the package-level styles, covering roughly 640 render sites from one choke point. The help path honours the flags separately, because cobra serves --help without PersistentPreRun.
• MCP task create stores acceptance criteria instead of accepting and discarding them, and checkAc / uncheckAc reject out-of-range indexes and name the range.
• A full reindex clears what doctor reports: Watermarks were written only by per-entity reconciliation, so a stale warning could outlive knowns search index --wait indefinitely. A successful generation swap now stamps the entities it indexed, taking truth from the points it actually built and validated.
• A newer intent revives a dead-lettered job: A Qdrant outage long enough to exhaust the retry budget dead-lettered every pending reconcile job at once, and editing the entity afterwards refreshed everything except the DeadLetter flag the scheduler checks, so the entity was never indexed again.
• History validates with the writer's hash function: The reader hashed the file's bytes verbatim while the writer normalized through models.HistoryRecord, so a record carrying a nested change value such as acceptance criteria hashed differently on read and an intact history was reported as corrupt.
• Doctor honours settings.skillsScope and flags a project copy that shadows a global install, and sync stops materializing project skill directories unconditionally, which used to reinstate a project copy over ~/.claude/skills on every run.
• Workspace paths are stored in on-disk casing: On Windows and the default macOS filesystem two spellings of one folder became two workspace rows, which auto-scan made routine. A case-insensitive match is only accepted when os.SameFile proves both spellings name one directory, so genuinely distinct directories on a case-sensitive filesystem stay distinct. Existing duplicates collapse on read. Fixes #144.
• CanonicalPath resolves a component its parent never lists, so one directory no longer canonicalizes to two strings.
• The agents hint points at a command that exists: knowns agents told users to run knowns agents --sync, which has never been a flag. The command is sync --instructions.

Documentation

• ARCHITECTURE.md rewritten: It described a TypeScript project, and 15 of the 24 files it named do not exist in this repository.
• Broken examples in embedded skills fixed: validate --sdd in kn-verify is not a real flag (it is --scope sdd), and memory add --category and template run --name are likewise not real.

Upgrade

• New tasks get prefixed IDs and are written as task-<id>.md. Existing tasks and file names keep working unchanged; nothing is migrated. Any tooling that parses task file names or assumes a bare six-character ID should be checked.
• MCP clients that send a uniform argument envelope will now see errors where extra arguments were previously ignored. Send only the arguments the action declares.
• knowns runtime-memory still runs but is hidden. Move to knowns runtime memory.

---

Acknowledgements

Special thanks to @TheLandsharkLabs for reporting the Windows workspace duplication in #144, with a measured registry (11 rows for 6 real projects, five pairs differing only in the casing of one path segment) rather than a reproduction sketch. The report also flagged workspace auto-scan as a lead rather than a finding, and that lead turned out to be the reason the bug was routine instead of rare: the candidate list carries both capitalizations of every well-known project folder, and both stat successfully. The fix in this release canonicalizes at registration and collapses existing duplicates on read, which is close to the first and last of the three routes the report proposed.

Contributors

@howznguyen

Included pull request: #145

Full Changelog: v0.32.0...v0.33.0