Skip to content

Hide init/metrics behind the existing gate pattern, withdraw them from the user guide, correct doctor's checks - #24

Closed
simonkrol wants to merge 7 commits into
aws-solutions:mainfrom
simonkrol:github-pages-quick-start
Closed

simonkrol wants to merge 7 commits into
aws-solutions:mainfrom
simonkrol:github-pages-quick-start

Conversation

@simonkrol

@simonkrol simonkrol commented Sep 28, 2026 •

Copy link
Copy Markdown
Member

CLI:

  • Hid konductor init and konductor metrics from --help and gated them at dispatch behind KONDUCTOR_ALLOW_INIT=1/KONDUCTOR_ALLOW_METRICS=1 — matches the existing konductor config pattern exactly. Both are complete, tested commands withheld from the v1 customer-visible surface, not removed; metrics is additionally a genuine stub with no logic behind its gate.
  • Removed doctor's config check from the live checks vector (run_checks) — matches the existing check_gitignore dormant-check precedent. Traced every consumer of the resolved config values and confirmed none acts on them for a real decision; the check was validating decorative output. Function and its unit tests stay intact, just not wired into live dispatch. doctor now runs 8 checks instead of 9.
  • Fixed doctor's dormant config-load-failure remediation string (in check_config_with_home, a check that is unit-tested but never called from live dispatch): it described a backup/hand-edit/delete-to-fallback recovery workflow for config.yml — the same stale "active risk" framing already removed from the docs. Since nothing reads or writes this file through any live command today, there's nothing to remediate against; the string now says so plainly instead of describing a workflow that doesn't apply to anything a user can currently do.
  • Corrected cli.rs's --from doc comment, which claimed installing from a published release was unavailable — false since v1.0.0 shipped; now describes the real GitHub-release/main-dist fallback chain.
  • Fixed the no---from remote install path printing "skipped 0 SOP(s) (no runtime discovery path yet)" even when it had installed 19 real SOPs. Added a manifest-derived count so the message reports accurately on both the --from and no---from paths.
  • Separated install's SOP and skill counts: SOP-derived sop-<name>/SKILL.md conversions no longer count toward the skill total. Detection now looks for the <agent-sop name="..."> marker every conversion carries, rather than the sop- filename prefix alone, which had misclassified a hand-authored skill (skills/sop-state-management/) that happened to share the prefix.
  • Corrected cli/README.md's --all section, which still said "all six checks above" after the live check count had already moved to 8
  • Added the three update flags (--cli, --version <v>, --force) to reference.md's flag table — present since the v1.0.0 release but never documented there; tasks/update.md already covered them in full.
  • cli/README.md brought fully in line with all of the above: command list, status callout, check table, sample outputs, and "Current state" section.

