Fix/release pipeline - #20
Merged
Merged
Conversation
The documentation led with skills and agents, which buried the feature that
carries the project's unique value. Restructure around three features, and
close the gap that made the primary one unadoptable.
Documentation, now a self-governing corpus:
Feature 1 DocGraph the ontology, its gates, the in-memory retrieval
graph, and the MCP server
Feature 2 ContextHygiene skill and agent-harness governance, plus the
shared instruction-surface scanner
Feature 3 CI Pipelines the diagnostic engine every gate reports through
Everything under docs/ now carries conformant frontmatter and passes
`docs validate` and `docs drift` with zero findings, via a .kyber-weave/
config that moves docs-root to docs/ and clears the inherited DevOps
exclusions. README becomes a router; install guidance is curl-only, and the
CI templates move off npm pinning to the install script.
Adoption path — previously absent:
`docs init` scaffolds host config, the catalog that supplies the component
and owner vocabularies, and the ontology reference. That last file closes a
real bug: every KW-DOC-SPEC-001 diagnostic told authors to read
<docs-root>/documentation-ontology.md, which the tool never produced.
It then deploys the kyber-weave-docs authoring skill through APM, defaulting
to the agent-skills target (.agents/skills/). APM is an expected dependency
and is never auto-installed; when absent, the corpus is still scaffolded and
the manual command is printed.
The skill is shipped as an APM package and governed by our own gates —
skill validate and scan clean, routing score 100/100.
Verified: 144 tests pass (+15), docs validate and docs drift clean, and a
scratch host repo initialises to a corpus that validates immediately.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Five AGENTS.md files, layered so each answers only what its directory makes true. Product knowledge stays in docs/ and is linked, never restated. / commands, non-negotiables, routing table src/KyberWeave.Core ports vs adapters, rule-id permanence, deps src/KyberWeave.Cli command+settings pairing, exit codes, stdout src/KyberWeave.Mcp stdout is JSON-RPC; log to stderr only tests/KyberWeave.Tests fakes vs the real sqlite fixture, fixtures Each has a paired CLAUDE.md that only points at its AGENTS.md, so the guidance has a single home. Root AGENTS.md directs agents to query the corpus through docs_explore rather than grepping docs/, which is the progressive-disclosure path: the routing table names where to go, and the corpus answers what things are. Nothing is placed under docs/ — files there are loaded by DocumentLoader and would need conformant frontmatter and compete in retrieval; docs/README.md already serves as the corpus index. Note recorded in the root file: `apm compile` generates AGENTS.md and CLAUDE.md at these exact paths and would overwrite them. This repository uses APM only for skill distribution via `apm install`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
apm compile writes AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md and a file per harness. That behaviour is APM's, but what aimed it at this repository was ours: apm.yml left `targets:` commented out, so APM auto-detected from the .github/ and .claude/ folders present and resolved to `all`. Pinning `targets: [agent-skills]` scopes compile to .agents/skills/, which produces no compile output, so the hand-authored AGENTS.md and CLAUDE.md files are safe. Verified with a real (non-dry-run) compile against a copy of this tree: both files byte-identical afterwards, no harness files generated. Consumers are unaffected — --target outranks apm.yml in APM's resolution chain, confirmed by installing with --target claude against a pinned manifest and seeing it deploy to .claude/skills/. `docs init` always passes --target explicitly. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Reading one redirected stream to the end and then the other deadlocks: an OS
pipe buffer is finite, so a child that fills the stream the parent is not yet
reading blocks on write, while the parent blocks on a read that can never
complete. `docs init` would hang instead of deploying or skipping the skill.
The same bug class was present in three places:
DocsInitCommand sequential ReadToEnd on both streams
CodeGraphResolver same, and it drains the whole node table, so stdout is
large by design and stderr sits unread behind it
CodeGraphFixtureDb worse — WaitForExit() with both pipes redirected and
neither drained
Centralised into Core/Processes/ProcessRunner, which starts both reads before
awaiting either, then waits for exit once both streams are at EOF.
ProcessRunnerTests covers a child writing 300 KB to each stream and the
asymmetric large-stdout case. The capture runs on a worker with a 30s bound so
a regression fails with a diagnostic rather than hanging CI forever — verified
by reintroducing the sequential reads, which times out exactly as intended.
The generator reads /dev/zero rather than piping `yes` into `head`; the latter
leaves `yes` writing to a closed pipe, and its "Broken pipe" message adds 25
stray stderr bytes per invocation.
Recorded in src/KyberWeave.Core/AGENTS.md — three independent occurrences is
enough to make it a stated convention.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Deployed into this tree by APM during development and picked up by a 'git add -A'. It is a general-purpose review skill, unrelated to this branch, and is generated output rather than repository source. Untracked with --cached so the working copy is left in place; track it deliberately elsewhere if that is wanted. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…values Two findings from review of this branch, both reproduced before fixing. Path containment (medium). --docs-root reached Path.Combine unchecked. Path.Combine returns its second argument outright when that argument is rooted, and '..' segments walk upward, so `docs init . --docs-root /tmp/pwned` wrote catalog.md and documentation-ontology.md outside the repository entirely. Verified by reproduction, not inspection. RequireContained canonicalises and refuses anything landing outside the root. It runs once up front against the resolved docs root and again per write. The up-front check is not redundant: the host config resolves inside the root, so a per-write-only check created it successfully and left it behind pointing at a docs root rejected a moment later. Rejection is now all-or-nothing. Value injection (low). owner and docs-root were interpolated raw into YAML frontmatter and into the pipe-delimited catalog row, so a newline added a key and a pipe shifted the columns the component and owner vocabularies are read from. RequireEmittableValue rejects control characters, '|' and '"'. Rejecting beats escaping here — two output formats would need two escapes, and silently rewriting what the operator typed is worse than stopping. DocsInitCommand catches ArgumentException so both surface as a red message and exit 1 rather than an unhandled crash. Nine tests cover relative escape, absolute escape, each injecting character, that nothing is written on rejection, and that ordinary values still work. Also ignores .agents/ and apm_modules/ — APM deploy targets holding generated output, including skills from unrelated packages. One such skill was swept into a commit on this branch by a `git add -A` and untracked in the previous commit; this stops it recurring. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…com/dpalfery/kyber-weave into feat/docs-restructure-and-docs-init
…cumentation and scaffolding logic
…on and code style consistency
…and Homebrew publishing status
Manual Run workflow now takes a SemVer input and creates the v* tag plus GitHub Release at that commit, so a dry-run checkbox alone is not a no-op. Co-authored-by: Cursor <cursoragent@cursor.com>
…o fix/release-pipeline
…issions feat: add GitHub Copilot configuration file
![kilo-code-bot[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
Code Review Roast 🔥Verdict: 4 Issues Found | Recommendation: Address before merge Overview
Issue Details (click to expand)
🏆 Best part: Removing the duplicate 💀 Worst part: The 31-line duplicate step cluster at 📊 Overall: Like a locksmith who locks himself out — the right tools, a confident attitude, and a door that still won't open cleanly.
Fix these issues in Kilo Cloud Files Reviewed (2 files)
Reviewed by kimi-k3 · Input: 132.4K · Output: 24.9K · Cached: 431.6K |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
dotnet build KyberWeave.sln -c Releasedotnet test tests/KyberWeave.Tests/KyberWeave.Tests.csproj -c ReleaseChecklist