0.0.1-preview.6 • Published 22h agoCLI

@nettoolskit/agent

Licence

MIT

Version

0.0.1-preview.6

Deps

Size

22.8 MB

Vulns

Weekly

607

Install scriptsThis package runs scripts during installation (preinstall/install/postinstall)

Summary Dependency Versions

nettoolskit-agent

Canonical reusable agent, instruction, governance, and model-routing repository for NetToolsKit.

nettoolskit-agent owns the reusable intelligence assets used by NetToolsKit products and developer tooling. It is the canonical home for Super Agent lifecycle guidance, agent instructions, context economy, planning workflow, model-routing policy, and provider projection governance.

This repository provides agent assets to nettoolskit-copilot, nettoolskit-control, nettoolskit-codegen, nettoolskit-devops, nettoolskit-assurance, and local CLI workflows through explicit contracts and versioned files. It must not own product orchestration, machine execution, deployment operations, code generation output, or terminal UI behavior.

Features

Canonical Super Agent lifecycle source under definitions/agents/super-agent.
Complete versioned definitions package for agents, instructions, hooks, skills, provider assets, and templates.
Shared development and governance instructions for context economy, planning, validation, closeout, and model routing.
Declarative model-routing policy contract and validation without runtime model decision execution.
Provider projections for Codex, Claude, and GitHub/Copilot with explicit source pointers back to canonical definitions.
Provider-neutral workspace adapter policy that keeps AGENTS.md as the preferred local repository contract while global runtime assets install under provider folders.
Agent asset catalog export for deterministic definitions/** inventory metadata without context or runtime assembly.
Declarative Super Agent context package manifest for downstream runtime orchestrators.
Deterministic UCP generation from planning documents and explicit parameters without AI-authored progress summaries.
Requirements, use case, architecture, UCP, and planning traceability governance with durable sources under docs/requirements/**.
Deterministic planning status reports for checklist progress, stale LastUpdated metadata, pending items, and planning-compatible Markdown.
Scriptable work mining from planning checklists to identify repeated work that should become deterministic automation instead of LLM-only execution.
Read-only scriptable work mining command surface for active and completed planning documents, including optional sanitized dry-run Markdown artifacts under .deployment/artifacts/planning/scriptable-work.
Promotion readiness dry-run checks before any global Super Agent replacement.
Repository-local promotion staging bundles under .deployment/artifacts.
Dry-run global apply planning with backup and smoke-check evidence.
Explicit runtime asset promotion apply with backup-before-overwrite, smoke evidence, staged-asset preflight, and rollback readiness for caller-injected runtime roots.
Dry-run-first Super Agent promotion operator example with explicit --apply and caller-supplied runtime root requirements.
Read-only Super Agent runtime verification for promoted assets.
Deterministic VS Code MCP catalog rendering and global mcp.json synchronization with dry-run default, backup-before-overwrite, explicit --yes confirmation, and post-write verification.
Deterministic audit engine with stable findings for README, CHANGELOG, instruction, provider projection, metadata, and artifact policy validation.
Agent-owned audit adapters that consume product-neutral nettoolskit-validation findings while preserving the existing Agent report contract and planning keys.
Service manifest discovery for catalog, model routing, UCP, audit, validation, and promotion readiness/staging contracts.
Lightweight Rust validation profiles with AI-consumable planning output.
Deterministic Rust command catalog for agent-safe command recommendation without executing commands, including separate single-package and workspace Cargo command profiles.
Declarative Codex skill runtime profiles that preserve Super Agent as the single starter, classify optional/provider skills, and enforce routing description budgets.
Deterministic Codex SKILL.md inventory parsing for supplied roots with sanitized duplicate, metadata, and sensitive-description findings.
Sanitized Codex skill runtime JSON, planning-input, and Markdown pending reports under .deployment/artifacts/codex-skill-runtime.
Validation catalog alignment checks for executable versus roadmap validation surfaces.
Compatibility lifecycle policy validation for implemented, planned, future, external, and retired validation checks.
Validation self-audit checks for implemented command adapters, manifest capabilities, introspection surfaces, test evidence, and audit ledger contracts.
Super Agent governance validation for lifecycle orchestration, permission gates, skill runtime profiles, and non-intrusive hook contracts.
Agent runtime-boundary validation for keeping RAG/CAG/HyDE, memory execution, model selection, approvals, and evidence replay in the correct downstream services.
Instruction governance validation for authoritative source policy, ownership ledgers, metadata envelopes, and architecture boundary baselines.
Planning, knowledge-base, warning-baseline, release-governance, and release-provenance validation for PR-ready governance controls.
Reusable Audit Evidence Pack templates for PR, release, security review, and audit closeout evidence without embedding raw logs or local metadata.
Static operations, security, supply-chain, and workspace-efficiency validation gates for instruction-owned operational baselines.
Deterministic C# style validation contracts with optional Markdown pending-checklist output for Super Agent planning.
Agent-owned function adapter handoff contracts for passing validated deterministic function requests to Harness-compatible execution layers.
DET runtime-wrapper preflight metadata on function handoffs so Harness or host runtimes can prove guarded DET start readiness before use without Agent executing DET.
Versioned function traceability matrix tying instruction ids, bindings, function ids, linked command ids, and required test evidence.
Report-only deterministic function test role coverage for happy-path, failure-path, conditional edge-case, contract, and security-negative evidence without breaking the existing traceability catalog during migration.
Item-level instruction coverage catalog that distinguishes pending instruction inventories from covered deterministic items.
Instruction package manifest and detail index for migrating large instructions into instructions.md cores with demand-loaded *.details.md files while keeping default runtime context small.
Focused README validation functions and a 52-item README instruction inventory with 51 deterministic source or file rules and one manual public API coverage review item instead of treating the aggregate README command as full coverage.
Focused PowerShell, scriptable-work, and planning taxonomy item coverage that binds already-proven static validators to individual instruction rules.
Focused CI/CD DevOps workflow coverage for provider startup ownership, GitRiver PR-to-main requirements, secondary provider scope, trigger filters, cancel-in-progress concurrency, job timeouts, broad pull request label events, expensive-job controls, docs-only cheap paths, reviewable skip evidence, explicit signal checks, visible analysis evidence, cache intent, stable artifact metadata, rebuild-reuse checks, promotion environment metadata, rollback evidence, secret materialization cleanup, schema/deploy ordering, side-effect guards, external uses: full-SHA pinning, least-privilege permissions, and dynamic script download checks without executing CI.
Focused CI/CD stage-policy coverage for GitHub Actions stage taxonomy, single-responsibility boundaries, needs, validation-before-mutation ordering, build publication boundaries, package/runtime separation, release gates, deploy approvals, verify-after-deploy evidence, security failure gates, review evidence, secret evidence guards, expensive-stage controls, and matrix fail-fast evidence intent without executing CI.
CI/CD Stage Policy source-contract coverage for machine-readable JSON, SARIF, JUnit, SBOM, manifest, and release-gate evidence guidance through validation-cicd-stage-policy, raising covered instruction items to 1438 and CI/CD Stages coverage to 47 of 48 items while keeping external dashboard and deployment-system link evidence manual-only.
Static Analysis/SonarQube source-contract coverage for coverage-import ownership, real-regression quality gates, hotspot/code-smell governance, and actionable technical-debt reporting through validation-static-analysis-sonarqube, raising covered instruction items to 1442 and SonarQube coverage to 28 of 31 items while keeping external analyzer/profile alignment and scanner performance evidence manual-only.
Security Vulnerabilities source-contract coverage for security baseline, cross-layer secure-default controls, API controls, backend controls, and database controls through validation-security-vulnerabilities, raising covered instruction items to 1463 and Security Vulnerabilities coverage to 68 of 86 items while keeping scanner/feed/runtime/operator evidence manual-only.
CI/CD Supply Chain source-contract coverage for retained OWASP CI/CD, software supply-chain, SBOM, and secrets-management references through validation-supply-chain, raising covered instruction items to 1467 and CI/CD Supply Chain coverage to 34 of 50 items while keeping live OWASP, publisher-trust, runner, secret, review, and incident evidence manual-only.
Repository Operating Model source-contract coverage for source ownership, Copilot/Control/DevOps/Harness boundaries, planning separation, domain routing, README/knowledge closeout, and delivery-state transparency through validation-release-governance, raising covered instruction items to 1478 and Repository Operating Model coverage to 33 of 34 items while keeping root .gitignore preservation manual-only.
Definitions Metadata Envelope source-contract coverage for semantic signal guidance, routing metadata intent, template policy boundaries, title and summary quality, taxonomy alignment, alias usage, pillar remediation, and generic pillar-stuffing rejection through validation-instruction-metadata, raising covered instruction items to 1488 and Metadata Envelope coverage to 26 of 29 items while keeping provider projection, stable id, and starter template provenance manual-only.
Backend Integration source-contract coverage for real public behavior, API/persistence/messaging/adapter seam guidance, and OWASP ASVS/API Security Top 10/WSTG reference mapping through validation-backend-integration-testing, raising covered instruction items to 1491 and Backend Integration coverage to 40 of 48 items while keeping applicability, browser-delegation, and measured performance evidence outside static automation.
Artifact Layout source-contract coverage for .gitignore baseline-first guidance, .build versus .deployment output selection, and script/template canonical output defaults through validation-generated-artifact-hygiene, raising covered instruction items to 1494 and Artifact Layout coverage to 16 of 17 items while keeping new-project baseline inheritance manual-only.
Effort Estimation/UCP source-contract coverage for final-document template boundaries and context/problem/persona/goal/scope/metric/risk/dependency/ rollout fields through validation-effort-estimation-ucp, raising covered instruction items to 1496 and UCP coverage to 23 of 24 items while keeping POC evidence versus MVP assumption separation manual-only.
Persistence And ORM source-contract and guardrail coverage for applicability scope, domain/data routing, soft-delete requirement evidence, and batch/bulk semantic evidence through validation-persistence-orm, raising covered instruction items to 1502 and Persistence ORM coverage to 21 of 23 items while keeping keyset fit and least-privilege role proof outside static automation.
Database Configuration source-contract coverage for scope, schema/query routing, ORM routing, quality principles, retry jitter, read-replica lag, expand/migrate/contract, destructive schema rollout, tenant export authorization, and zero-downtime migration checklist guidance through validation-database-configuration-operations, raising covered instruction items to 1512 and Database Configuration coverage to 48 of 57 items while keeping live failover, load, backup, restore, RTO/RPO, and dashboard proof manual-only.
Database Schema And Query source-boundary coverage for scope, database-configuration routing, ORM routing, security routing, and runtime policy boundaries through validation-database-schema-query, raising covered instruction items to 1517 and Database Schema And Query coverage to 15 of 36 items while keeping workload, query-plan, indexing, migration-runtime, and realistic data-shape proof manual or reviewer-owned.
Focused Platform Reliability and Resilience coverage for reliability objectives, resilience patterns, degradation, capacity, chaos guidance, disaster recovery, deployment safety, and readiness without executing infrastructure tooling.
GitRiver-backed CI/CD foundation for PR Rust quality, Agent validation, package dry-run, and vulnerability gates while GitHub Actions remains a lightweight metadata and changelog guardrail.
Human-readable command catalog reference for CLI families, deterministic function mappings, instruction item coverage, and validation workflow.
Core Governance deterministic function coverage for Feedback/Changelog change-kind section grouping through release-governance validation, raising covered instruction items to 333.
Release Artifact Sanitization function coverage for selected text release artifact local-machine-path scanning through generated-artifact hygiene, raising covered instruction items to 334.
Template Standards validation now applies required and forbidden patterns to template contents, including Feedback/Changelog entry template feedback integration fields, raising covered instruction items to 335.
Release Artifact Sanitization function coverage for selected text release artifact raw secret value scanning through generated-artifact hygiene, raising covered instruction items to 336.
Release Artifact Sanitization function coverage for selected text release artifact environment dumps and sensitive CI log scanning through generated-artifact hygiene, raising covered instruction items to 337.
Release Artifact Sanitization function coverage for selected text release artifact provider-specific secret value scanning through generated-artifact hygiene, raising covered instruction items to 338.
Release Artifact Sanitization function coverage for selected text release artifact secret-name descriptor validation through generated-artifact hygiene, raising covered instruction items to 339.
Feedback/Changelog function coverage for concrete examples in the changelog entry template through template standards, raising covered instruction items to 340.
Git Workflow function coverage for explicit PR changed-path changelog enforcement through validation-git-pr-changelog, raising covered instruction items to 341.
Artifact Layout function coverage for generated artifact source-tree cleanup through validation-generated-artifact-hygiene, raising covered instruction items to 342.
Feedback/Changelog function coverage for issue context, problem, solution, and impact fields through template standards, raising covered instruction items to 343.
Release Artifact Sanitization function coverage for raw environment values in generated evidence through generated-artifact hygiene, raising covered instruction items to 344.
Feedback/Changelog function coverage for canonical feedback tracking table columns through template standards, raising covered instruction items to 345.
Release Artifact Sanitization function coverage for high-confidence sensitive-pattern blocking through generated-artifact hygiene, raising covered instruction items to 346.
Release Artifact Sanitization function coverage for personal operator and machine identifier blocking through generated-artifact hygiene, raising covered instruction items to 347.
Release Artifact Sanitization function coverage for audit evidence storage boundaries through generated-artifact hygiene, raising covered instruction items to 348.
Release Artifact Sanitization function coverage for raw audit payload and transcript blocking through generated-artifact hygiene, raising covered instruction items to 349.
Release Artifact Sanitization function coverage for JSON release manifest public metadata through generated-artifact hygiene, raising covered instruction items to 350.
Release Artifact Sanitization function coverage for neutral release example values through generated-artifact hygiene, raising covered instruction items to 351.
Release Artifact Sanitization function coverage for selected source and package archive entry scanning through generated-artifact hygiene, raising covered instruction items to 353.
Feedback/Changelog function coverage for canonical pull request template title, description section order, Applied Instructions, EOF checklist, and label metadata guidance through template standards, raising covered instruction items to 358.
Feedback/Changelog function coverage for PR release-communication instruction ownership through catalog alignment, raising covered instruction items to 359.
Feedback/Changelog function coverage for the canonical GitHub issue template through template standards, raising covered instruction items to
Release Artifact Sanitization function coverage for selected evidence, archive, manifest, checksum, OCI bundle, and metadata directory release artifact classes through generated-artifact hygiene, raising covered instruction items to 361.
Feedback/Changelog function coverage for explicit breaking CHANGELOG entries requiring README migration, upgrade, compatibility, or rollback guidance through release-governance validation, raising covered instruction items to 362.
Scriptable Work function coverage for stable inputs, stable outputs, safe write scopes, approval-gated sensitive actions, approved maintenance scope, and dry-run-before-mutation enforcement, raising covered instruction items to 369.
Repository Operating Model function coverage for .build transient output and no-secret/local-state hygiene through generated-artifact validation, plus PR changed-path CHANGELOG enforcement through Git workflow validation, plus canonical instruction source placement through instruction metadata validation, plus definitions-owned canonical asset placement through instruction architecture validation, plus semantic commit-message validation, raising covered instruction items to 375.
Git Workflow function coverage for semantic English imperative commit subjects through validation-git-commit-message, raising covered instruction items to 376.
Scriptable Work function coverage for repository-owned Rust validators and command catalogs before ad hoc shell through planning-scriptable-work-mine, raising covered instruction items to 377.
Repository Operating Model function coverage for keeping nettoolskit-agent guidance, contracts, governance catalogs, and static audits only through validation-agent-runtime-boundary, raising covered instruction items to 378.
Repository Operating Model function coverage for deterministic active plan/spec scaffolding through ntk runtime scaffold-workstream, raising covered instruction items to 379.
Scriptable Work function coverage for completed validation plans requiring valid and invalid fixture evidence through validation-planning-structure, raising covered instruction items to 380.
Repository Operating Model function coverage for native runtime context, memory, sync, and health command selection through ntk runtime contracts, raising covered instruction items to 381.
Repository Operating Model function coverage for native security audit gates before dependency, package, and release changes through ntk runtime contracts, raising covered instruction items to 382.
Repository Operating Model function coverage for agents, skills, hooks, templates, and generated provider surfaces through instruction architecture and template standards validation, raising covered instruction items to 384.
Planning closeout function coverage for blocking fully checked active plans without validation, review, closeout, and acceptance or blocker evidence through validation-planning-structure, raising covered instruction items to 386.
Scriptable Work function coverage for accepted reusable automation requiring active or completed planning evidence that references the script through validation-script-automation-contract, raising covered instruction items to 387.
VS Code workspace-efficiency function coverage for duplicate-pressure baseline evidence, minimal committed workspace-local settings, shared-support folder separation, and formatter EOF/Prettier policy through validation-workspace-efficiency, raising covered instruction items to 400.
VS Code workspace-efficiency deterministic coverage for source-of-truth, runtime sync command, pseudo-inheritance, discovery, layout, duplicate-window policy, and edit-payload normalization contracts through the same validator, raising covered instruction items to 1191 and reducing VS Code deterministic candidates to zero.
Kubernetes deterministic coverage for static manifest, workload security, resource, probe, networking, storage, rollout, operation, and verification policy through validation-k8s-manifests, raising covered instruction items to 1228 and reducing global deterministic candidates to zero.
Context Economy source-contract hardening for memory model, operating modes, compression triggers, preserve/discard rules, checkpoint triggers, priority order, template ownership, and cross-instruction ownership through validation-context-package, raising covered instruction items to 1267 while preserving the distinction between source-contract validation and live LLM session behavior.
Prompt Template source-contract quality coverage for input/context separation, target-user markers, measurable acceptance, stable output formats, tool/source/refusal contracts, security/privacy/source attribution, and multi-objective anti-pattern checks through validation-template-standards, raising covered instruction items to 1274 and Prompt Templates coverage to 27 of 30 items while keeping Prompt Template semantic usefulness outside the deterministic claim.
Prompt Template source-contract completion for bounded visible reasoning/evidence requests and conservative POML authoring when prompt assets require reusable structure, fixtures, external inputs, or provider-independent rendering through validation-template-standards, raising covered instruction items to 1410 and Prompt Templates coverage to 29 of 30 items while leaving prompt behavior CHANGELOG impact manual-only.
Authoritative Sources source-contract coverage for lookup order, official documentation, maintainer and community fallback, required external lookup triggers, narrowest stack selection, response source-type wording, conflict-resolution rules, high-risk authoritative-doc-over-memory guidance, and insufficient-docs disclosure through validation-authoritative-source-policy, raising covered instruction items to 1425 and Authoritative Sources coverage to 17 of 17 items while keeping live browsing and source adequacy as runtime behavior.
Feedback/Changelog source-contract coverage for canonical release communication ownership, PR goals, title style, security and performance checklist guidance, namespace and generated-file consistency, discussion focus, material evidence attachment, consolidated feedback history, changelog-template provenance, SemVer impact classes, and discontinuation timelines through validation-release-governance, raising covered instruction items to 1437 and Feedback/Changelog coverage to 28 of 33 items while keeping live CI, reviewer assignment, issue triage, and issue-to-tag workflow evidence manual-only.
Agentic Surfaces source-contract definition coverage for MCP, RAG, CAG, A2A, tool projection, retrieval/compaction separation, lane defaults, and extension-class boundaries through validation-agent-runtime-boundary, raising covered instruction items to 1286 and Agentic Surfaces coverage to 45 of 62 items while keeping live runtime behavior outside the deterministic claim.
Agent Model Routing source-contract coverage for applicability, provider transport/MCP/A2A boundaries, downstream orchestrator ownership, budget/cost/prompt-compaction guardrails, and policy-guidance-only runtime boundaries through validation-model-routing-policies, raising covered instruction items to 1292 and Agent Model Routing coverage to 23 of 23 items while keeping live model selection and provider calls downstream.
Sub-Agent Planning Workflow source-contract coverage for lifecycle order, SDD layout, dated progress, active-plan reuse, slice decomposition, required slice shape, sub-slice matrix, pillar checks, worktree isolation, and closeout archive gating through validation-planning-structure, raising curated instruction items to 1767, covered instruction items to 1302, and planning workflow coverage to 12 of 12 items while keeping live subagent execution outside the deterministic claim.
Copilot Instruction Creation source-contract coverage for semantic guidance ownership, provider semantic surface rendering, body focus, Markdown scanning, mandatory quality pillars, Standardization/Security/ Performance signals, concise pillar coverage, quality-gate states, and pillar-validation finding evidence through validation-instruction-metadata and validation-instruction-architecture, raising covered instruction items to 1317 and Copilot Instruction Creation coverage to 55 of 55 items.
Docker instruction routing coverage for primary ownership scope and adjacent Kubernetes, API performance, observability/SRE, and platform reliability/resilience boundaries, plus Docker image-build, runtime, Compose, local development, vulnerability-scan, and Kubernetes verification-boundary detail retention through validation-instruction-architecture, plus build-layer invalidation coverage through validation-docker-static-safety, and static final-size/reproducibility guardrails through existing Docker static-safety functions, plus runtime evidence verification through validation-docker-runtime-evidence, raising covered instruction items to 440 and reducing Docker deterministic candidates to zero.
PowerShell authoring, path, safety-runtime, mutation, diagnostics, compatibility, performance, and security detail-retention coverage through validation-powershell-standards, raising covered instruction items to 471 and reducing PowerShell deterministic candidates to zero.
CI/CD DevOps external action pinning coverage through validation-cicd-devops, requiring external GitHub Actions uses: references to use full commit SHAs.
CI/CD DevOps workflow permissions coverage through validation-cicd-devops, requiring explicit least-privilege GitHub Actions permissions and raising covered instruction items to 473.
CI/CD DevOps dynamic script download coverage through validation-cicd-devops, requiring checksum/signature verification, pinned SHA or approved release-tag evidence, and runner temp or workspace script output paths, raising covered instruction items to 475.
CI/CD DevOps artifact retention and step-summary coverage through validation-cicd-devops, requiring upload-artifact retention-days and real GITHUB_STEP_SUMMARY evidence, raising covered instruction items to 476.
CI/CD DevOps native validation preference coverage through validation-cicd-devops, warning when workflows use raw package audit commands instead of available ntk validation surfaces, raising covered instruction items to 477.
CI/CD DevOps validation evidence coverage through validation-cicd-devops, requiring validation-oriented jobs to emit summary, artifact, or report evidence, raising covered instruction items to 478.
Knowledge Base deterministic function coverage through validation-knowledge-base, requiring canonical authoring roots, README lane and maintenance policy, record metadata, semantic filenames, grouped separators, source-path provenance, and native validation command evidence, raising covered instruction items to 523.
Context Economy deterministic function coverage through validation-context-package, requiring checkpoint template field order, command reference coverage, and active planning-root continuity evidence, raising covered instruction items to 532.
Brainstorm Spec Workflow deterministic function coverage through validation-spec-workflow, requiring active spec metadata, required sections, timestamped decisions, concrete acceptance evidence, design slice matrix shape, related-plan linkage, and completed archive hygiene, raising covered instruction items to 542.
Backend Architecture Core deterministic function coverage through validation-backend-architecture-core, requiring backend architecture evidence, dependency-direction checks, domain/presentation boundary checks, application workflow shape, module ownership heuristics, and correlated test evidence, raising covered instruction items to 558.
Backend Integration And API Testing deterministic function coverage through validation-backend-integration-testing, requiring backend integration-test framework, dependency harness, API host, browser-boundary, suite-boundary, fixture-determinism, and secret-hygiene evidence, raising covered instruction items to 571.
Persistence And ORM deterministic function coverage through validation-persistence-orm, requiring .NET persistence boundary, mapping, lazy-loading, repository, read-model, connection-secret, and observability evidence, raising covered instruction items to 586.
Backend Architecture Core deterministic function coverage expansion through validation-backend-architecture-core, adding focused infrastructure-policy, value-object immutability, authorization-boundary, validation-order, versioned-contract, and distinguishable-failure checks, raising covered instruction items to 592.
Backend Architecture Core deterministic function coverage completion through validation-backend-architecture-core, adding focused contract-consistency, outbox-reliability, event-consumer reliability, external I/O resilience, service-boundary security, observability, reproducible-delivery, and schema-rollout checks, raising covered instruction items to 600 and reducing Backend Architecture Core deterministic candidates to zero.
CI/CD DevOps provider and trigger economy coverage through validation-cicd-devops, adding GitRiver startup checks, secondary provider scope checks, expensive-job trigger controls, docs-only cheap-path checks, job-level changed-surface skips, and skip-reason evidence, raising covered instruction items to 607.
CI/CD DevOps build, artifact, promotion, and platform guardrail coverage through validation-cicd-devops, adding explicit signal checks, visible analysis evidence, cache-intent validation, stable artifact metadata, rebuild-reuse validation, promotion environment checks, rollback evidence, secret materialization cleanup, schema/deploy ordering, and repository side-effect guards, raising covered instruction items to 621.
CI/CD DevOps deterministic function coverage completion through validation-cicd-devops, adding routing-boundary, fail-fast dependency, IaC/application coordination, matrix budget, deterministic command, surface split, local/remote ownership, suite trigger scope, expensive evidence, incremental determinism, environment boundary, secret log, and workflow-template controls, raising covered instruction items to 665 and reducing CI/CD DevOps deterministic candidates to zero.
CI/CD Stages deterministic function coverage through validation-cicd-stage-policy, adding focused stage taxonomy, single-responsibility, package/runtime separation, release gate, deploy approval, verify-after-deploy, security failure, evidence output, secret evidence, expensive-stage, validation-side-effect, documentation-release, and performance-release checks, raising covered instruction items to 701 and reducing CI/CD Stages deterministic candidates to 2.
CI/CD Supply Chain deterministic function coverage through validation-supply-chain, adding trusted workflow trigger checks, immutable action and container pinning, least-privilege identity/OIDC evidence, runner trust boundaries, secret material hygiene, safe execution source checks, and release SBOM/provenance evidence checks, raising covered instruction items to 731 and reducing CI/CD Supply Chain deterministic candidates to zero.
Static Analysis SonarQube deterministic function coverage through validation-static-analysis-sonarqube, adding focused scanner configuration, source/test boundary, exclusion, coverage report, quality-gate, PR analysis, profile-policy, reporting, and pipeline-boundary checks, raising covered instruction items to 755 and reducing SonarQube deterministic candidates to zero.
Security Vulnerabilities deterministic function coverage through validation-security-vulnerabilities, adding static vulnerability instruction boundary, native audit gate, per-stack audit command, retired wrapper, evidence path, blocking severity, evidence shape, CI trigger boundary, OWASP/CWE mapping, and docs-only boundary checks, raising covered instruction items to 774 and reducing vulnerability deterministic candidates to 28 without running scanners.
API High Performance and Security deterministic function coverage through validation-security-api-high-performance, adding focused endpoint target, resource budget, load profile, collection control, OpenAPI gate, abuse-limit, ProblemDetails, resilience, observability, suite trigger, performance evidence, OWASP API mapping, and security/load runner boundary checks, raising covered instruction items to 797 and reducing API high-performance deterministic candidates to 18 without running load tests or security probes.
Backend Integration And API Testing deterministic function coverage expansion through validation-backend-integration-testing, adding focused test-matrix, affected-shard, API contract, deterministic test data, negative security, resilience, CI diagnostic, and security evidence classification checks, raising covered instruction items to 815 and reducing backend integration deterministic candidates to 6 without running .NET tests, browsers, containers, or network targets.
Priority deterministic function coverage completion for Knowledge Base, Effort Estimation/UCP, Deployment Topology, Database Configuration, and Backend Integration And API Testing, raising covered instruction items to 1068 and reducing global deterministic candidates to 160 without executing live databases, containers, browsers, networks, DAST, load tests, or .NET test suites.
Frontend deterministic function coverage completion through validation-frontend-e2e-testing, validation-frontend-vue-quasar-code-organization, and validation-frontend-architecture-core, adding 68 focused static validation functions, raising covered instruction items to 1136, and reducing global deterministic candidates to 92 without running browsers, package managers, DAST, load suites, CI, or external services.
Frontend UI/UX deterministic function coverage completion through validation-frontend-ui-ux, adding 14 focused static validation functions, raising covered instruction items to 1150, and reducing global deterministic candidates to 78 without running browsers, accessibility crawlers, package managers, visual diff tools, DAST, load suites, CI, or external services.
Database Schema And Query deterministic function coverage completion through validation-database-schema-query, adding 10 focused static validation functions, raising covered instruction items to 1160, and reducing global deterministic candidates to 68 without executing databases, migrations, query plans, package managers, containers, networks, or external services.
Data Privacy And Compliance deterministic function coverage completion through validation-data-privacy-compliance, adding 15 focused static validation functions, raising covered instruction items to 1175, and reducing global deterministic candidates to 53 without calling privacy platforms, identity providers, databases, ticketing systems, cloud services, scanners, or external compliance evidence stores.
CI/CD Stages deterministic function coverage completion through validation-cicd-stage-policy and validation-git-pr-changelog, adding instruction applicability and changelog-impact gates, raising covered instruction items to 817 and reducing CI/CD Stages deterministic candidates to zero.
Security Vulnerabilities deterministic function coverage expansion through validation-security-vulnerabilities, adding security test taxonomy and release-gate taxonomy checks for SCA, SAST, secrets, IaC/workflow, DAST/API, OpenAPI-driven runner, regression testing, and critical exposed surface gates, raising covered instruction items to 826 and reducing vulnerability deterministic candidates to 19 without running scanners or network probes.
API High Performance and Security deterministic function coverage expansion through validation-security-api-high-performance, adding focused service contract compatibility, async message contract, query safety, query efficiency, query timeout/cancellation, cache-control, cache invalidation, cache ownership/fallback, auth token, authorization, least privilege, input normalization, and mutation field safety checks, raising covered instruction items to 839 and reducing API high-performance deterministic candidates to 5 without running load tests, DAST, scanners, or network probes.
Security Vulnerabilities deterministic function coverage completion through validation-security-vulnerabilities, adding static cross-layer secret hygiene, API strict schema, API resource limit, API version inventory, WSTG/OWASP reference, frontend browser security, backend credential, injection, middleware, error-disclosure, and database parameterized-query checks, raising covered instruction items to 858 and reducing vulnerability deterministic candidates to zero without running scanners, package managers, browser tests, API probes, Docker, CI, or network calls.
Context Economy deterministic function coverage completion through validation-context-package, adding explicit user-request checkpoint trigger and recognized command immediacy checks, raising covered instruction items to 876 and reducing Context Economy deterministic candidates to zero.
API High Performance and Security deterministic function coverage completion through validation-security-api-high-performance, adding focused release load/stress, negative abuse test, dependency vulnerability gate, PR smoke performance boundary, and concurrent abuse degradation checks, raising covered instruction items to 905 and reducing API high-performance deterministic candidates to zero without running load tests, scanners, DAST, package managers, containers, CI, or network probes.
Brainstorm Spec Workflow deterministic function coverage completion through validation-spec-workflow, adding mandatory trigger contract, skip governance, workspace contract, stable naming, workstream reuse, planning-readiness update timestamps, plan relationship boundaries, command-output evidence, temp-fixture locality, and plan-only skip reason checks, raising covered instruction items to 997 and reducing Brainstorm Spec Workflow deterministic candidates to zero.

Introduction
Features
Architecture
Control Plane Model
Components
Compatibility and Support
Operations
Planning
Changelog
Governance and Security
Build and Tests
Contributing
Dependencies
References
License
Package publication

Architecture

nettoolskit-agent separates canonical agent knowledge from runtime-specific provider projections. Canonical rules live in definitions/agents/** and definitions/instructions/**; provider outputs must point back to those sources instead of becoming independent policy trees.

Global provider runtime installation and downstream workspace adapters are separate boundaries. Runtime installation projects Agent-owned assets to operator folders such as .claude, .codex, .github, and .agents. Downstream repositories should keep only local facts, preferably in root AGENTS.md, such as repository identity, stack, entrypoints, constraints, and specialist routing. Provider-specific local files are compatibility bridges only and must not replace AGENTS.md as the local contract.

flowchart TD
    canonical[Canonical agent and instruction sources]
    validation[Deterministic audit engine]
    foundation[Product-neutral validation foundation]
    adapters[Agent audit adapters]
    projections[Provider projections]
    consumers[NetToolsKit product repositories]

    canonical --> validation
    validation --> adapters
    adapters --> foundation
    foundation --> adapters
    canonical --> projections
    projections --> consumers
    adapters --> consumers

Agentic Surfaces

nettoolskit-agent documents agentic surfaces as declarative contracts and validation rules. Runtime execution remains in downstream products and services.

Surface	Role	Entry Point	Support Status
MCP	Provider integration and private gateway configuration guidance.	`definitions/providers/codex/mcp/` and runtime catalogs	Supported as declarative catalog policy.
RAG	Retrieval and durable knowledge-base guidance for reusable recall.	`docs/knowledge-base/` and memory policy instructions	Supported as guidance and contracts only.
CAG	Context assembly, checkpoint, and prompt-layering guidance.	`definitions/agents/super-agent/` and context economy instructions	Supported as instruction contract.
HyDE	Pre-retrieval expansion and evidence-bound query policy.	memory and retrieval policy instructions	Supported as policy boundary.
A2A	Future agent-to-agent interoperability boundary.	Agentic Surfaces instruction and boundary details	Reserved until an explicit protocol surface exists.
LLM	Model-routing, fallback, and cognitive-work ownership guidance.	model-routing and scriptable-work instructions	Supported as declarative routing guidance.

The audit engine produces stable machine-readable findings with rule ids, severity, category, repository-relative paths, expected and actual values, remediation hints, and planning keys. Validation profiles consume the shared nettoolskit-validation foundation at the edge where possible, then map findings back into the Agent-owned audit contract and policy defaults. Foundation schemas, grouping keys, and neutral rule names are implementation details; public command output must keep the nettoolskit.agent.audit.v1 schema, Agent rule ids, Agent planning keys, and sanitized repository-relative paths.

Agent command output, core utilities, runtime observability, and deterministic handoff contracts consume reusable nettoolskit-rust crates through thin adapters. Generic terminal rendering comes from nettoolskit-cli; secret-shape screening and other low-level helpers come from nettoolskit-core; telemetry vocabulary comes from nettoolskit-observability; command-output status vocabulary comes from nettoolskit-contracts. Agent-specific rules, provider projection policy, instruction bindings, and Super Agent planning metadata stay inside this repository.

Durable behavior sources live under docs/requirements/**. Requirements, business rules, use cases, and architecture stay there; UCP pages remain generated planning artifacts under planning/ucps/**.

Instructions are audited as structured documents. Active instruction sources use the packaged definitions/instructions/<domain>/ntk-*/instructions.md layout only; flat definitions/instructions/<domain>/ntk-*.instructions.md files are rejected by validation. Each active source must declare front matter, required metadata, a unique instruction id, and a non-empty Markdown body with a top-level heading. Package *.details.md files are indexed through the detail catalog and are not selected as default runtime instruction context. Metadata must be present in the front matter; body-only text does not satisfy audit requirements.