Docs:

  • Restructured docs/user-guide/quick-start.md to lead with the curl-based quick install (fetches the published release) instead of framing source-building as the only path. Corrected a real misunderstanding baked into the prior draft — installing without --from never runs synth remotely, it fetches synth's already-built output.
  • Restructured docs/user-guide/tasks/update.md so the no---from content-update path (with --version, --force, doctor's new version-checks) leads, with --from demoted to a clearly labeled alternative for maintainers working from a local checkout.
  • Deleted docs/user-guide/tasks/initialize-a-project.md and removed every teaching reference to init/metrics from reference.md, concepts.md, glossary.md, faq.md — consistent with both being withdrawn from the documented command surface. Reworded every remediation step that used to recommend running init so it gives a manual alternative instead of a command that will now fail.
  • Corrected .konductor/config.yml's documentation in reference.md, notes.md, and tasks/update.md: it is not dead code — its load/validate logic is real and functional — but it is currently unreachable because config (the only command that reads or writes it) is hidden/gated the same way init/metrics are. Removed the "schema change might bite you" risk/recovery messaging entirely (back up your config, hand-edit it, re-scaffold it) since there is no live workflow where that risk currently applies; replaced with a flat statement that the file is not currently used.
  • Corrected faq.md's "Is any of my data sent anywhere?" section, which claimed the CLI "touches the network in one place only: install" and that "neither update nor doctor makes any release call" — both false. doctor fetches the latest release tag by default to check currency (skippable via --no-version-check); a no---from update fetches a release by design; update --cli additionally reaches the network for its self-replace step. synth remains the only command with zero network involvement, and is now stated as such specifically rather than folded into a blanket "everything else is local" claim.
  • Fixed all navigation left dangling by the initialize-a-project.md deletion (prev/next links, ToC entries, a mermaid diagram).
  • Corrected the doctor check-count documentation from nine to eight everywhere it's stated, and fixed a stale "no release has been published yet" claim in prerequisites.md.
  • Resynced both docs/index.html and docs/site/user-guide.html to match every markdown change above, via the deterministic htmlbundle.py/sync-html-content.py edit mechanism — confirmed byte-identical to each other throughout, and independently verified by decoding both and diffing against current markdown content (not just the automated checker's narrower fact-based checks).

Build tooling:

  • Fixed a real gap in check-guide-facts.py's own withdrawn-command leak detector: its pattern required a trailing space that a JSON-quoted string value never has, letting metrics leak into both live HTML bundles undetected. Fixed the boundary logic generally, not as a metrics-specific patch. Extended it further with a bare-word enumeration-leak check after finding a second leak of the same underlying shape.
  • Retired several stale entries in tools/build-user-guide/html_sop_edits.py/sync-html-content.py whose new text encoded facts later corrected elsewhere — each was silently reintroducing already-fixed content on every subsequent --apply. Root-caused and fixed at the source rather than patched again in the HTML.

Release:

  • Bumped cli/konductor-rs's Cargo.toml/Cargo.lock and the top-level VERSION file to 1.0.4, with a new [1.0.4] CHANGELOG.md entry. This branch was rebased onto main after PR fix(telemetry): scoped agent telemetry for Kiro v2/v3 and Claude #20 (fix/telemetry-kiro-v2-v3) — earlier expected not to merge — actually merged and landed as the real, published 1.0.3. That PR's own [1.0.3] CHANGELOG section (telemetry hook wiring, mcp/README.md drift) is left untouched above this entry; this release is 1.0.4, not a second claim on 1.0.3.

Fixes # (issue)

Type of Change

  • CLI (cli/) change — Rust or Python
  • Documentation

Testing

  • If cli/ changed: cd cli && make test passes (Rust + Python + conformance suites) — full suite green after the rebase onto PR fix(telemetry): scoped agent telemetry for Kiro v2/v3 and Claude #20's merged, substantially-rewritten cli.rs/dispatch.rs/doctor.rs/install.rs, confirming every fix's intent survived relocation into the new upstream code structure, not just that it compiled
  • Smoke tested affected agent(s): live-verified konductor --help, konductor init/metrics/config (gated, exit 64, "not currently available"), and each with its escape hatch set (real behavior confirmed — init wrote real files to a scratch target, metrics reached its stub)
  • Ran the benchmark harness for the affected agent(s) — not applicable, no agent behavior changed (CLI/docs only)
  • New or changed code files carry the required SPDX header

Checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own changes
  • I have commented my code where necessary
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added or updated tests that prove my change works — added gate/escape-hatch tests for init/metrics mirroring the existing config test pattern; added a regression test for the SOP/skill double-count exclusion (order-independent); added a serializing-lock guard to a test that raced its siblings over the same env var; updated one test whose assertion no longer held once config's doctor check was removed

Notes for Reviewers

  • The chore: release 1.0.4 commit (version bump + changelog) is intentionally separate from the substantive fix: commits and is expected to be squashed into the CR or folded into one of them at merge — it's release bookkeeping, not an independent change.
  • docs/user-guide/'s version strings are deliberately still pinned at 1.0.0, unrelated to this bump — a standing, documented decision (see notes.md), not an oversight.

@simonkrol
simonkrol force-pushed the github-pages-quick-start branch from 469b690 to 57e25f8 Compare September 29, 2026 14:12
@simonkrol
simonkrol changed the base branch from main to fix/telemetry-kiro-v2-v3 September 29, 2026 14:14
@simonkrol
simonkrol force-pushed the github-pages-quick-start branch from 57e25f8 to 69dd4a6 Compare September 29, 2026 14:37

@knihit knihit left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Posted comments for clarification.

Comment thread docs/site/USER_GUIDE_BUILD_NOTES.md Outdated
Comment thread tools/user-guide-sync/check-guide-facts.py Outdated
Comment thread skills/about-konductor/SKILL.md Outdated
Comment thread skills/about-konductor/SKILL.md Outdated
Comment thread skills/about-konductor/SKILL.md Outdated
Comment thread skills/about-konductor/SKILL.md Outdated
Comment thread cli/konductor-rs/src/cli/dispatch.rs
@simonkrol
simonkrol force-pushed the github-pages-quick-start branch 2 times, most recently from 6733fc4 to 560fdbe Compare September 30, 2026 18:47
@simonkrol
simonkrol changed the base branch from fix/telemetry-kiro-v2-v3 to main September 30, 2026 18:47
@simonkrol
simonkrol force-pushed the github-pages-quick-start branch 3 times, most recently from 71d563d to 9cec2d7 Compare September 30, 2026 21:40
- Updated cli.rs's doc comment on the `--from` flag: it no longer claims installing from a published release is unavailable, and instead describes the real fallback chain (GitHub Release, then main's dist/ tarball) documented in cli/README.md.
- Fixed install.rs's install summary on the no-`--from` remote path: it previously printed a false "skipped 0 SOP(s) (no runtime discovery path yet)" message even when SopInstallPhase had installed all 19 SOPs. Added a manifest-derived `sops` count (InstallCounts::sops / `sops_installed` in --json output) so the skip clause is now gated on `sops_skipped > 0`, leaving the --from path's existing skip wording untouched and reporting the real installed count on the no-`--from` path instead.
- Updated cli/README.md's "Current limitations" bullet to match install.rs's corrected behavior.
…bundles

Does not commit docs/site/USER_GUIDE_BUILD_NOTES.md: it is a per-run build
log (see tools/build-user-guide/README.md's "Where things live", which
describes it as generated output, not hand-authored content), and no prior
commit in this repo's history ever included one -- the durable, previously
committed build artifacts are .user-guide.manifest and user-guide.html.
Added to .gitignore so it does not recur.
Hides init and metrics behind #[command(hide = true)] plus dispatch
gating, matching the existing config pattern. Removes doctor's dormant
config check from the live checks vector, matching the check_gitignore
precedent. Fixes a stale remediation string in doctor.rs that
recommended two now-hidden commands. Updates cli/README.md's command
list, status blurb, check table, and Current-state section to match.
Bumps cli/konductor-rs's Cargo.toml/Cargo.lock (CLI binary version) and the
top-level VERSION file (content version) from 1.0.3 to 1.0.4, paired with
CHANGELOG.md's new [1.0.4] entry as required by validate-pr.yml's own
VERSION-alongside-CHANGELOG gate.

PR aws-solutions#20 (fix/telemetry-kiro-v2-v3), earlier expected not to merge, did merge
and landed as the real, published 1.0.3 on main -- its own [1.0.3]
CHANGELOG section (telemetry hook wiring, mcp/README.md drift) is real,
permanent history now and is left untouched above this entry. This
release's own version is 1.0.4, not a second claim on 1.0.3.

The substantive work this release covers is already recorded in full in
the "hide init/metrics, correct doctor's checks" and "withdraw init/metrics
from the user guide" commits earlier in this branch; this commit is pure
release bookkeeping layered on top of those.
Exclude SOP-derived sop-<name>/SKILL.md conversions from the
skill count and report SOPs as a single, always-accurate N SOP(s)
field/line instead of the prior 'skipped ... (no runtime discovery
path yet)' wording, which was stale on every path this codebase
now supports.

