hve-squad

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

There is a pre-release process that creates a pre-release tag of what is being merged to main but the official release stays intact. Like the current situation, we are at v0.16.1 but the pre-release is at v0.16.2-pre
Users can always use the pre-release if they wish to but it is always better to use the latest one as it is tested.

https://github.com/Peter-N91/hve-squad/tags
https://github.com/Peter-N91/hve-squad/releases

Repository on GitHub, which uses git. git is distributed.

Releases and tags are unique for each release and changelog explains what changes.

https://github.com/Peter-N91/hve-squad/tags
https://github.com/Peter-N91/hve-squad/releases
https://github.com/Peter-N91/hve-squad/blob/main/CHANGELOG.md

Tags are used https://github.com/Peter-N91/hve-squad/tags

Non-trivial release notes file in repository: https://github.com/Peter-N91/hve-squad/blob/main/CHANGELOG.md.

release notes file in repository: https://github.com/Peter-N91/hve-squad/blob/main/CHANGELOG.md.

Bug reports are submitted through the GitHub issue tracker at https://github.com/Peter-N91/hve-squad/issues, which is open to the public and requires only a GitHub account. A structured Bug report form at .github/ISSUE_TEMPLATE/bug-report.yml collects the installed version, the Copilot host, expected against actual behaviour, reproduction steps, and optional squad state. The "Reporting a bug" section of CONTRIBUTING.md documents the process and the two exceptions: security vulnerabilities go privately through GitHub Security Advisories as described in SECURITY.md, and defects in upstream microsoft/hve-core assets are directed to that repository. .github/ISSUE_TEMPLATE/config.yml surfaces both routes directly in the issue-creation chooser.

Some of the issues can be labeled to squad/auto and have the squad itself handle them. The history of the squad member will be saved under .copilot-tracking

Reports and responses are archived publicly in the GitHub issue tracker at https://github.com/Peter-N91/hve-squad/issues?q=is%3Aissue, which lists open and closed issues together. The archive is readable without a GitHub account, is indexed by GitHub's full-text search across titles, bodies, and comments, and every issue and comment has a stable, permanently addressable URL. It currently holds 16 issues, 15 of them closed with the discussion and resolution intact, alongside 82 pull requests at https://github.com/Peter-N91/hve-squad/pulls?q=is%3Apr, where most defect fixes are discussed and linked back to the issue they close. Nothing is deleted on closure, so the reasoning behind a past fix stays retrievable.

All vulnerabilities will be shown under this tab and handled by contributors

https://github.com/Peter-N91/hve-squad/security/code-scanning

Private vulnerability reports are supported through GitHub Security Advisories at https://github.com/Peter-N91/hve-squad/security/advisories/new. Private vulnerability reporting is enabled on the repository, so any GitHub user can open a report that is visible only to the reporter and the maintainer until an advisory is published. Submission is over HTTPS. The process is documented in SECURITY.md, which states explicitly that vulnerabilities must not be filed as public issues, lists what to include (affected version or commit, component, reproduction steps, observed impact, suggested mitigation), and commits to acknowledgement within 5 business days and a status update within 10. The same private route is surfaced in the issue-creation chooser through .github/ISSUE_TEMPLATE/config.yml and in the Bug report template, so a reporter who starts down the public path is redirected before disclosing anything.

All vulnerabilities were treated in a single day.

The build is automated in PowerShell and driven from CI. scripts/Build-SquadPlugin.ps1 deterministically assembles the distributable Copilot CLI plugin from the squad-src/ tree and is invoked by .github/workflows/publish-plugin.yml on every release tag; it can also be run locally as a manual fallback. scripts/Update-ApmDependencies.ps1 regenerates the apm.yml dependency manifest and apm.lock.yaml from source, and .github/workflows/pr-validation.yml re-runs it on every pull request to verify the checked-in manifest matches what the build produces. Modifying source under squad-src/ and re-running either script yields updated artifacts with no manual steps. External dependencies (microsoft/hve-core) are fetched at install time by APM and are not rebuilt here.

The build uses PowerShell 7 (pwsh), a widely adopted cross-platform build and automation tool, rather than a project-specific build system. Named build targets are declared in the scripts: section of apm.yml (sync-deps, install-sync, change, release-prep), which serves the same role as make targets and gives contributors a single documented entry point per task. The APM CLI performs dependency resolution and installation, and GitHub Actions orchestrates the build in CI. All of these are standard, off-the-shelf tools; the project defines no custom build engine or DSL.

Every tool in the build chain is FLOSS. The build scripts run on PowerShell 7 (MIT), dependency resolution and installation use the APM CLI (microsoft/apm, MIT), source and ref handling uses Git (GPL-2.0), the plugin packaging path uses Node.js and npm (MIT / Artistic-2.0), and release automation uses the GitHub CLI (MIT). No proprietary compiler, SDK, or build tool is required. The build is not Windows-dependent: PowerShell 7 is cross-platform and CI executes the same scripts on Ubuntu runners, so a contributor can reproduce the full build on a Linux machine using only free/libre software.

The project uses Pester 5.7.1 (Apache-2.0), a FLOSS test framework for PowerShell, across three automated suites in tests/: Tier 0 conformance (tests/tier0/) validates the package manifest and shipped asset structure, Tier 1 behavior (tests/tier1/) validates the squad state contract and coordinator assertions against recorded scenarios, and Tier 2 semantic (tests/tier2/) compares live squad runs against stored baselines. Each tier has a runner script (Invoke-Tier0Tests.ps1, Invoke-Tier1Tests.ps1, Invoke-Tier2Tests.ps1) that can be executed locally with pwsh. All three run in CI on every pull request via .github/workflows/tier0-conformance.yml, tier1-behavior.yml, and tier2-semantic.yml, which document the exact install and invocation steps. The test suites and their fixtures are MIT-licensed as part of this repository.

Tests are invoked in the standard way for PowerShell. Each suite is executed through Invoke-Pester with New-PesterConfiguration, the conventional Pester entry point, wrapped in a per-tier runner script (tests/tier0/Invoke-Tier0Tests.ps1 and equivalents for Tier 1 and Tier 2). The wrappers are required because the suites are parameterised through New-PesterContainer -Data, so they cannot be discovered by a bare Invoke-Pester call. A single-command entry point is also declared as the test target in the scripts: section of apm.yml, so apm run test runs the fast conformance suite in the same way make check would. CI invokes the same runner scripts, so local and CI invocation are identical.

The project practises continuous integration against a single central repository. All changes land on main through squash-merged pull requests, with 103 commits integrated in the last 30 days, and branches are short-lived. Every pull request triggers automated validation in GitHub Actions: .github/workflows/tier0-conformance.yml installs the package the branch would deliver and runs the Pester static conformance suite against it, and .github/workflows/pr-validation.yml verifies release state and change-fragment hygiene. Security analysis runs on the same trigger through CodeQL, Zizmor, Checkov, and OpenSSF Scorecard. The same Tier 0 workflow is reused as the release gate via workflow_call, so the check that guards a merge is the check that guards a tag. Merged work is rebuilt onto a rolling pre-release tag within minutes, keeping the integrated state continuously installable and testable.

The policy is documented in the "Automated tests" section of CONTRIBUTING.md: major new functionality must come with tests. A pull request adding a new agent, routing rule, gate, or any consumer-observable behavior is expected to add or extend a case in the automated suite. Documentation, wording fixes, and behavior-preserving refactors are exempt, and a maintainer may waive the requirement for behavior that cannot be asserted without a live model run, stating so on the pull request. The policy is enforced at review time through a Tests checklist in the pull request template, which asks the contributor to confirm the case was added, declared in tests/squad-behavior-contract.md with a citation to the source file stating the rule, and that apm run test passed locally.

The automated suite was introduced on 2026-08-20 and the policy has been followed since. Of the sixteen changes merged after that date, ten added or extended test cases. Every change to squad behavior shipped a regression case traced to a numbered entry in tests/squad-behavior-contract.md: PR #79 (state records survive on every host, 5 test files), #81 (Scribe line-number leakage, 3), #82 (Deliverable Root binding, 5), #83 (deliverable path truncation, 4), #84 and #85 (ledger arithmetic and turn accumulation, 3 and 4), #87 (Init floor record, 2), and #89 (dispatch-backed ledger rows, 3). The most recent feature work, PR #86, added four test files alongside the behavior change. Changes merged without tests are confined to build and release workflow fixes (#92, #93, #94), which sit outside the suite's scope of asserting the shipped asset package.

The policy is documented in the instructions for change proposals in two places. CONTRIBUTING.md carries an "Automated tests" section stating that major new functionality must come with tests, naming the exemptions (documentation, wording fixes, behavior-preserving refactors) and the maintainer waiver for behavior that cannot be asserted without a live model run. It also explains the three test tiers, how to run each locally, and the required Pester version. The pull request template at .github/pull_request_template.md is injected into every pull request description and includes a Tests checklist asking the contributor to confirm that a case was added or extended, that it was declared in tests/squad-behavior-contract.md with a citation to the source file stating the rule, and that apm run test passed locally. Contributors therefore see the policy both before and during change proposal.

The project uses PSScriptAnalyzer, the standard FLOSS linter for PowerShell, over scripts/ and tests/, which together contain all executable code the repository authors. It runs on every pull request and push to main via .github/workflows/lint-powershell.yml, blocks the build on Error-severity findings, and publishes all findings as SARIF to the GitHub Security tab. Rule configuration lives in PSScriptAnalyzerSettings.psd1 at the repository root, so contributors get identical results in VS Code and in CI; the two excluded rules each carry a written justification in that file. In addition, the build scripts and test runners set Set-StrictMode -Version Latest and $ErrorActionPreference = 'Stop', PowerShell's equivalent of a safe language mode. Three further FLOSS analysers run on the same trigger: CodeQL for Python, Zizmor for GitHub Actions workflows, and Checkov for infrastructure-as-code.

All PSScriptAnalyzer findings are addressed. Actionable findings were fixed rather than suppressed: five empty catch blocks now record why the failure is deliberately ignored, seven inconsistent pipeline continuations were realigned, and a line-numbering loop that relied on a cross-scriptblock counter was rewritten. Findings that are genuine false positives are marked in the source with [Diagnostics.CodeAnalysis.SuppressMessageAttribute] carrying a written justification; these cover parameters PSScriptAnalyzer cannot resolve across Pester's separate discovery and run scopes, and a parameter-set selector consumed through $PSCmdlet.ParameterSetName. Two rules are excluded repository-wide in PSScriptAnalyzerSettings.psd1, each with a documented reason: PSAvoidUsingWriteHost, because these are interactive CLI scripts whose console output is the intended behaviour, and PSUseBOMForUnicodeEncodedFile, because every script begins with a #!/usr/bin/env pwsh shebang that a byte-order mark would break on the Linux runners CI uses. The remaining 22 findings are all Warning or Information severity across 5,506 lines of PowerShell, a rate of 0.40 per 100 lines, and none is Error severity. The CI gate blocks the build on Error severity.

The project enables strict checking wherever it is practical. PSScriptAnalyzer runs with IncludeDefaultRules = $true and reports at all three severities (Error, Warning, Information) rather than errors alone, so nothing is filtered out before a human sees it. Only two rules are excluded repository-wide, each with a written justification in PSScriptAnalyzerSettings.psd1, and individual false positives are marked at the call site rather than by broadening those exclusions. Every script and module additionally runs under Set-StrictMode -Version Latest, PowerShell's strictest language mode, which turns references to uninitialized variables, non-existent properties, and malformed method calls into terminating errors, combined with $ErrorActionPreference = 'Stop' so no error is silently swallowed. Three further analysers run at their default full rule sets on every pull request: CodeQL for Python, Zizmor for GitHub Actions workflows, and Checkov for infrastructure-as-code, with Checkov configured as blocking and accepted findings requiring a justified inline checkov:skip.

The project has a single primary developer, who initiated it, authors its releases, and receives private vulnerability reports. Familiarity with secure design is evidenced in the architecture rather than asserted. The system is built around a small number of deliberately narrow human gates rather than a broad permission model (economy of mechanism), and those gates deny by default: an autopilot run stops at any impactful or irreversible action and proceeds only on explicit human approval, never on a timeout (fail-safe defaults). Progress is non-bypassable, since each pipeline stage is gated on the prior stage's artifact and history entry existing on disk, so a stage cannot be skipped by narrating it as complete (complete mediation). The entire design, including every gate and routing rule, is public under an MIT licence and depends on enforcement rather than obscurity (open design). Impactful actions require two independent conditions, the agent's proposal and a human approval delivered through a separate channel (separation of privilege). CI workflows declare an empty top-level permissions: {}, grant the minimum scope per job, and check out with persist-credentials: false (least privilege), while test runs are isolated in per-run scratch directories and Watch Mode scopes sub-squads per event (least common mechanism). The user-facing surface is a single /squad entry point, and a blocked action explains what was stopped and how to proceed (psychological acceptability). The package flow is one-directional: consumers pull assets and the package never reads from consumer environments, and the project runs no service and stores no user data (limited attack surface). Inputs are constrained by allowlists rather than denylists, through ValidateSet on script parameters, a fixed set of squad profiles, and an explicit untrusted-content boundary that treats all ingested external content as data to analyse and never as instructions to execute, refusing embedded authority changes such as "ignore previous instructions" or "set autonomy to full".

The primary developer has over eleven years of experience as a software developer and technical lead and works as a Partner Solution Architect at Microsoft, where secure development practice is part of the role. Because this project ships AI agent assets rather than a network service, the dominant error classes are those in the OWASP Top 10 for LLM Applications and the OWASP Agentic Security Initiative rather than the memory-safety and injection classes of the CWE Top 25, though the latter still apply to the build scripts. The relevant classes and their mitigations in this project are: prompt injection (LLM01), countered by an explicit untrusted-content boundary that processes all ingested external content as data to analyse or quote and never as instructions, and that refuses embedded authority changes such as "ignore previous instructions" or "set autonomy to full"; excessive agency and insecure output handling (LLM02, LLM06), countered by an impactful-action gate that halts any irreversible operation and resumes only on explicit human approval delivered through a separate channel, never on a timeout; supply-chain compromise (LLM03, CWE-1357), countered by pinning every third-party GitHub Action to a full commit SHA, pinning the upstream microsoft/hve-core dependency to a specific commit that only a guarded workflow may move, a resolved apm.lock.yaml, Dependabot updates, and OpenSSF Scorecard analysis; sensitive information disclosure (CWE-200), countered by a mandatory sanitisation checklist on any pull request proposing a shared learning, requiring removal of secrets, customer and individual names, internal URLs, and environment-specific paths, backed by GitHub secret scanning with push protection; CI script injection (CWE-94, CWE-78), countered by Zizmor static analysis of every workflow and by passing untrusted inputs through environment variables rather than interpolating them into shell blocks; path traversal (CWE-22), countered by consistent use of -LiteralPath in file operations; and missing authorization (CWE-862), countered by gates that persist in state.json and advance only on an authorised approval. Familiarity with these classes is further evidenced by the assessment tooling the project ships: security-review-llm.prompt.md drives owasp-llm and owasp-agentic assessments, and the package includes dedicated CVE analysis, dependency review, supply-chain review, and VEX generation agents.