The asset catalog exporter indexes definitions/** as repository-relative metadata. It identifies reusable assets, provider projections, source pointers, and provider output paths without exporting file contents, assembling runtime context, or interpreting model-routing policy decisions.

Control Plane Model

This repository defines reusable agent behavior and governance, not machine execution. nettoolskit-control owns workers, leases, command execution, and approval bridges. nettoolskit-copilot owns the product orchestration layer that composes agent guidance with control, codegen, assurance, DevOps, and CLI surfaces.

nettoolskit-agent participates in the control model by publishing:

agent lifecycle instructions;
model-routing policy;
context economy and planning-first continuity rules;
provider projection governance;
validation helpers for instruction quality.

Runtime Orchestration Boundary

nettoolskit-agent owns declarative assets and validation. It may describe context package manifests, prompt layering contracts, model-routing policies, memory/RAG/CAG/HyDE policy, provider projections, and promotion safety rules.

nettoolskit-agent must not execute the live decision loop. It must not choose models at runtime, call providers, run retrieval queries, schedule workers, approve destructive actions, execute machine commands, create deployments, or compose product workflows.

When a downstream host wants to use DET, Agent function handoff contracts can declare the required runtime-wrapper preflight: the host resolves the request artifact, runs nettoolskit-det runtime-wrapper --json, and records the manifest artifact. Agent only declares the preflight contract and blocked runtime boundaries; Harness, Copilot, Control, or the host performs execution. Operators and downstream hosts can inspect the same read-only contract with ntk-agent runtime functions det-preflight --request-id <safe-id> --json-output; the command does not discover, install, or execute DET. Returned DET runtime-wrapper manifests are validated by Agent as contract artifacts only: schema version, request correlation, required decision, artifact references, sanitized metadata, and blocked provider/publication/ runtime-mutation boundaries must match the preflight contract.

nettoolskit-copilot owns the runtime orchestration layer. It consumes versioned nettoolskit-agent assets, assembles task-specific context, applies prompt middleware, chooses model lanes, executes memory and retrieval flows, calls domain services through contracts, coordinates approval gates, and records evidence and replay state.

nettoolskit-memory owns memory execution when a workspace exposes that service boundary. Super Agent guidance may request memory, RAG, CAG, HyDE, and context-package capabilities through published contracts, but the Agent repository remains the declarative source for policies and guidance only.

The boundary is intentionally one-way: nettoolskit-copilot consumes nettoolskit-agent; nettoolskit-agent does not depend on the Copilot runtime implementation.

Components

This repository uses a Rust workspace. Crate folders stay short inside the repository, while Cargo package names keep the full nettoolskit-agent-* product prefix. Rust package source, tests, and examples live inside the owning crate, never at the workspace root.

Component	Package	Responsibility
crates/agent	`nettoolskit-agent`	Package facade, binary entry point, examples, and command adapters. It re-exports workspace crates while command adapters remain package-owned.
crates/core	`nettoolskit-agent-core`	Shared audit report, path, planning, context, manifest, model-routing, and instruction-source contracts.
crates/catalog	`nettoolskit-agent-catalog`	Agent asset catalog and Rust command catalog services.
crates/validation	`nettoolskit-agent-validation`	Deterministic validators, domain audit profiles, and validation specifications.
crates/runtime	`nettoolskit-agent-runtime`	Deterministic function contracts, executable-instruction bindings, function coverage, promotion, and runtime handoff services.

The repository root is workspace-only. Command modules remain in crates/agent/src/commands/** until a concrete CLI extraction need exists. Domain-specific audit profile modules live under crates/validation/src/audit_profiles/**; core owns the shared audit contracts they compose.

Compatibility and Support

The crate targets Rust 1.95.0 and consumes shared contracts from ../nettoolskit-rust/crates/contracts, product-neutral validation primitives from ../nettoolskit-rust/crates/validation, core text/path utilities from ../nettoolskit-rust/crates/core, CLI terminal rendering primitives from ../nettoolskit-rust/crates/cli, and observability vocabulary from ../nettoolskit-rust/crates/observability. The dependency direction is one-way: Agent adapters consume foundation primitives, and the foundation does not depend on Agent policy, provider projections, runtime orchestration, or product workflows.

Provider projections are intentionally not installed globally from this repository until the Super Agent replacement gate passes.

Operations

npm/npx package surface

The @nettoolskit/agent npm package declares the ntk-agent command as a thin Node wrapper over the Rust agent binary. The wrapper uses NTK_AGENT_BINARY when set, otherwise it expects a release-provided native binary under npm/native/<platform-id>/, such as npm/native/win32-x64/ntk-agent.exe or npm/native/linux-x64/ntk-agent, keeping deterministic agent functions owned by the Rust workspace instead of duplicating them in JavaScript. Use npx @nettoolskit/agent manifest --json as the minimal package smoke command. Cargo output is pinned by .cargo/config.toml to .build/target. Generated validation, projection, packaging, or publication artifacts belong under .deployment/artifacts and must not be committed unless the release process explicitly publishes sanitized outputs. Machine-local NetToolsKit runtime state uses %USERPROFILE%\.ntk on Windows or $HOME/.ntk on Unix-like hosts. Isolated Git worktrees belong under .ntk/worktrees; dirty worktree cleanup preserves patches and untracked files under .ntk/worktree-salvage. Do not create ad hoc _worktrees, .worktree, or .worktrees folders inside source repositories.

GitRiver owns automatic pull-request gates for every PR targeting main in this repository, including Rust quality, Agent validation, package dry-run checks, Cargo vulnerability audits, changelog enforcement, and workflow governance validation. GitHub Actions remains manual-only for operator diagnostics so ordinary pull requests do not burn GitHub Actions minutes. Code-bearing changes under crates/**, src/**, scripts/**, tests/**, examples, definitions, manifests, or workflow metadata are routed through GitRiver gates; unrelated documentation and planning edits are skipped inside GitRiver by changed-surface checks. Repositories without GitRiver should apply the same preferred-provider ownership model through the company or project CI/CD provider. River PR gates are bounded by design: they publish expected contexts as pending, reuse dependency caches and .build/target-river, log timing for each major stage, and keep dependency-only PRs on compile/lint/package/audit proof unless a full-behavior gate is explicitly requested. The Agent River stage command list is declared in .ntk/ci/river.toml and executed through the shared ntk-devops ci river run runner. Shell files under scripts/ci/river/** remain transitional adapters or Agent-specific gates; they must not reintroduce public custom contexts such as river/agent-validation-quality.

Repository validation is local-first and runs through the deterministic audit engine:

Surface	Adapter owner	Foundation use	Aggregate behavior	Public output guarantee
`root-contracts`	`src/commands/validation/root_contracts.rs`	Repository-root path existence checks	Executable validation profile; covered by `root.file-contracts`	Agent audit schema, `root.*` rule ids, `root/file-contracts` planning key
`powershell-standards`	`src/commands/validation/operations_security.rs`	Static PowerShell instruction and hook script contract checks	Executable static validation profile; covered by `scripts.powershell-standards`	Agent audit schema, `powershell-standards.*` rule ids, `operations/powershell-standards` planning key, no PowerShell execution
`script-static-safety`	`src/commands/validation/scripts.rs`	Static script pattern and metadata classifiers	Executable validation profile	Agent audit schema, Agent script rule ids, sanitized sensitive metadata findings
`script-automation-contract`	`src/commands/validation/scripts.rs`	Reusable `scripts/automation` layout, metadata, catalog, documentation, and validation-evidence checks	Executable validation profile; covered by `scripts.automation-contract`	Agent audit schema, `script.automation-contract.*` rule ids, automation planning keys, no script execution
`generated-artifact-hygiene`	`src/commands/validation/generated_artifact_hygiene.rs`	Approved generated output root, `.gitignore`, artifact namespace, and explicit source-tree output checks	Repository governance runs without candidate paths; explicit leak-scan and source-tree candidates remain opt-in; covered by `artifacts.generated-hygiene`	Agent audit schema, `generated-artifact.*` rule ids, no recursive broad artifact scan
`model-routing-policies`	`src/commands/validation/model_routing.rs`	Canonical Super Agent policy-file source and contract checks	Executable static validation profile; covered by `model-routing.policy`	Agent audit schema, `model-routing.policy.*` rule ids, `model-routing/policy` planning key, no runtime routing
`routing-coverage`	`src/commands/validation/routing_coverage.rs`	Static provider routing catalog, prompt, and golden-test coverage checks	Executable validation profile with declared deferred domain routes kept non-blocking	Agent audit schema, `routing.coverage.*` rule ids, no model/runtime execution
`audit-ledger`	`src/commands/validation/audit_ledger.rs`	Rule registry, report contract, artifact writer, planning projection, and test evidence checks	Executable self-audit profile; covered by `validation.audit-ledger`	Agent audit schema, `validation.audit-ledger.*` rule ids, `validation/audit-ledger` planning key, no external tool execution
`warning-baseline`	`src/commands/validation/warning_baseline.rs`	Analyzer warning baseline schema, threshold, and scan-root checks	Executable static validation profile; covered by `validation.warning-baseline`	Agent audit schema, `warning-baseline.*` rule ids, `validation/warning-baseline` planning key, no analyzer execution
`release-governance`	`src/commands/validation/release_governance.rs`	Release governance document headings, release checklist, changelog, semantic version, and tag policy checks	Executable static validation profile; covered by `validation.release-governance`	Agent audit schema, `release-governance.*` rule ids, `release/governance` planning key, no GitHub or release mutation
`spec-workflow`	`src/commands/validation/spec_workflow.rs`	Active brainstorm spec metadata, sections, decisions, acceptance evidence, design-slice matrix, related-plan, archive hygiene, instruction detail contracts, stable active names, workstream reuse, planning-readiness update dating, and plan-only skip reasons	Executable static validation profile; covered by `planning.spec-workflow`	Agent audit schema, `spec-workflow.` rule ids, `planning/spec-workflow/` planning keys, no LLM or GitHub execution
`backend-architecture-core`	`src/commands/validation/backend_architecture_core.rs`	Backend architecture evidence, dependency direction, domain and presentation boundaries, module ownership, test evidence, infrastructure-policy ownership, value-object immutability, authorization boundary, validation order, versioned contracts, distinguishable failures, contract consistency, outbox reliability, event-consumer reliability, external I/O resilience, service-boundary security, observability, reproducible delivery, and schema rollout controls	Executable static validation profile; covered by `backend.architecture-core`	Agent audit schema, `backend-architecture.*` rule ids, backend planning keys, no runtime architecture judgment
`backend-integration-testing`	`src/commands/validation/backend_integration_testing.rs`	.NET backend integration-test framework, Testcontainers/dependency harness, API host harness, browser boundary, suite boundary, fixture determinism, secret hygiene, test matrix, affected shards, API contract coverage, deterministic test data, negative security coverage, resilience coverage, CI diagnostics, security evidence classification, domain unit evidence, expensive-suite gates, DAST/API abuse gates, load-suite triggers, performance assertion justification, and PR smoke/full-gate policy	Executable static validation profile; covered by `backend.integration-testing`	Agent audit schema, `backend.integration.*` rule ids, backend integration planning keys, no test, container, browser, network, DAST, or load execution
`persistence-orm`	`src/commands/validation/persistence_orm.rs`	.NET persistence source contracts, domain boundaries, mapping visibility, lazy-loading drift, repository boundaries, read-model projection, soft-delete evidence, batch/bulk semantics, connection-secret hygiene, and observability evidence	Executable static validation profile; covered by `persistence.orm`	Agent audit schema, `persistence-orm.*` rule ids, persistence planning keys, no database, migration, query, or network execution
`database-configuration-operations`	`src/commands/validation/database_configuration_operations.rs`	Repository-owned database configuration, secret, provider baseline, pooling, and timeout guidance	Executable static validation profile; covered by `data.database-configuration-operations`	Agent audit schema, `database-configuration.*` rule ids, `data/database-configuration` planning key, no database connectivity
`database-schema-query`	`src/commands/validation/database_schema_query.rs`	Database schema and query naming, keys, read/write model, broad-scan, SARGability, transaction, migration, storage-type, and timezone guidance	Executable static validation profile; covered by `data.database-schema-query`	Agent audit schema, `database-schema-query.*` rule ids, `data/database-schema-query` planning key, no database, migration, query plan, container, or network execution
`data-privacy-compliance`	`src/commands/validation/data_privacy_compliance.rs`	Privacy governance, classification, consent, access-control, protection, retention, subject-rights, export, release-readiness, and automated-test evidence	Executable static validation profile; covered by `data.privacy-compliance`	Agent audit schema, `data.privacy-compliance.*` rule ids, `data/privacy-compliance` planning key, no privacy platform, identity provider, database, ticketing, cloud, scanner, or external evidence-store execution
`observability-sre`	`src/commands/validation/observability_sre.rs`	Observability/SRE scope, resilience boundary, critical flow measurability, health-state taxonomy, SLO/error-budget policy, telemetry design, metrics quality, alerting, runbooks, health probes, incidents, telemetry security, and release verification	Executable static validation profile; covered by `operations.observability-sre`	Agent audit schema, `observability-sre.*` rule ids, `operations/observability-sre` planning key, no telemetry backend execution

emit stable AuditFinding values with rule id, severity, category, path, expected value, actual value, remediation, and planning key;
export deterministic metadata for reusable assets under definitions/**;
parse every canonical instruction through structured front matter before metadata checks;
validate canonical instruction budgets and required metadata;
expose a declarative context package manifest for runtime consumers;
validate declarative model-routing policy source path, schema version, lane identifiers, model hints, and intent partitions through model-routing.policy;
validate model-routing instruction-source applicability, provider transport/MCP/A2A boundaries, downstream ownership, and budget/cost/ prompt-compaction guardrails without executing runtime routing;
document the model-routing operator precedence chain in docs/operations/model-routing-operator-playbook.md;
validate provider routing catalog shape, deterministic routing prompt guardrails, active bootstrap route coverage, safe include paths, and declared deferred domain route ids without executing an LLM;
reject duplicate instruction ids and body-only metadata false positives;
reject duplicate .github/instructions/** source trees;
require source pointers, matching provider-output paths, and source coverage for provider projections;
catalog provider-owned prompts, policies, scripts, catalogs, and templates as provider assets until they are promoted to required projections;
validate provider hook selectors as selector-only metadata with no command, install, push, sync, promotion, build, test, or mutation fields;
validate README sections, order, contents links, path semantics, and local metadata leaks;
parse planning documents and generate UCP coordination pages from typed checklist-backed progress;
validate requirements, use case, architecture, UCP, and active planning traceability so behavior-changing plans link durable source documents;
generate planning status reports from active or completed planning documents, including pending checklist items, explicit stale cutoffs, missing progress metadata, active/completed folder status mismatches, and drift findings without using the current clock implicitly;
mine planning checklists for repeated scriptable work candidates and classify them as scriptable, partially scriptable, LLM-owned, external-owned, or manual-approval;
mine repeated work across active and completed planning folders through a reusable command surface without reparsing Markdown outside planning;
write sanitized scriptable-work dry-run reports under .deployment/artifacts/planning/scriptable-work for operator review;
validate repository-root contracts declared by docs through root.file-contracts, including root license, AGENTS.md, CHANGELOG.md, planning README, and declared governance instruction path availability;
validate the audit ledger through validation.audit-ledger, including stable rule ids, report schema markers, artifact writer outputs, planning projection shape, and required test evidence;
validate analyzer warning budgets through validation.warning-baseline, including baseline schema, scan-root safety, total warning budgets, and per-rule thresholds without running analyzers;
validate release governance through validation.release-governance, including required release-governance document headings, release checklist, changelog policy, semantic versioning policy, and tag policy without mutating GitHub or release assets;
validate C# style, XML docs, default-on existing regions, member order, async hygiene, placeholders, and file hygiene through isolated .NET style profiles for src and tests, exposed as focused deterministic functions for regions, ordering, XML docs, async hygiene, test naming, test regions, and Result<T> file naming;
validate Rust Cargo configuration, NetToolsKit package naming, .build/target output policy, source module layout, module docs, public and production item docs, inline tests, unsafe code policy, repository topology, and current repository smoke state through focused rust.crate-style functions;
validate the Rust command catalog that agents use to select approved format, build, test, lint, audit, hygiene, and release-readiness commands without guessing flags, working directories, or single-package versus workspace command profiles;
validate the Codex skill runtime profile contract so the default profile keeps one super-agent starter, bounded always-on skills, short routing reasons, disabled optional provider skills, and sanitized root labels;
inventory caller-supplied Codex skill roots without global runtime discovery, parse top-level name and description front matter, and report malformed, duplicate, empty, or sensitive skill metadata through sanitized findings;
write Codex skill runtime report artifacts under .deployment/artifacts/codex-skill-runtime/**, including the full JSON report, AI planning input, and Markdown pending checklist;
expose validation requests and specifications through a shared specification-driven contract that language-specific command aliases can normalize into, while command-surface validation requires implemented local validation commands to declare specification coverage or an explicit exemption;
expose generated-artifact hygiene through the artifacts.generated-hygiene specification so .gitignore, root artifact layout, artifact placement, and leak-scan findings stay deterministic without recursive scans of generated output folders;
validate governance catalog alignment so default profiles only reference implemented checks, validation commands declare lifecycle state, implemented commands map to manifest capabilities, and roadmap or external entries stay non-executable;
validate compatibility lifecycle semantics so active profiles stay executable while roadmap, external, future, and retired checks remain clearly separated;
validate Super Agent orchestration, permissions, skill profiles, and hook contracts so lifecycle order, approval boundaries, runtime skill budgets, and trim-only global hook policy remain deterministic;
validate PowerShell standards, shell hook policy, runtime script test evidence, and shared-script checksum manifest integrity, including includedRoots coverage, without executing scripts, hooks, or external scanners;
validate security baseline evidence, forbidden path patterns, secret-shaped content patterns, supply-chain baseline paths, dependency policy, and workspace-efficiency contracts as static instruction gates;
validate instruction governance so authoritative source maps, ownership manifests, quality ledgers, metadata envelopes, and architecture boundaries stay aligned with canonical definitions/** sources;
validate planning structure, active/completed plan status metadata, durable knowledge records, explicit warning baselines, changelog release policy, and release provenance evidence before PR or release closeout;
validate template standards and provider surface projection catalogs for JSON shape, unique ids, safe repository-relative paths, source availability, and regex syntax without treating legitimate template placeholders as drift;
validate root .gitignore artifact coverage, private path ignores, top-level generated folder drift, and caller-provided generated artifact paths, including validation profile checkOptions.candidatePaths consumed by validation-all, so outputs stay under .build/** or .deployment/artifacts/**, with opt-in text leak scans that do not recursively walk broad build or deployment folders by default;
render validation catalog alignment findings as a Markdown pending checklist for planning consumers;
render shared audit reports as sanitized Markdown pending checklists;
scan definition assets for local machine or secret metadata;
write optional audit artifacts only under .deployment/artifacts/audit/**;
use .deployment/artifacts/audit/latest as the default root for full repository audit report and planning input artifacts.

C# style validation keeps the regions group enabled by default because it is part of the canonical NetToolsKit C# layout. Missing region blocks are not findings, but existing regions are validated for balance, canonical names, location, spacing, and order. A caller can disable the group explicitly with --ignore regions; --region-policy forbid is reserved for repositories that want to reject every region directive.

C# style audit reports use concrete profiles such as dotnet-csharp-style/src and dotnet-csharp-style/tests. Each finding carries the resolved validationProfile, targetScope, and fileContext metadata so planning consumers can separate production fixes from test cleanup. Automatic profile selection rejects mixed src and tests targets unless the caller supplies an explicit --profile, and Markdown pending reports use a simplified planning checklist under ## Pending Fixes.

External C# smoke validation is opt-in and does not persist local paths. Set NTK_AGENT_DOTNET_STYLE_SMOKE_ROOT to a repository root before running the Rust test suite when a real workspace should be included in validation.

External Rust smoke validation is also opt-in. Set NTK_AGENT_RUST_CRATE_STYLE_SMOKE_ROOT to a repository root before running the Rust test suite when another Rust workspace should be included in validation. For a direct command-style run, execute:

cargo run -p nettoolskit-agent -- rust validate-crate --codebase . --report both --fail-on error

Use --codebase <path> to validate another Rust repository, such as ..\nettoolskit-rust. The command uses the same typed rust.crate-style validator as the test smoke path and writes optional JSON, planning input, and Markdown reports under the target repository's .deployment/artifacts tree.

Rust command recommendation is declarative and non-executing. The canonical catalog lives at definitions/templates/manifests/rust-command-catalog.catalog.json; it defines command ids, working directories, safety classes, approval requirements, artifact paths, and changed-path selection rules. Agents and downstream CLIs can load it to recommend commands such as cargo fmt --all --check, cargo test --all --all-targets, strict clippy validation, or git diff --check without treating the recommendation as permission to run publish, format-write, or destructive actions. Changed-path inputs must be repository-relative; absolute workstation paths, parent-directory escapes, and sensitive path-shaped values are dropped before a recommendation report is rendered.

The human-readable command and function catalog reference lives at docs/commands/README.md. The JSON catalogs remain authoritative, but that document summarizes command families, deterministic function mappings, instruction item coverage, ownership boundaries, safety rules, update workflow, and focused validation commands for agents and operators.

Codex skill runtime profiles are declarative and non-mutating. The canonical profile catalog lives at definitions/providers/codex/runtime/skill-runtime-profiles.json; it separates the default local Super Agent profile from optional provider, system, and plugin skills. Validation keeps super-agent as the only starter, enforces enabled skill and routing-description budgets, and rejects local path leaks in root labels. Policy notes in the same folder describe skill budget remediation, canonical starter ownership, and private MCP gateway route expectations. The inventory scanner accepts explicit repository-relative skill roots and does not discover local Codex homes by itself; reports use root labels instead of absolute workstation paths. Report artifacts are written only under .deployment/artifacts/codex-skill-runtime/**; the writer emits codex-skill-runtime-report.json, planning-input.json, and a planning-compatible Markdown pending checklist for operator review. Run cargo run -p nettoolskit-agent --example generate_codex_skill_runtime_report to generate the current non-versioned dry-run report from the repository-owned Codex skill definitions.

Scriptable work governance is canonicalized in definitions/instructions/governance/ntk-governance-scriptable-work/instructions.md. Agents should prefer deterministic repository-owned automation when inputs, outputs, write targets, and validation are stable, while keeping architecture decisions, final judgement, publish, merge, deploy, delete, and secret changes under LLM or operator control. When the Super Agent finds repeated work, it asks before creating automation unless the operator explicitly ordered it. Accepted automation starts as a normal planning/plans/active workstream, but the script itself belongs in the owning repository under scripts/automation/<category>/ and must be registered in that repository's local command, automation, capability, or service catalog before agents treat it as reusable. Run cargo run -p nettoolskit-agent --example generate_scriptable_work_report to generate the current non-versioned dry-run report under .deployment/artifacts/planning/scriptable-work/.

The executable-instruction foundation maps guidance to deterministic functions without making nettoolskit-agent a live model orchestrator. Function metadata lives in definitions/providers/github/governance/function-catalog.json; instruction bindings live in definitions/providers/github/governance/instruction-function-bindings.catalog.json. Rust contracts under crates/runtime/src/functions/** and crates/runtime/src/executable_instructions/** load, validate, and dry-run those catalogs so the Super Agent can decide when to call a validator, analyzer, formatter, script, CLI command, or generator before asking the LLM to reason about fallback or ambiguous work. The function execution contracts add typed request context, approval state, execution result, audit events, and a contract-only executor facade. That facade validates catalog data, parameters, context metadata, approval gates, and dry-run behavior, but it intentionally does not spawn processes, run scripts, call HTTP, push Git branches, or mutate files. Real adapter execution remains a downstream responsibility for nettoolskit-harness and nettoolskit-copilot. The function adapter handoff contracts package a validated execution request into service-neutral adapter references, public contract ids, artifact I/O references, idempotency metadata, approval state, and sanitized result correlation. The handoff is an auditable boundary artifact; it is not a local execution engine and does not create a Rust dependency on nettoolskit-harness. Function coverage is tracked through definitions/providers/github/governance/function-test-traceability.catalog.json. That matrix links each function to its instruction binding, linked command id, and required Rust test names. The Rust validator checks the matrix against the function catalog, binding catalog, command catalog, and real tests/**/*.rs test functions so coverage drift is caught deterministically. Instruction automation coverage is tracked separately through definitions/providers/github/governance/instruction-item-coverage.catalog.json. That matrix decomposes reviewed instructions into stable item ids before claiming automation coverage. Pending instructions stay explicitly marked as pending, so reports can show inventory coverage, covered item counts, linked command counts, and automation percentages without treating one function as coverage for an entire instruction file. Focused function ids should represent one rule whenever possible. The README instruction now has a curated 52-item inventory: 32 items are covered by deterministic function and Rust test evidence, 19 remain LLM-only semantic review items, and 1 remains manual-only. Covered README functions include root section inventory/order, root package-only section exclusion, Architecture placement after Contents, H1 title, section uniqueness, Architecture Mermaid diagram presence, Contents naming, H2 links, package README nested Usage Examples/API Reference links, root Crates workspace manifest checks, root Crates package README link checks, References real-link checks, Agentic Surfaces subsection evidence, root Agentic Surfaces boundary documentation, workflow Mermaid diagram usage, canonical README template source validation, package Usage Examples scenario numbering, package public enum value tables, package Data Shapes tables, Features checkmark bullets, License text, artifact path semantics, sensitive metadata, EOF blank-line hygiene, code-fence language tags, empty section stubs, and package README section order, root-only section exclusion, H2 heading-level checks, and house-style major section separators. The Rust instruction keeps the same non-executing crate-style command, but now exposes focused function mappings for package-name prefix, Cargo target output, module file resolution, module docs, public docs, production docs, inline source tests, tests/lib.rs exclusion, unsafe-code detection, and the operating-model guards for fake crates/* layouts and missing root src/lib.rs or src/main.rs entrypoints in single-crate repositories, plus literal multi-crate workspace members that must resolve under crates/<package> with a member manifest and source or test roots. Broader Rust performance and architecture judgment remains outside the deterministic coverage claim until it has focused validators and tests. Context Economy coverage is now backed by ntk validation context-package for static checkpoint-template, root command-reference, context-package source, planning-continuity, memory model, operating modes, compression triggers, preserve/discard rules, checkpoint triggers, priority order, payload-template ownership, and cross-instruction ownership contracts. These checks prove the repository preserves the canonical source contract; live decisions about when to compress, when to show a checkpoint, and how to interpret an active conversation remain runtime LLM behavior and are not claimed as live execution proof. Brainstorm Spec Workflow coverage is now backed by ntk validation spec-workflow for active spec metadata, required design sections, timestamped key decisions, concrete acceptance evidence, broad-work design slice matrices, active related-plan linkage, completed archive hygiene, canonical instruction detail contracts, stable active spec names, one active spec per workstream, planning-readiness update timestamps, spec-plan responsibility boundaries, deterministic command evidence, temporary fixture locality, and plan-only skip reasons. The same command also exposes focused source-contract functions for spec-before-plan intent, versioned design context, spec-to-plan granularity, mandatory and skip triggers, required spec content, pillar mapping, performance concerns, acceptance quality, rejected alternatives, plan/spec responsibility, multi-spec milestones, and plan consumption of ready specs. Semantic decisions about whether a task truly needs a spec for a specific ambiguous request, how to judge alternatives, or whether pillar details are sufficient remain LLM-owned. Backend Architecture Core coverage is now backed by ntk validation backend-architecture-core for observable backend architecture artifacts: architecture evidence, C# project-reference direction, domain framework isolation, presentation-to-infrastructure boundary drift, application workflow shape, narrow interface boundaries, module ownership smells, correlated domain/application/infrastructure test evidence, infrastructure business-policy ownership, mutable value objects, domain authorization coupling, validation-after-side-effect ordering, unversioned presentation contracts, and generic failure contracts. The same profile now also checks collection and error contract consistency, outbox-style messaging reliability, event-consumer idempotency and failure-handling evidence, external I/O resilience controls, service-boundary security, backend observability evidence, reproducible delivery pinning, and staged schema rollout controls. Architectural fit, business-policy modeling quality, versionable contract design quality, resilience semantics, and other product-specific design judgments remain LLM or reviewer owned until they have narrower validators and tests. Backend Integration And API Testing coverage is now backed by ntk validation backend-integration-testing for observable .NET backend integration-test artifacts: xUnit/NUnit framework evidence, Testcontainers or dependency harness evidence, WebApplicationFactory/TestServer API host evidence, browser E2E boundary drift, load/performance/security suite tagging, deterministic fixture hygiene, secret-like test material, backend test matrices, affected-shard CI selection, API contract evidence, deterministic test data, negative security scenarios, resilience behavior, CI diagnostics, and security evidence classification. It also validates domain unit-test evidence, isolated-logic expensive-suite gates, DAST/API abuse gates, load-suite trigger gates, justified performance assertions, PR smoke versus full-gate policy, source contracts for real public behavior and seam coverage, and OWASP reference mapping for security-sensitive evidence. Backend Integration now maps 40 of 48 instruction items. Applicability/routing decisions, browser delegation judgment, live gate approval, measured performance evidence, and environment readiness remain LLM, reviewer, CI, or operator owned. Persistence And ORM coverage is now backed by ntk validation persistence-orm for observable .NET persistence artifacts: domain isolation from persistence annotations and DbContext concerns, centralized mapping visibility, lazy-loading drift, repository and unit-of-work boundary drift, read-model projection and pagination evidence, connection-string secret hygiene, persistence observability tokens, canonical routing source contracts, soft-delete requirement evidence, and batch/bulk invariant and transaction semantics. It now maps 21 of 23 instruction items. Keyset pagination fit, least-privilege role proof, data-model correctness, and live database behavior remain LLM, reviewer, or environment-owned. Database Configuration coverage is now backed by ntk validation database configuration-operations for repository-owned database configuration guidance: externalized settings, typed configuration contracts, stable keys, hardcoded secret prohibition, managed secret-store guidance, TLS and certificate validation, connection metadata, credential separation, provider baselines, and pooling/timeout policy. It also protects source contracts for instruction scope, schema/query routing, ORM routing, quality principles, retry jitter, read-replica lag tolerance, expand/migrate/contract, destructive schema rollout, cross-tenant export authorization, and zero-downtime migration checklist guidance. It now maps 48 of 57 instruction items. It validates static instruction contracts only; live database connectivity, secret-store access, rotation evidence, migration execution, failover, load tests, backup/restore, RTO/RPO, dashboards, and environment readiness remain downstream runtime or operator concerns. Database Schema And Query coverage is now backed by ntk validation database-schema-query for repository-owned database schema and query guidance: scope, database-configuration routing, ORM routing, security routing, deterministic English naming, convention consistency, explicit keys and referential integrity, read/write model evidence, broad-scan guards, SARGable predicate shape, transaction boundaries, forward-only or reentrant migrations, precise storage types, timezone semantics, and runtime policy boundaries. It now maps 15 of 36 instruction items. It validates static artifacts and committed instruction contracts only; live database connectivity, migration execution, query plans, package managers, containers, networks, workload proof, indexing fit, and external services remain downstream runtime, LLM, reviewer, or operator concerns. Data Privacy And Compliance coverage is now backed by ntk validation data-privacy-compliance for repository-owned privacy governance, data classification, pseudonymization/tokenization, legal basis, consent lifecycle, least-privilege access, tenant scoping, encryption, masking/redaction, error/debug leakage, retention, subject-rights requests, secure exports, release readiness, and automated privacy test evidence. It validates static repository artifacts only; privacy platforms, identity providers, databases, ticketing systems, cloud services, scanners, and external compliance evidence stores remain downstream runtime or operator concerns. This slice raises covered instruction items to 1175 and reduces global deterministic candidates to 53. VS Code Workspace Efficiency coverage now also validates source-of-truth, runtime sync command, pseudo-inheritance, discovery-root, layout-policy, and edit-payload normalization contracts through ntk validation workspace-efficiency. It validates committed baselines, command catalog evidence, and workspace files only; live VS Code windows, user profile state, and sync execution remain downstream runtime or operator concerns. This slice raises covered instruction items to 1191 and reduces global deterministic candidates to 37 while reducing VS Code deterministic candidates to zero. Kubernetes coverage is now backed by ntk validation k8s-manifests for repository-owned Kubernetes and Helm-style manifest evidence: instruction routing boundaries, least-privilege workload policy, service accounts and RBAC, non-root/read-only security posture, namespace and network isolation, secret projection design, resource requests and limits, policy objects, scheduling topology, probes, graceful termination, rollout semantics, ConfigMap/Secret separation, traffic exposure, TLS/host routing, NetworkPolicy evidence, storage assumptions, autoscaling justification, rollout/rollback policy, kubectl troubleshooting surfaces, manifest correctness, and cluster constraint release evidence. It validates static repository artifacts only; kubectl, Helm execution, Docker execution, cluster API calls, cloud CLIs, admission controllers, network checks, and live deployment mutation remain downstream runtime or operator concerns. This slice raises covered instruction items to 1228 and reduces global deterministic candidates to zero. Context Economy source-contract hardening now extends ntk validation context-package across memory model, operating modes, compression triggers, preserve/discard rules, checkpoint triggers, priority order, template ownership, and cross-instruction ownership references. The validator proves canonical repository artifacts preserve those contracts; live LLM session decisions remain outside deterministic execution claims. This slice raises covered instruction items to 1267 while keeping global deterministic candidates at zero. Prompt Template quality coverage now extends ntk validation template-standards with source-contract checks for input/context separation, target-user markers, measurable acceptance criteria, stable output format contracts, conditional tool/source/refusal requirements, security/privacy/source attribution, and the existing single-objective anti-pattern guard. This slice raises covered instruction items to 1274 and Prompt Templates coverage to 27 of 30 items while keeping prompt semantic usefulness and live provider behavior outside deterministic execution claims. Agentic Surfaces definition coverage now extends ntk validation agent-runtime-boundary with source-contract checks for MCP, RAG, CAG, A2A, tool projection, retrieval/compaction separation, lane-default metadata, and extension-class boundaries. This slice raises covered instruction items to 1286 and Agentic Surfaces coverage to 45 of 62 items while keeping live RAG/CAG/A2A/MCP execution and provider behavior outside deterministic execution claims. Agent Model Routing coverage now extends ntk validation model-routing-policies with source-contract checks for applicability, provider transport/MCP/A2A boundaries, downstream orchestrator ownership, budget/cost/prompt-compaction guardrails, internal routing versus A2A terminology, and policy-guidance-only runtime boundaries. This slice raises covered instruction items to 1292 and Agent Model Routing coverage to 23 of 23 items while keeping live provider calls and runtime model selection downstream. Sub-Agent Planning Workflow coverage now extends ntk validation planning-structure with source-contract checks for lifecycle order, type-first SDD layout, dated progress, active-plan reuse, slice decomposition, required slice shape, sub-slice matrix, pillar checks, worktree isolation, and closeout/archive gating. This slice raises curated instruction items to 1767 and covered instruction items to 1302 while keeping live subagent execution outside deterministic execution claims. Copilot Instruction Creation coverage now extends ntk validation instruction-metadata and ntk validation instruction-architecture with source-contract checks for semantic guidance ownership, provider semantic surface rendering, body focus, Markdown scanning, mandatory quality pillars, Standardization/Security/Performance signals, concise pillar coverage, quality-gate states, and pillar-validation finding evidence. This slice raises covered instruction items to 1317 and Copilot Instruction Creation coverage to 55 of 55 items while keeping semantic review and provider generation outside deterministic execution claims. README source-contract coverage now extends ntk validation readme-standards with canonical README instruction checks for direct-assembly prohibition, repository focus, reference scope, runtime/provider topic ownership, concise package canonical-doc links, logical API grouping, concise entrypoint context, single canonical destinations, Introduction quality, Architecture source-alignment, runtime/provider subsections, real setup/build/example/API guidance, concise actionable formatting, and template-owned placeholders. This slice raises covered instruction items to 1336 and README coverage to 51 of 52 items while keeping public API importance coverage manual-only. Backend Architecture Core source-contract coverage now extends ntk validation backend-architecture-core with canonical instruction checks for cross-language applicability, stack-specific routing, normative boundary precedence, template/scaffold ownership, domain/use-case/SOLID/domain-modeling rules, transaction and DTO boundaries, thin orchestration, anti-corruption layers, critical external tests, event separation, graceful degradation, persistence boundaries, data read/write alignment, and architecture anti-patterns. This slice raises covered instruction items to 1363 and Backend Architecture Core coverage to 57 of 57 items while keeping live architecture judgment outside the deterministic claim. Brainstorm Spec Workflow source-contract coverage now extends ntk validation spec-workflow with 28 focused functions for the remaining explicit governance source rules around spec-before-plan intent, versioned design context, mandatory and skip triggers, required spec content, pillar mapping, performance concerns, acceptance quality, rejected alternatives, plan/spec responsibility, multi-spec milestones, and plan consumption of ready specs. This slice raises covered instruction items to 1391 and Brainstorm Spec Workflow coverage to 63 of 65 items while keeping the 2 material-completion judgment rules manual-only. Agentic Surfaces source-contract coverage now extends ntk validation agent-runtime-boundary with 17 focused functions for separated A2A, MCP, RAG, CAG, HyDE, and runtime guidance, vague AI-layer prevention, maintenance boundaries, RAG indexing/retrieval/recall, CAG prompt assembly/compaction/token pruning, A2A capability/identity/task/protocol definitions, internal orchestration until real protocol support, and operational memory as an editorial layer. This slice raises covered instruction items to 1408 and Agentic Surfaces coverage to 62 of 62 items while keeping runtime RAG/CAG/HyDE/A2A execution downstream. Prompt Templates source-contract completion now extends ntk validation template-standards with focused functions for bounded visible reasoning or evidence requests and conservative POML authoring when prompt assets require reusable structure, fixtures, external inputs, or provider-independent rendering. This slice raises covered instruction items to 1410 and Prompt Templates coverage to 29 of 30 items while keeping prompt behavior CHANGELOG impact manual-only. Authoritative Sources source-contract coverage now extends ntk validation authoritative-source-policy with focused functions for lookup order, official documentation, maintainer and community fallback, required external lookup triggers, narrowest stack selection, response source-type wording, conflict-resolution rules, high-risk authoritative-doc-over-memory guidance, and insufficient-docs disclosure. This slice raises covered instruction items to 1425 and Authoritative Sources coverage to 17 of 17 items while keeping live browsing, source adequacy, and final-answer source attribution behavior downstream. Feedback/Changelog source-contract coverage now extends ntk validation release-governance with focused functions for canonical release-communication ownership, PR goals, title style, security and performance checklist guidance, namespace and generated-file consistency, discussion focus, material evidence attachment, consolidated feedback history, changelog-template provenance, SemVer impact classes, and discontinuation timelines. This slice raises covered instruction items to 1437 and Feedback/Changelog coverage to 28 of 33 items while keeping live CI evidence, formatter evidence, reviewer assignment, issue triage, and issue-to-tag release workflow evidence manual-only. Observability/SRE coverage is now backed by ntk validation observability-sre for SLOs, telemetry design, metrics quality, alerting, dashboards, runbooks, health probes, incident operations, telemetry security, release verification, and runtime diagnostics taxonomy alignment. It validates repository-owned instruction and taxonomy contracts only; live telemetry backends, dashboards, synthetics, alert delivery, and incident systems remain downstream runtime or operator concerns. Platform Reliability and Resilience coverage is now backed by ntk validation platform reliability-resilience for static reliability and continuity guidance: scope ownership, Observability/SRE routing boundaries, graceful degradation, reliability targets, error-budget prioritization, recovery objectives, timeout budgets, bounded jittered retries, dependency isolation, backpressure/load-shedding, idempotency, fallbacks, core-journey degradation, degraded-mode indicators, load headroom, autoscaling safeguards, async pipeline capacity, controlled chaos guidance, blast-radius control, chaos backlog actions, measurable chaos hypotheses, RTO/RPO, restore/failover/rollback testing, runbook validation, dependency maps, progressive delivery, rollback signal gates, automated rollback, incident command readiness, corrective evidence, and recurring-failure elimination. It validates instruction drift only; live chaos experiments, deployment execution, failover testing, backups, incident APIs, and production probes remain downstream runtime or operator concerns. The same item-level model now covers the repository planning taxonomy through ntk.validation.planning-structure, repository generated/transient artifact placement through ntk.validation.generated-artifact-hygiene, and thirty-six focused PowerShell rules: ntk.validation.powershell.error-action-stop, ntk.validation.powershell.strict-mode-latest, ntk.validation.powershell.comment-help-sections, ntk.validation.powershell.param-block-top, ntk.validation.powershell.approved-verbs, ntk.validation.powershell.no-broad-recurse, ntk.validation.powershell.exit-codes, ntk.validation.powershell.no-recursive-force-delete, ntk.validation.powershell.no-silent-catch, ntk.validation.powershell.safe-silentlycontinue, ntk.validation.powershell.literal-path, ntk.validation.powershell.no-hardcoded-absolute-paths, ntk.validation.powershell.no-shell-shortcuts, ntk.validation.powershell.logging-verbose-mode, ntk.validation.powershell.no-secret-logging, ntk.validation.powershell.no-dynamic-execution, ntk.validation.powershell.template-source, ntk.validation.powershell.ai-generation-prompt, ntk.validation.powershell.sections-layout, ntk.validation.powershell.focused-functions, ntk.validation.powershell.explicit-parameters, ntk.validation.powershell.utf8-eof-policy, ntk.validation.powershell.root-no-cwd-assumption, ntk.validation.powershell.root-detect-validate, ntk.validation.powershell.root-shared-helper, ntk.validation.powershell.root-test-resolve-before-cd, ntk.validation.powershell.root-bounded-discovery, ntk.validation.powershell.path-join-path, ntk.validation.powershell.path-validate-before-mutation, and ntk.validation.powershell.path-repo-relative-after-root, ntk.validation.powershell.runtime-error-details, ntk.validation.powershell.mutation-safety-details, ntk.validation.powershell.logging-diagnostics-details, ntk.validation.powershell.compatibility-runtime-details, ntk.validation.powershell.performance-cache-lookups, and ntk.validation.powershell.security-runtime-details. The ntk.validation.powershell.no-broad-recurse coverage also backs the known-layout search-scope item by requiring scoped recursive paths or early filters before enumeration. The ntk.validation.powershell.exit-codes rule requires a deterministic non-zero failure exit path while allowing normal PowerShell fall-through or explicit exit 0 for success. The validation-powershell-standards authoring and path-detail coverage also preserves the canonical guidance that PowerShell scripts must start from the shared template/prompt, keep authoring structure and file hygiene explicit, not assume the caller starts at the repository root, detect and validate that root before repo-relative operations, and build paths with Join-Path. The same PowerShell standards validator now preserves safety-runtime guidance for meaningful failure handling, destructive-mutation safeguards, deterministic operator output, compatibility notes, repeated lookup caching, and least-privilege security guidance. Scriptable-work governance also reuses ntk.planning.scriptable-work-mine for testable repeated-work classification from planning sources, plus ntk.validation.generated-artifact-hygiene for generated evidence that must stay sanitized and repository-relative, and ntk.validation.script-automation-contract for reusable script placement, metadata, catalog registration, README discoverability, validation-command declarations, validation-evidence correlation, and unsupported-file findings under scripts/automation. Focused Scriptable Work functions now classify stable file, manifest, Git metadata, command-output, and planning inputs; stable JSON, Markdown, checklist, schema, catalog, manifest, and report outputs; safe read-only, generated, dry-run, and explicitly approved write scopes; and approval-gated publish, push, merge, tag, deploy, delete, secret, and runtime mutation work. The script automation contract also validates repository-relative maintenance script input scope, explicit dry-run mechanisms, and unsupported-file rejection. Repository-validator-first telemetry, active-plan correlation, and plan closeout validation remain candidates. The same generated-artifact hygiene validator also covers focused artifact-layout items for .build transient outputs, .deployment/artifacts namespace enforcement, canonical .gitignore roots, private path ignores, and ad-hoc top-level artifact folder drift. It also validates root .gitignore baseline sections and generated provider/runtime ignores, plus explicit first-level namespaces below .build and .deployment, and explicit .NET build or publish output paths when a repository has .NET project signals. Repository Operating Model focused functions reuse that validator for .build transient-output evidence and no-secret/local-state hygiene so repository governance can be routed to deterministic checks before manual review. The same operating-model closeout path also reuses the Git PR changelog validator for changed-path inputs that require release or governance history. Canonical instruction source placement is routed through instruction metadata validation so authored instruction files stay under definitions/instructions. Definitions-owned canonical asset placement is routed through instruction architecture validation, and commit closeout text is routed through validation-git-commit-message. The same boundary validator also backs ntk.validation.repository.agent-guidance-only, proving static Operating Model text keeps nettoolskit-agent limited to guidance, contracts, governance catalogs, and static audits. Repository Operating Model source-contract functions also validate committed source ownership, Copilot/Control/DevOps/Harness boundaries, non-trivial Super Agent planning, bug-ledger separation, durable knowledge traceability, domain routing, README/knowledge closeout, and local/commit/push/PR/CI/merge state transparency through validation-release-governance. The ntk.runtime.scaffold-workstream generator renders or creates the canonical active plan/spec pair from repository templates with dry-run-first behavior, safe lower-kebab identifiers, explicit timestamp prefixes, and create-new writes that avoid overwriting existing planning files. Release sanitization reuses the same validator for selected artifact candidates that must block high-confidence credentials, private keys, local paths, provider tokens, environment values, and operator or machine identifiers, including a focused personal operator and machine identifier function. CI/CD stage-policy coverage now maps vague workflow job-name rejection, explicit stage ordering, release/deploy validation gates, canonical stage taxonomy, single-responsibility boundaries, package/runtime separation, release gate evidence, deploy approval controls, verify-after-deploy health evidence, security failure gates, stage evidence output, secret evidence guards, expensive-stage controls, validation-side-effect rejection, documentation release gates, and performance release gates through focused ntk.validation.cicd.* functions backed by validation-cicd-stage-policy. Machine-readable evidence format guidance is now also covered through ntk.validation.cicd.machine-readable-evidence-formats, which validates the retained source contract for JSON, SARIF, JUnit, SBOM, manifest, and release-gate report guidance without executing CI or reading live artifacts. VS Code workspace-efficiency coverage now maps static baseline checks for Git throttles, parent repository discovery, extension defaults, Copilot next-edit pressure, conservative SCM visibility, startup editor posture, and Explorer/search/watcher exclusions through focused ntk.validation.vscode.* functions. The generated-output exclusion function now includes direct evidence for required build-output watcher exclusions in the committed baseline. Required Explorer, watcher, and search exclude coverage is also exposed as a focused function for effective-settings and checklist routing while staying limited to committed baseline declarations. Duplicate exclusion-key coverage now rejects repeated baseline requiredKeys after /** normalization; live workspace merge semantics remain downstream. The baseline also rejects window.restoreWindows in workspace scopes so window restore behavior stays owned by user/global VS Code settings. Effective/checklist throttle coverage now also maps the committed Git autofetch and parent-folder discovery declarations through existing focused validators without inspecting live VS Code settings. Git workflow coverage now maps release-policy checks for the changelog [Unreleased] section, Semantic Versioning release headings, and documented vMAJOR.MINOR.PATCH tag format through focused ntk.validation.git-workflow.* functions backed by validation-release-governance. Feedback/changelog hygiene also maps CHANGELOG EOF blank-line validation and Semantic Versioning release heading dates through ntk.validation.feedback-changelog.changelog-eof-hygiene and ntk.validation.feedback-changelog.version-date-heading, and maps canonical feedback issue context, problem, solution, and impact fields through ntk.validation.feedback-changelog.issue-context-problem-solution plus feedback tracking table columns through ntk.validation.feedback-changelog.feedback-tracking-columns. Pull request template governance now maps title shape, description section order, Applied Instructions, EOF checklist, and label metadata guidance through focused ntk.validation.feedback-changelog.pr-* functions backed by validation-template-standards. Instruction ownership now also maps the no-separate-PR-only release communication rule through ntk.validation.feedback-changelog.no-separate-pr-only-instruction backed by validation-catalog-alignment. Breaking change communication now maps explicit breaking CHANGELOG entries to README migration, upgrade, compatibility, or rollback guidance through ntk.validation.feedback-changelog.breaking-readme-migration backed by validation-release-governance. Feedback/Changelog source contracts now also map canonical release-communication ownership, PR goals, title style, security/performance checklist guidance, namespace and generated-file consistency, discussion focus, material evidence attachment, consolidated feedback history, changelog-template provenance, SemVer impact classes, and discontinuation timeline guidance through focused ntk.validation.feedback-changelog.* functions backed by validation-release-governance, raising Feedback/Changelog coverage to 28 of 33 items while leaving live CI, reviewer, issue, and release workflow evidence manual-only. Git branch-name coverage now also maps approved semantic prefixes, lower-kebab-case suffixes, and release/<version> branch targets through ntk.validation.git-workflow.branch-name backed by validation-git-branch-name. It now also covers static rejection of protected main publication branches, semantic branch evidence before publishable work, and explicit PR changed-path changelog evidence through ntk.validation.git-workflow.changelog-pr-required backed by validation-git-pr-changelog. Semantic commit-message coverage now maps type, optional scope, subject length, low-signal summary, past-tense, and sensitive metadata checks through ntk.validation.git-workflow.commit-message backed by validation-git-commit-message. PR approval, live branch protection, and tag timing remain manual or candidate items because they require live Git/GitHub state and operator approval. CI/CD Rust local gate coverage now maps rustfmt, stable test, and Clippy command-profile evidence through ntk.validation.cicd.rust-local-gates backed by validation-rust-command-catalog. CI/CD DevOps remote-proof ownership, runner budget, trigger scope, and fail-fast dependency boundaries are now covered by validation-cicd-devops; live CI execution and operator release approval remain outside static validation. CI/CD matrix fail-fast coverage now maps the expensive-matrix evidence rule through ntk.validation.cicd.matrix-fail-fast-evidence backed by validation-cicd-stage-policy. This proves static fail-fast: false evidence markers only; real runner-cost proof remains outside the static validator. CI/CD stable job-name coverage now maps vague workflow job ids through ntk.validation.cicd.no-vague-job-names backed by validation-cicd-stage-policy. This proves static job-id quality only; live branch protection configuration remains outside the validator. CI/CD explicit stage-concern coverage now maps package, release, deploy, and verify stage dependency rules through ntk.validation.cicd.stage-explicit-needs and ntk.validation.cicd.validation-before-mutation backed by validation-cicd-stage-policy. This proves static dependency and mutation-order evidence only; full pipeline architecture remains an LLM or review concern. The same stage dependency evidence backs the failed-stage blocking rule by requiring downstream package, release, deploy, and verify jobs to declare explicit needs dependencies. CI/CD stage-policy completion now also maps the canonical instruction applicability rule through ntk.validation.cicd.stage-instruction-applicability backed by validation-cicd-stage-policy, plus CI/CD workflow/governance changelog-impact evidence through ntk.validation.cicd.stage-changelog-impact backed by validation-git-pr-changelog. This closes the deterministic candidates for ntk-governance-ci-cd-stages; machine-readable evidence format guidance is now static source-contract coverage and external dashboard proof remains manual-only. Repository boundary coverage now maps the nettoolskit-rust generic foundation ownership rule through ntk.validation.repository.rust-foundation-boundary backed by validation-agent-runtime-boundary. This is static instruction text validation only; external crate and product DTO scans remain separate. Agentic surface Rust foundation coverage now reuses the same boundary function for the agentic ownership item that keeps reusable Rust foundation primitives product-neutral. This remains static instruction-boundary validation; runtime or external repository behavior stays downstream. Repository deployment artifact coverage now maps the operating-model rule that .deployment is non-versioned output and .deployment/artifacts stores validation artifacts through generated artifact hygiene functions. This proves path namespace and ignore-root evidence only, not semantic release-output classification. Deployment Cargo target coverage now maps the deployment artifact rule that Cargo output stays under .build/target through ntk.validation.deployments.cargo-target-dir backed by validation-rust-crate-style. Deployment Topology coverage is now backed by ntk validation deployments-topology for observable deployment topology contracts: instruction entrypoint scope, Docker/Kubernetes/CI routing boundaries, approved deployment/ top-level paths, reusable shared proxy and persistence placement, package/install wrapper source under deployment/wrappers/{ecosystem}/{package}/, placeholder-safe deployment filenames, root-owned .deployment guidance, nested .deployment rejection, root target/ drift after .cargo/config.toml points to .build/target, and command catalog implementation evidence. Docker Compose rendering, live Portainer/Dokploy, Kubernetes manifests, and server deployment behavior remain downstream runtime/operator concerns until narrower validators exist. Agentic surface token coverage now maps README Agentic Surfaces evidence and domain ARCHITECTURE.md Agentic Surfaces sections through ntk.validation.readme.agentic-surfaces-subsection and ntk.validation.requirements.architecture-agentic-surfaces. These validators check section presence and detected token naming only; runtime protocol support, memory execution, and semantic architecture correctness remain downstream or LLM-review concerns. Agentic Surfaces boundary coverage now adds focused ntk.validation.agentic-surface.* functions backed by validation-agent-runtime-boundary. They validate canonical ownership, separation, repository mapping, documentation subsection, and forbidden-claim rules for MCP, RAG, CAG, HyDE, A2A, internal runtime, model routing, provider matrices, extension taxonomy, operational memory, and Harness boundaries without making this repository a live runtime executor. VS Code workspace-efficiency coverage also includes ntk.validation.vscode.chat-maxrequests-bound, which enforces the committed baseline upper bound for chat.agent.maxRequests; live VS Code user/workspace settings inspection remains outside this static Agent-owned validator. It also includes ntk.validation.vscode.chat-empty-history-disabled, which keeps the committed baseline aligned with the provider template by requiring chat.emptyState.history.enabled = false without inspecting live VS Code settings. The same baseline validator now proves the approved local override allowances for git.autorefresh and chat.agent.maxRequests; generated workspace synthesis and live effective settings checks remain downstream concerns. It also rejects unapproved workspace-local override allowances in the committed baseline so the checklist can stay deterministic without inspecting live VS Code windows. That same override allow-list now backs focused coverage for avoiding unrelated global setting copies and global default restatement in workspace scope. It also proves the committed baseline declares the supported .code-workspace glob and .vscode/base.code-workspace shared template path; actual workspace generation and pseudo-inheritance merge behavior stay outside this static validator. Chat continuity coverage now also validates chat.restoreLastPanelSession = false, and the global throttle template item is backed by the existing focused Git, SCM, extension, parent-repository, and Copilot throttle validators. The ESLint, Copilot reviewSelection, and formatter trigger posture is now represented in the committed workspace-efficiency baseline and backed by focused validators for problems-only ESLint code actions, disabled noisy ESLint actions, disabled reviewSelection, and disabled format triggers. Workspace layout heuristic coverage now also validates the committed folder-count warning threshold, multiple product folder warning, support-folder mix warning, and shared support-folder pattern inventory. These checks remain static baseline validation only; live VS Code windows and operator justification evidence stay downstream. It also rejects .github subfolder discovery patterns in the committed support folder inventory to prevent duplicated instruction roots. Committed .code-workspace files are now validated directly for folder-count pressure and multi-root git.autorefresh posture. Single-root workspaces may inherit global autorefresh settings, while multi-root workspaces must set the local override to false. The workspace-efficiency validator now also enforces minimal committed workspace-local settings, rejects product workspaces that mix shared AI runtime support folders, and validates formatter policy for no Prettier shared default, protected language defaults, no-final-newline EOF compatibility, and disabled language-scoped format-on-save. This raises VS Code deterministic coverage to 57/16 while staying limited to committed baselines and workspace files. The same validator now also covers the remaining VS Code source-of-truth, runtime command, pseudo-inheritance, global discovery, layout policy, duplicate repository-window policy, and edit-payload normalization items. This raises VS Code deterministic coverage to 73/0; live VS Code window inspection, user profile inspection, and runtime sync execution remain outside this static Agent-owned validator. The current deterministic candidate backlog is zero. The historical scored backlog remains in docs/knowledge-base/references/instruction-automation-candidates.md for auditability and future re-scoring if new instruction items are added. Authoritative source governance maps the canonical source-map rule through ntk.validation.authoritative-sources.map-single-source, backed by validation-authoritative-source-policy. The same policy validator now also backs ntk.validation.authoritative-sources.no-domain-list-duplication, which rejects copied official domains in unrelated canonical instruction files. Metadata envelope governance maps canonical instruction scope, bounded front matter, required shared fields, required applyTo and priority routing metadata, fixed scalar defaults, and classification-path alignment through focused ntk.validation.metadata-envelope.* functions backed by validation-instruction-metadata. It also keeps template payloads outside the canonical instruction metadata contract, routes template machine-readable manifest files through definitions/templates/manifests, enforces required pillar tags, and rejects a separate quality_pillars field. The same validator now rejects unknown top-level metadata keys while allowing the approved operational keys owner, status, and provider_surface. Source-contract checks now preserve semantic signal guidance, routing metadata intent, template policy boundaries, title and summary quality, taxonomy alignment, stable alias usage, and pillar remediation guidance. Provider projection exemption, stable id history, and starter-template provenance remain manual governance evidence. Copilot instruction creation now rejects generic pillar padding in keywords and graph_topics, validates source contracts for body focus and quality pillar signals, and lets Git PR validation require a durable knowledge record path when a change is classified with required knowledge impact. Full semantic review and provider generation stay outside these deterministic checks.

The service manifest exposes these audit and validation surfaces as discoverable capabilities. It does not expose model-routing decisions, tool-invocation results, machine commands, shell commands, or promotion apply execution.

Promotion readiness is also local-first and read-only:

resolve source-to-destination runtime assets from the provider runtime surface manifest;
verify every source exists before promotion;
reject unsafe absolute or upward-escaping destination paths;
verify required provider runtime destinations have mapped assets;
keep provider bootstrap routing small and product-agnostic.

Promotion staging is repository-local:

run readiness gates before copying any promotion asset;
copy only declared provider runtime manifest assets;
preserve runtime-relative destination paths inside .deployment/artifacts;
reject staging roots outside .deployment/artifacts;
never write to the installed global runtime.

The service manifest exposes promotion readiness inspection, repository-local staging, and read-only runtime verification. Runtime asset promotion apply remains an explicit Rust API and is not advertised as a public discovery capability. It copies versioned provider assets into caller-injected runtime roots; it is not live task orchestration, model selection, retrieval execution, machine command execution, deployment, or product workflow composition.

Global apply planning remains dry-run:

consume an existing staged promotion bundle;
map staged assets to caller-injected runtime roots;
plan backup paths under .deployment/artifacts;
emit smoke checks for file presence, manifest semantic markers, Super Agent bootstrap, and routing catalog limits;
never mutate the installed global runtime.

Explicit runtime asset promotion apply is opt-in:

consume a previously built dry-run apply plan;
revalidate public plan paths before any runtime asset writes;
require exact one-to-one matching between runtime asset writes and backup entries;
preflight all staged files before backups or runtime asset writes;
back up runtime files that exist at apply time before overwrite;
copy staged assets only into the caller-injected runtime root;
evaluate smoke checks after copy;
reject unbacked overwrites if a destination appears after backup inspection;
return rollback readiness and smoke failure evidence without automatic rollback or installed runtime discovery.

The repository also exposes a dry-run-first operator example for local promotion workflows when the durable ntk CLI is unavailable:

cargo run -p nettoolskit-agent --example promote_super_agent_runtime -- --runtime-root <runtime-root>
cargo run -p nettoolskit-agent --example promote_super_agent_runtime -- --runtime-root <runtime-root> --apply

The first command stages the current bundle and builds an apply plan without runtime asset writes. The second command performs the explicit asset apply, creates repository-local backups under .deployment/artifacts, and runs smoke checks. The example never discovers %USERPROFILE%, $HOME, .codex, or .agents implicitly; the operator must pass the intended runtime root.

Runtime verification is also explicit and read-only:

cargo run -p nettoolskit-agent --example verify_super_agent_runtime -- --runtime-root <runtime-root>

The command compares promoted runtime files with the repository source tree and reports missing or mismatched promotion assets without staging, backups, apply execution, or runtime discovery.

Promotion staging and verification use the same provider runtime surface manifest as the npm installer, so .github root files, the .agents/skills shared skill directory, .claude/skills, .claude/settings.json, .github/chatmodes, .github/prompts, .codex/skills, .codex/mcp, .codex/orchestration, opt-in VS Code runtime assets, and mirror runtime destinations are described by one manifest flow. The npm default package profile excludes VS Code user files unless a future package profile explicitly includes them.

The provider runtime install is global to the selected operator runtime root. It installs agents, skills, hooks, commands, prompts, and provider settings for the operator. Downstream repositories should not receive copied global definitions or provider runtime folders; they should expose a concise provider-neutral local adapter through AGENTS.md, with provider-specific files only as optional bridges.

Provider runtime surface verification uses the shared manifest and can inspect GitHub/Copilot, Codex, Claude, and mirror profiles without writing files:

ntk runtime provider-surfaces verify --repo-root . --runtime-root $env:USERPROFILE --profile github
ntk runtime provider-surfaces manifest --repo-root . --profile codex
ntk runtime provider-surfaces plan --repo-root . --runtime-root $env:USERPROFILE --profile all
ntk runtime provider-surfaces doctor --repo-root . --runtime-root $env:USERPROFILE --profile all
ntk runtime provider-surfaces healthcheck --repo-root . --runtime-root $env:USERPROFILE --profile all
ntk runtime provider-surfaces report --repo-root . --runtime-root $env:USERPROFILE --profile all
ntk runtime provider-surfaces parity --repo-root . --previous-root <previous-runtime-root>
ntk runtime provider-surfaces apply --repo-root . --runtime-root $env:USERPROFILE --profile all --yes

Session housekeeping is dry-run-first. It inventories provider session folders, exports a sanitized planning summary when requested, and reports whether a later guarded cleanup apply would be allowed. Apply mode only removes preflight-approved closed candidates after planning summary export, persisted evidence, and matching provider confirmation. Add --write-evidence to dry-run or preflight to persist sanitized Markdown and JSON evidence under .deployment/artifacts/runtime/session-cleanup/latest:

ntk runtime session-housekeeping dry-run --runtime-root $env:USERPROFILE --provider codex --write-evidence --json-output
ntk runtime session-housekeeping export-planning-summary --workspace-root .
ntk runtime session-housekeeping preflight --runtime-root $env:USERPROFILE --workspace-root . --provider codex --export-planning-summary --apply-requested --write-evidence --json-output
ntk runtime session-housekeeping apply --runtime-root $env:USERPROFILE --workspace-root . --provider codex --export-planning-summary --write-evidence --confirm-session-cleanup codex --json-output

Function invocation observability can summarize sanitized repository ledgers under .deployment/artifacts/runtime/function-usage/. Machine-global Agent runtime logs use %USERPROFILE%\.ntk\logs\{agent-name} on Windows, with the Super Agent defaulting to .ntk/logs/super-agent. The Agent runtime can summarize provider usage, write reviewable reports, and validate that every cataloged function has linked command and test-role metadata without reading raw Codex, Copilot, or Claude sessions:

ntk runtime functions smoke --runtime-root $env:USERPROFILE --provider codex --json-output
ntk runtime functions usage --repo-root . --runtime-root $env:USERPROFILE --provider codex --since today --until today --group-by provider-function
ntk runtime functions report --repo-root . --runtime-root $env:USERPROFILE --provider codex --since today --until today --group-by provider-function --output-root .deployment/artifacts/runtime/function-usage/reports/latest --format both
ntk runtime functions doctor --codebase . --json-output

Each recorded invocation writes the Agent event plus shared nettoolskit-observability records for audit, log, metric, and trace signals under the same date-partitioned sink. The smoke command is mutation-free and exists to prove the selected ledger can receive and summarize events.

Runtime observability settings follow a Serilog-style model with enabled, minimumLevel, local sinks, enrichment, and allow-list redaction. Repository settings live under .deployment/artifacts/runtime/observability/; user-global settings live under .ntk/observability/agent/ below the selected runtime root. Default runtime logging is enabled at error level and writes to the user-global Super Agent sink. Configure and enable commands create enabled sink roots. Status reports include sink existence, event counts, telemetry record counts, the Agent package version, and Super Agent source/runtime hash alignment without parsing raw provider sessions:

ntk runtime observability status --repo-root . --runtime-root $env:USERPROFILE --json-output
ntk runtime observability configure --repo-root . --runtime-root $env:USERPROFILE --enabled true --minimum-level error --sink user --yes
ntk runtime observability disable --repo-root . --runtime-root $env:USERPROFILE --yes

Use parity to compare the current runtime evidence with the previous local .temp/copilot-instructions baseline. The report classifies previous surfaces as covered, deferred, optional, superseded, or excluded without printing the absolute previous baseline root.

The all profile excludes optional VS Code global user files. Use --profile vscode to dry-run or explicitly apply VS Code settings, snippets, and profile baselines:

ntk runtime provider-surfaces plan --repo-root . --runtime-root $env:USERPROFILE --profile vscode
ntk runtime provider-surfaces apply --repo-root . --runtime-root $env:USERPROFILE --profile vscode --yes

The Agent package also exposes the same provider-surface UX through the nettoolskit-agent binary while generic ntk delegation is wired by the downstream CLI layer:

cargo run --bin nettoolskit-agent -- runtime provider-surfaces doctor --repo-root . --runtime-root $env:USERPROFILE --profile all
cargo run --bin nettoolskit-agent -- runtime provider-surfaces healthcheck --repo-root . --runtime-root $env:USERPROFILE --profile all
cargo run --bin nettoolskit-agent -- runtime provider-surfaces report --repo-root . --runtime-root $env:USERPROFILE --profile all

See Provider Runtime Surfaces for the manifest, report contract, dry-run planning, backup behavior, and explicit apply boundary.

Codex provider scripts remain versioned under definitions/providers/codex/scripts as provider runtime assets. They are not crate source files and should not be moved under crates/**/src. Rust owns the deterministic behavior and static wrapper contract; PowerShell wrappers only forward explicit parameters to ntk runtime. The provider runtime manifest now projects the reviewed wrappers into .codex/scripts for the Codex profile; use provider runtime plan, apply --yes, and verify instead of hand-copying those files.

Codex orchestration assets remain versioned under definitions/providers/codex/orchestration as declarative provider runtime assets. They project to .codex/orchestration, but do not execute provider runtimes, call model APIs, invoke memory, or run shell commands from nettoolskit-agent.

GitHub chatmode assets remain versioned under definitions/providers/github/chatmodes as concise provider entrypoints. They project to .github/chatmodes only when the runtime validator confirms valid frontmatter, bounded context, source-instruction references, and no local path or secret-shaped leakage.

GitHub prompt assets remain versioned under definitions/providers/github/prompts as concise source-backed task entrypoints. They project to .github/prompts only when the runtime validator confirms valid frontmatter, bounded payloads, required sections, source references, and no copied code blocks, local paths, or secret-shaped leakage.

Planning

Planning lives under planning.

The SDD flow is Requirements -> Use Cases -> Architecture -> UCP -> Specs -> Plans -> Implementation. Requirements, use cases, and architecture are durable source documents under docs/requirements/**; UCPs, specs, and plans are derived coordination artifacts under planning/**.

UCP generation is deterministic. Parameter files live under planning/ucps/parameters/**; preview output defaults to .deployment/artifacts/planning/ucps/; official active and completed milestone pages are written only when parameters explicitly choose versioned-active or versioned-completed. Completed planning artifacts are archived under finalization-month YYYY-MM folders.

Requirement source documents live under docs/requirements/**. A requirement domain uses REQUIREMENTS.md, ARCHITECTURE.md, and one Markdown file per use case under use-cases/. Active plans that change behavior, business rules, workflow, architecture, or acceptance criteria must reference the relevant source documents; maintenance-only plans may declare source traceability as not required.

Current active workstreams are tracked under planning/plans/active.

Specs and plans have different jobs. Specs under planning/specs/** capture design intent, alternatives, constraints, risks, and acceptance criteria. Plans under planning/plans/** translate that intent into ordered execution tasks, target paths, validation commands, evidence, PR closeout, release/tag handling, and branch cleanup. One large milestone plan may reference multiple specs when each spec owns an independent design boundary. Narrow maintenance or governance clarification work can be plan-only when the plan explicitly records Spec: not required and why.

The installed Super Agent must not be replaced until the planning gates, validation gates, provider projection gates, and sanitization gates are satisfied.

Changelog

Release-relevant instruction, provider projection, governance, and validation changes are tracked in CHANGELOG.md.

Governance and Security

One rule has one canonical home. Provider-specific files can exist only as projections, adapters, or generated surfaces.

Canonical instruction growth is budgeted:

target: 40 to 46 active canonical instruction sources;
soft warning: more than 46 canonical instructions;
hard gate: more than 52 canonical instructions without an approved consolidation decision.

Do not commit secrets, tokens, usernames, machine-local paths, raw logs, or unsanitized release artifacts. Examples must use neutral placeholders such as workspace-root, operator-example, and repository-relative paths.

Repository-local operating rules live in AGENTS.md. Reusable governance instructions live under definitions/instructions/governance/.

The current Git workflow policy requires semantic branches such as feat/..., fix/..., refactor/..., docs/..., test/..., chore/..., ci/..., and release/.... Use develop, not development, as the long-lived integration branch when one is required. Commit subjects must use <type>(optional-scope): imperative summary, stay in English, stay under 72 characters, and avoid vague publishable text such as wip, update files, or changes. Publishable work must go through pull requests, update CHANGELOG.md, use Semantic Versioning, create GitHub tags in the vMAJOR.MINOR.PATCH format when a release version is present, and delete merged semantic work branches after the PR is accepted.

CI/CD governance requires explicit, named stages. Validation, security, testing, build, package, release, deploy, and verify concerns must stay separated with clear gates and evidence. The reusable stage policy lives in definitions/instructions/governance/ntk-governance-ci-cd-stages/instructions.md.

Release and package outputs must pass sanitization before publication. The reusable sanitization policy lives in definitions/instructions/governance/ntk-governance-release-artifact-sanitization/instructions.md.

Audit Evidence Pack templates live under definitions/templates/docs/audit-evidence-pack/. Generated audit evidence and supporting artifacts belong under .deployment/artifacts/audit/<run-or-scope>/ until they are sanitized for publication.

Build and Tests

Run the local validation set before opening or updating a PR:

cargo fmt --all --check
cargo test -p nettoolskit-agent --test test_suite -- --nocapture
cargo clippy --all-targets --all-features -- -D warnings
cargo run -p nettoolskit-agent -- rust validate-crate --codebase . --profile workspace --target all --report none --fail-on error
cargo run -p nettoolskit-agent -- validation all --codebase . --profile release --report markdown --output-root .deployment/artifacts/audit/validation-all/release --fail-on error
bash scripts/ci/river/test-agent-stage.sh
git diff --check

Run the managed EOF hygiene command after documentation, instruction, or Rust source changes. Rust files keep the final newline required by rustfmt; other text files keep the repository no-final-newline policy:

ntk runtime trim-trailing-blank-lines --repo-root . --git-changed-only

Build local package artifacts when a Rust crate archive or npm installer is needed:

cargo run -p nettoolskit-agent --locked -- package build-artifacts

The builder creates source .crate archives by default because Agent currently depends on private NetToolsKit crates that are not registry-resolvable. Use --use-cargo-package only after the private dependency chain is available from the configured Cargo registry. scripts/package/build-artifacts.ps1 is a thin compatibility wrapper around the Rust command for older local calls.

The package builder writes:

Artifact	Output path	Purpose
Cargo crates	`.deployment/artifacts/package/cargo/*.crate`	Reusable Rust package archives for Agent workspace crates.
npm tarball	`.deployment/artifacts/package/npm/nettoolskit-super-agent-<version>.tgz`	Explicit `@nettoolskit/super-agent` installer package generated from the provider runtime surface manifest.
manifest	`.deployment/artifacts/package/package-artifacts.json`	Package names, versions, sizes, and SHA-256 hashes.
GHCR crate bundle	`ghcr.io/nettoolskit/nettoolskit-agent-crates`	Private OCI bundle that stores the generated Cargo `.crate` archives and checksum manifest for GitHub Packages discovery.

The source-owned npm wrapper lives under deployment/wrappers/npm/super-agent and must remain versioned because it contains package.json, the installer CLI, and the runtime asset selection config. .deployment/artifacts/package/npm/** is the generated staging and tarball output. Keep future npm, WinGet, Homebrew, Chocolatey, MSI, shell installer, and similar operator-facing wrapper sources under deployment/wrappers/{ecosystem}/{package}/, not under .deployment.

GitRiver owns package publication. The river/release stage runs only from main, regenerates the same artifacts, publishes the @nettoolskit/super-agent tarball to GitHub Packages, publishes the nettoolskit-agent-crates GHCR bundle with the generated Cargo archives through ORAS without requiring Docker daemon access, and reads package credentials only from masked GitRiver variables synchronized by Access from Bitwarden. The GHCR bundle is artifact storage and discovery, not a native Cargo registry. Main-branch package publication is intentionally idempotent: when GitRiver cannot derive changed paths for a main publish run, the release stage runs and then skips only the already published npm version while refreshing the GHCR crate bundle.

Publish or refresh the GitRiver metadata repository through Access:

pwsh -NoLogo -NoProfile -File scripts/integrations/gitriver/publish-agent-ci-metadata.ps1

The npm package stages provider runtime assets from definitions/providers/runtime/provider-runtime-surfaces.json; it does not use postinstall. Install the Super Agent runtime explicitly after installing the tarball:

Package publication is treated as supply-chain release work: npm, Cargo, image, and installer outputs must pass dry-run file-list inspection and block secrets, local paths, generated caches, session logs, prompt transcripts, and unreviewed runtime artifacts. Runtime package content consumed by LLMs is treated as untrusted data to reduce prompt-injection risk.

npm install -g .deployment/artifacts/package/npm/nettoolskit-super-agent-0.1.0.tgz
ntk-super-agent plan --runtime-root $env:USERPROFILE
ntk-super-agent install --runtime-root $env:USERPROFILE --yes
ntk-super-agent verify --runtime-root $env:USERPROFILE

For one-off usage through GitHub Packages, configure npm authentication for the private @nettoolskit scope and run:

npx --yes --package=@nettoolskit/super-agent@0.1.0 ntk-super-agent verify --runtime-root $env:USERPROFILE

Contributing

Work from a semantic branch and keep changes scoped to reusable agent behavior. Update planning state for non-trivial instruction, governance, projection, or validation changes.

Do not add a new instruction file when an existing canonical instruction can be extended. Do not reintroduce .github/instructions/** as an authored duplicate tree.

Dependencies

Runtime: nettoolskit-contracts, nettoolskit-validation, serde, serde_json

The crate should remain lightweight. Product-runtime SDKs, LLM provider SDKs, deployment SDKs, browser automation SDKs, and machine-control implementations belong in product repositories unless a separate architecture decision approves their presence here.

References

License

This project is licensed under the MIT License. See the LICENSE file at the repository root for details.

Package publication

Current preview package: @nettoolskit/agent@0.0.1-preview.6. Use npx @nettoolskit/agent for ephemeral execution or ntk-agent after global installation. GitRiver stage river/release validates the staged native Rust binary inside the npm tarball before publication, requires Windows and Linux native assets on trusted release refs, and publishes only from main or v* source refs through scripts/ci/river/npm-publish.sh; trusted release refs also synchronize the npm latest dist-tag.

Keywords

nettoolskit agent cli npx