Disambiguate SOP-derived conversions from hand-authored skills that
happen to share the sop- filename prefix (e.g. skills/sop-state-management/)
by detecting the <agent-sop name="..."> marker every SOP-conversion body
carries, rather than relying on the sop- prefix alone, which produced a
false positive that miscounted sop-state-management as SOP-derived.
The "all six checks above" line in the --all section predates every
commit in this branch -- it was written at the 1.0.0 initial release
and never updated when the check count changed to 8 (cli_version and
content_version added outside run_checks(), telemetry_state renamed
from an earlier removed check). git blame confirms no later commit
touched these lines, so this is a standalone fix rather than a
correction folded into any prior commit's history.
@simonkrol
simonkrol force-pushed the github-pages-quick-start branch 2 times, most recently from bc695f1 to 6dc9652 Compare October 1, 2026 20:18
@simonkrol
simonkrol marked this pull request as ready for review October 1, 2026 20:19
The `update` flag table in reference.md's flag reference never gained
rows for --cli, --version <v>, and --force. All three trace to the
initial v1.0.0 release (git log -S confirms each flag's introduction
at 1f3f66c), predating every commit in this branch's range, and no
later commit in this history ever added the missing rows -- reference.md
has only ever been touched by 7223c96 (original authoring, outside this
branch's range) and 359f7cc (command-table/config-section wording,
leaving this flag table alone). tasks/update.md already documents all
three flags in full (see its '--version <v> and --force' section and
'Update the CLI itself' section); this brings the flag reference table
into sync with that existing, correct content.
@simonkrol
simonkrol force-pushed the github-pages-quick-start branch from 6dc9652 to 4e44696 Compare October 1, 2026 20:26
@simonkrol

simonkrol commented Oct 1, 2026 •

Copy link
Copy Markdown
Member Author

Closing in favor of #31 as fork PRs don't run CodeQL checks.

@simonkrol simonkrol closed this Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants