ci: verify agent harness workspace on Jenkins

This commit is contained in:
2026-08-10 11:18:44 +09:00
parent 219f0e22a8
commit e9467b15f9
5 changed files with 182 additions and 1 deletions

48
Jenkinsfile vendored Normal file
View File

@@ -0,0 +1,48 @@
pipeline {
agent { label 'agent-harness' }
options {
disableConcurrentBuilds()
skipDefaultCheckout(true)
timestamps()
}
triggers {
cron('TZ=Asia/Seoul\nH 8 * * 1-5')
}
stages {
stage('Verify Workspace') {
steps {
powershell '''
$ErrorActionPreference = 'Stop'
if ([string]::IsNullOrWhiteSpace($env:KRI_DEV_ROOT)) {
throw 'KRI_DEV_ROOT must point to the existing KRI multi-repository workspace root.'
}
$harnessRoot = Join-Path $env:KRI_DEV_ROOT '_________AgentHarnessBase'
$verificationScript = Join-Path $harnessRoot 'scripts\verify-workspace.ps1'
if (-not (Test-Path -LiteralPath $verificationScript -PathType Leaf)) {
throw "Workspace verification script not found: $verificationScript"
}
& $verificationScript -WorkspaceRoot $env:KRI_DEV_ROOT
if ($LASTEXITCODE -ne 0) {
exit $LASTEXITCODE
}
'''
}
}
}
post {
success {
echo 'All registered Agent Harness documents are current.'
}
failure {
echo 'Agent Harness drift or an invalid workspace registration was detected.'
}
}
}

View File

@@ -56,3 +56,13 @@ On Windows PowerShell, use `npm.cmd` because the `npm.ps1` shim may be blocked b
npm.cmd install
npm.cmd run verify
```
## Workspace Verification
Run a read-only verification of every shared and local project registration from the existing multi-repository workspace:
```powershell
npm.cmd run verify:workspace
```
This command uses the committed runtime bundle and does not compose documents, update Git repositories, or access the network. The Jenkins pipeline runs the same script on the dedicated Windows workspace node. See [docs/jenkins.md](docs/jenkins.md) for node configuration, scheduling, and failure handling.

56
docs/jenkins.md Normal file
View File

@@ -0,0 +1,56 @@
# Jenkins Workspace Verification
The root `Jenkinsfile` runs a read-only `verify --all` against the existing Windows multi-repository workspace. It detects stale generated documents, missing registered repositories, invalid profiles, and contract composition failures. It never composes files or performs Git operations.
## Windows node setup
Configure one Jenkins Windows node with:
- the label `agent-harness`;
- Node.js 20 or newer on `PATH`;
- every registered repository available in the established workspace layout;
- the node environment variable `KRI_DEV_ROOT` set to the absolute multi-repository workspace root.
Do not store the absolute workspace path, credentials, or tokens in this repository. The node-level environment variable owns the machine-specific path.
The local central harness clone must remain at `_________AgentHarnessBase` directly below `KRI_DEV_ROOT`. The pipeline deliberately skips the default Jenkins checkout and reads this existing clone so the relative paths in `workspace.yml` resolve to the sibling repositories.
## Jenkins job setup
Create a Pipeline job using Pipeline script from SCM:
- repository: the central Agent Harness repository;
- branch: `master`;
- script path: `Jenkinsfile`.
Assign the job only to the node carrying the `agent-harness` label. The pipeline runs automatically once per weekday at a hashed minute during the 08:00 hour in `Asia/Seoul`, and it may also be run manually.
The job does not fetch or update the repositories under `KRI_DEV_ROOT`. Keep that workspace synchronized using the existing repository update process before relying on the scheduled result.
## Local verification
From the central harness repository:
```powershell
npm.cmd run verify:workspace
```
To supply the workspace root explicitly:
```powershell
.\scripts\verify-workspace.ps1 -WorkspaceRoot <workspace-root>
```
Both forms execute the committed `dist\cli.cjs` bundle and require no package installation.
## Failure handling
Treat a failed build as a drift report, not as authorization for automatic repair:
1. identify the missing, invalid, or stale project in the console output;
2. update the authoritative `.agent` source when a rule changed;
3. run `plan` and obtain approval for the affected repositories;
4. run the narrowest applicable `compose` command;
5. run `verify` again and commit each repository independently after approval.
The Jenkins job must not compose documents, commit, push, pull, fetch, or modify credentials.

View File

@@ -13,7 +13,8 @@
"build": "node scripts/build.mjs",
"typecheck": "tsc -p tsconfig.json --noEmit",
"test": "node --test",
"verify": "npm run typecheck && npm run build && npm test"
"verify": "npm run typecheck && npm run build && npm test",
"verify:workspace": "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts/verify-workspace.ps1"
},
"engines": {
"node": ">=20"

View File

@@ -0,0 +1,66 @@
[CmdletBinding()]
param(
[string] $WorkspaceRoot
)
$ErrorActionPreference = 'Stop'
$scriptRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
$harnessRoot = Split-Path -Parent $scriptRoot
if ([string]::IsNullOrWhiteSpace($WorkspaceRoot)) {
$WorkspaceRoot = Split-Path -Parent $harnessRoot
}
$resolvedWorkspaceRoot = [System.IO.Path]::GetFullPath($WorkspaceRoot)
$resolvedHarnessRoot = [System.IO.Path]::GetFullPath($harnessRoot)
$expectedHarnessRoot = [System.IO.Path]::GetFullPath(
(Join-Path $resolvedWorkspaceRoot '_________AgentHarnessBase')
)
if (-not $resolvedHarnessRoot.Equals(
$expectedHarnessRoot,
[System.StringComparison]::OrdinalIgnoreCase
)) {
throw "Harness repository must be a direct child of the configured workspace root. Expected: $expectedHarnessRoot"
}
$workspaceFile = Join-Path $resolvedHarnessRoot 'workspace.yml'
$entryPoint = Join-Path $resolvedHarnessRoot 'dist\cli.cjs'
if (-not (Test-Path -LiteralPath $workspaceFile -PathType Leaf)) {
throw "Shared workspace registry not found: $workspaceFile"
}
if (-not (Test-Path -LiteralPath $entryPoint -PathType Leaf)) {
throw "Harness entry point not found: $entryPoint"
}
$nodeCommand = Get-Command node -ErrorAction SilentlyContinue
if ($null -eq $nodeCommand) {
throw 'Node.js 20 or newer is required.'
}
$nodeVersionText = (& $nodeCommand.Source --version).TrimStart('v')
if ($LASTEXITCODE -ne 0) {
exit $LASTEXITCODE
}
$nodeVersion = [Version] $nodeVersionText
if ($nodeVersion.Major -lt 20) {
throw "Node.js 20 or newer is required. Found: $nodeVersionText"
}
Write-Host "[Agent Harness] workspace=$resolvedWorkspaceRoot"
Write-Host "[Agent Harness] node=$nodeVersionText"
Write-Host '[Agent Harness] running read-only verify --all'
& $nodeCommand.Source $entryPoint verify --all
$verifyExitCode = $LASTEXITCODE
if ($verifyExitCode -ne 0) {
Write-Error "Agent Harness workspace verification failed with exit code $verifyExitCode."
exit $verifyExitCode
}
Write-Host '[Agent Harness] all registered projects are current.'