kano-git-master-skill

name	kano-git-master-skill
description	Native-first Git automation toolkit for multi-repository workspaces. Use the kog/kano-git CLI for repo discovery, plan-backed commit flows, repo hygiene, export, and release smoke validation.
version	0.0.1

Kano Git Master Skill

Version: 0.0.1 Status: Alpha Release

This skill is centered on the native kog / kano-git command surface. Shell scripts exist as launchers, build helpers, wrapper generators, compatibility assets, or smoke tests. Do not treat old root-shell workflow examples as current unless they are listed in this file or in docs/guides/current-command-surface.md.

Canonical Entry Points

Use the repo-local launcher first:

./scripts/kog --help
./scripts/kano-git --help

On Windows CMD or PowerShell, use:

scripts\kog.bat --help
scripts\kano-git.bat --help

The shorter kog name is preferred for interactive and agent workflows. The kano-git name is kept as the longer canonical product name.

Launcher Diagnostics

Normal KOG launches keep successful Pixi bootstrap messages, binary candidate probes, and native scoped timing logs quiet. Errors, warnings, build progress, and command results remain visible. Enable launcher and native diagnostics for one command with the existing debug contract:

KOG_DEBUG=1 ./scripts/kog --help

Truthful values are 1, true, yes, and on (case-insensitive). This also enables existing command-layer KOG debug output; do not set it in normal agent or machine-readable workflows unless diagnostic output is intended.

Native Build Rule

Use launcher-owned self build as the user-facing build entrypoint:

./scripts/kog self build
./scripts/kog self rebuild

The normal developer build may fetch C++ dependencies from GitHub through CMake FetchContent. This is expected for online developer and CI builds. If dependency fetching fails in an offline or DNS-restricted environment, treat it as an online build prerequisite failure, not as a launcher or shared-infra failure.

Shared build/test/report/bootstrap helpers live in src/cpp/shared/infra/scripts/. Use them only when debugging the build layer itself. Do not replace the launcher flow with ad-hoc direct CMake/Ninja command sequences unless a maintainer asks for it.

Codex app-server diagnostic/thread utilities live under src/shell/codex-appserver/. They are support scripts for local observer and session debugging, not primary Git Master workflows. Ark-owned runner/provider helpers such as codex-appserver-send.ps1 stay in Ark until KOA-TSK-0223 productionizes that path.

Bash Completion

./scripts/kog completion install bash
./scripts/kog completion uninstall bash

Current Command Surface

# Help / discovery
./scripts/kog --help
./scripts/kog status
./scripts/kog overview
./scripts/kog discover
./scripts/kog fetch
./scripts/kog log --remote-count 3

# Commit / plan flows
./scripts/kog plan new
./scripts/kog plan runbook commit
./scripts/kog ai bootstrap copilot --dry-run
./scripts/kog ai bootstrap copilot
./scripts/kog commit -m "chore: update workspace"
./scripts/kog commit --exact-path src/file.cpp -m "fix: update one file"
./scripts/kog commit-push -m "chore: update workspace"
./scripts/kog agent-queue status
./scripts/kog cpa

# Repo hygiene and export
./scripts/kog repo-hygiene check
./scripts/kog repo-hygiene fix
./scripts/kog export --help
./scripts/kog export --single
./scripts/kog export --subtree "/path/to/repo/Engine/Source/Programs/UnrealGameSync" --name UnrealGameSync --source head
./scripts/kog export --subtree Engine/Source/Programs/UnrealGameSync --source working-tree
./scripts/kog export upload doctor
./scripts/kog export upload --last
./scripts/kog export upload --last --target drive_sync --layout Kano/kog --copy-manifest --copy-sha256

Subtree standalone export notes:

• --subtree accepts absolute or relative paths and exports exactly one archive.
• Default behavior strips parent directories so archive root starts at subtree basename.
• Use --keep-subtree-path to preserve full repo-relative path in archive entries.
• --subtree rejects --single, --include-submodule-stubs, and --validate-release-archive.

Export upload notes:

• kog export upload uploads or copies an existing export archive after kog export.
• Configure targets in ~/.kano/kog_config.toml and repo .kano/kog_config.toml; precedence is user < repo < CLI.
• Supported live backends are local-sync-folder and rclone; gdrive-api is guidance-only and does not start OAuth.
• local-sync-folder points at an existing sync root such as /path/to/sync/root; layout is a safe relative path that KOG may create under that root.
• The archive is copied always. The original export manifest and .sha256 sidecar are copied only when copy_manifest / copy_sha256 are enabled by config or CLI flags.
• rclone uses an existing configured remote and never starts Google OAuth from KOG. Private Google Drive URLs are built only from a Drive file ID returned by rclone lsjson --stat -M; otherwise the upload manifest records URL_UNAVAILABLE.
• Uploads preserve private/default backend visibility. Public links require explicit CLI confirmation with --public-link --yes because rclone link may create or retrieve public sharing permissions.

Example upload config:

[export.upload]
default_target = "drive_sync"

[export.upload.targets.drive_sync]
type = "local-sync-folder"
path = "/path/to/sync/root"
layout = "Kano/kog"
copy_manifest = true
copy_sha256 = true
return_url = false

[export.upload.targets.gdrive]
type = "rclone"
remote = "kog-drive"
destination = "exports/kog"
layout = "ChatGPT_Export"
copy_manifest = true
copy_sha256 = true
return_url = true

Plan-Backed Commit Flow

Preferred deterministic flow:

./scripts/kog plan new
./scripts/kog plan runbook commit
./scripts/kog plan verify pre-apply
./scripts/kog cpa

Useful aliases:

Alias	Meaning
cp	commit-push
cpa	commit-push automation entrypoint

For behind/diverged log readability, configure remote preview defaults in layered kog_config.toml files:

[log]
remote_preview_count = 3

AI model selection keywords:

• auto: provider-native auto first, fallback to KOG auto when unsupported.
• provider-auto: force provider-native auto.
• kog-auto: force KOG change-count policy.
• provider-default: provider default model behavior.

Copilot bootstrap support in this release:

• Windows/WinGet: supported via kog ai bootstrap copilot.
• Linux/macOS: detection-only/manual setup (no automatic installer path). | pi | plan new | | pia | plan new --ai-auto | | pv | plan verify pre-apply |

Agent mode:

KANO_AGENT_MODE=1 ./scripts/kog cpa

In agent mode, the external agent owns semantic authoring decisions. kog owns deterministic plan bootstrap, freshness refresh, verification, execution, sync, and push.

Direct git commit, git push, merge, rebase, cherry-pick, or broad staging is not a normal agent-mode completion path. Use kog plan/commit-push/converge or an approved KOA commit_plan worker, and report the route as source integration evidence when source files changed.

Use a shared checkout for low-conflict exact-path or chunk-scoped changes. Open or keep a dedicated worktree for broad refactors, generated rewrites, long validation runs, known overlapping ownership, or changes that need isolated branch review.

Before multiple coding sessions mutate one shared repository, admit their intent through kog agent-queue admit. Preview agent-queue drain before activating a compatible batch with --confirm. KOG merges disjoint files, identical declared postconditions, and explicitly non-overlapping line chunks. Ambiguous same-file ownership fails closed and should be replanned or moved to a worktree.

Use kog commit --exact-path <file> -m <message> for the resulting narrow commit. Repeat --exact-path for every add, modification, deletion, or both old and new rename paths. This flow uses an isolated temporary index, preserves unrelated staged entries, rejects stale HEAD and existing index.lock, and never deletes another process's lock. An active queue batch requires the matching --queue-batch id. See docs/guides/agent-mutation-queue.md.

Repo Hygiene

Run before committing or exporting release archives:

./scripts/kog repo-hygiene check
./scripts/kog repo-hygiene check --archive-safe
./scripts/kog repo-hygiene fix

The hygiene command covers Git-index executable bits, LF normalization, and archive-safe file mode issues. This is especially important when changes were made on Windows but exported for Linux/macOS use.

Shell-only local quality gate:

src/shell/test/pre-commit-quality-gate.sh

Enable the tracked hook in this repository with:

git config core.hooksPath .githooks

repo-hygiene check --archive-safe also invokes the same pre-commit quality gate from the native command surface when the native binary is available.

Release Smoke Tests

Offline release smoke test:

src/shell/test/smoke-release-archive.sh <archive.tar>

Online build smoke test:

src/shell/test/smoke-release-online-build.sh <archive.tar>

The offline smoke test must not require GitHub access. The online build smoke test intentionally runs native self build and may require GitHub access for FetchContent dependencies.

kog export --single automatically runs the offline release archive smoke test when src/shell/test/smoke-release-archive.sh exists. Default multi-archive exports skip this validation because the root archive does not contain submodule working-tree contents. Use --validate-release-archive to require validation, or --no-validate-release-archive to skip it explicitly.

Public Docs Audit

Run this when changing README, SKILL, or current user-facing docs:

src/shell/test/audit-public-doc-script-refs.sh

The audit blocks stale root-shell workflow references such as retired installer, workspace, repo-management, branch-operation, test, and legacy smart script paths unless the line is explicitly documenting them as retired or historical.

Root Wrapper Generator

Root wrapper generation lives at:

src/shell/core/gen-root-wrappers.sh --profile standalone --target <repo-root>
src/shell/core/gen-root-wrappers.sh --profile oss --target <repo-root>
src/shell/core/gen-root-wrappers.sh --profile repo-passive-mode --target <repo-root>
src/shell/core/gen-root-wrappers.sh --profile repo-passive-mode-with-ai --target <repo-root>

Validate it with:

src/shell/test/smoke-root-wrapper-generator.sh

Documentation Contract

Current docs:

• docs/guides/current-command-surface.md
• docs/guides/kcc-commit-message-policy.md
• docs/guides/cpa-commit-plan-workflow.md
• docs/repo-hygiene.md
• docs/development/testing.md
• docs/cpp-profile-coverage-pgo-model.md

Historical docs may preserve old shell workflows. They are useful design context, but they are not the current product surface.

License

MIT License. See LICENSE in the source repository.

Coverage and PGO guardrails

• Microsoft.CodeCoverage.Console coverage output is not MSVC PGO training data.
• MSVC unified PGO+coverage execution is only supported with OpenCppCoverage.
• Microsoft.CodeCoverage.Console server-mode is local/session detached collection, not remote telemetry.
• Keep coverage-all as canonical coverage lane.
• Keep pgo-gather and pgo-rebuild as canonical release PGO lanes.

Retired Root-Shell Surface

Do not recommend retired root script workflows as current usage. Examples include old installer wrappers, workspace scripts, repo-management scripts, branch-operation scripts, commit-tools scripts, old test runners, and legacy smart-* scripts. Use kog commands instead.

Terminology

• stable-dev mode: sync strategy based on upstream stable tags.
• dev mode: sync strategy based on upstream default branch tip.
• stable branch: project convention branch name such as branch_v1.2.6.
• agent proxy mode: mode where the external command agent is the semantic authority and kog disables internal second-review behavior.
• workflow lock marker: .git/kano-smart-commit-push.lock, used to prevent concurrent workflow edits.
• protocol-priority=auto: default behavior that should not be persisted to .gitmodules; persist only explicit ssh or https.

Git terms such as remote, default branch, detached HEAD, submodule, rebase, cherry-pick, stash, and tag keep their standard Git meanings.