feat: schedule local workspace verification

This commit is contained in:
2026-08-10 14:10:25 +09:00
parent 966a06e881
commit 76ded1947d
8 changed files with 264 additions and 110 deletions

1
.gitignore vendored
View File

@@ -1,5 +1,6 @@
/node_modules/
/.build/
/workspace.local.yml
/.local/
*.tmp
*.bak

52
Jenkinsfile vendored
View File

@@ -1,52 +0,0 @@
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 = [System.IO.Path]::Combine(
$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

@@ -65,4 +65,19 @@ Run a read-only verification of every shared and local project registration from
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.
This command uses the committed runtime bundle and does not compose documents, update Git repositories, or access the network.
To retain a local UTF-8 log for the same verification:
```powershell
npm.cmd run verify:scheduled
```
Install or remove the weekday Windows scheduled task with:
```powershell
npm.cmd run schedule:install
npm.cmd run schedule:uninstall
```
See [docs/local-scheduling.md](docs/local-scheduling.md) for scheduling, log retention, and failure handling.

View File

@@ -1,56 +0,0 @@
# 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.

54
docs/local-scheduling.md Normal file
View File

@@ -0,0 +1,54 @@
# Local Scheduled Workspace Verification
The Windows Task Scheduler runs the same read-only workspace verification as the manual command. It does not compose documents, update repositories, perform Git operations, or access the network.
## Manual verification with a retained log
Run the scheduled-verification wrapper directly before registering the task:
```powershell
npm.cmd run verify:scheduled
```
Each execution stores a UTF-8 log below `.local/verification-logs`. The directory is ignored by Git, and logs older than 30 days are removed after an execution finishes.
## Register the weekday task
Register the task for the current Windows user:
```powershell
npm.cmd run schedule:install
```
The default task is named `KRI Agent Harness Workspace Verify` and runs Monday through Friday at 08:30. It uses one process at a time, retries a failed task up to three times, and runs a missed schedule when the signed-in user becomes available.
The task uses an interactive, limited Windows principal. The computer must be running and the registered user must be signed in before the process can execute.
To use a different time, call the registration script directly with an `HH:mm` value:
```powershell
.\scripts\register-scheduled-verification.ps1 -At <HH:mm>
```
## Remove the task
```powershell
npm.cmd run schedule:uninstall
```
Removing the task does not remove retained verification logs.
## Result handling
Task Scheduler records the verification process exit code:
- `0`: all registered Agent Harness documents are current;
- non-zero: a missing repository, invalid profile, stale generated document, or another verification error was detected.
Treat a failed task as a drift report, not as authorization for automatic repair:
1. inspect the newest log in `.local/verification-logs`;
2. update the authoritative `.agent` source when a rule changed;
3. run `plan` and obtain approval for affected repositories;
4. run the narrowest applicable `compose` command;
5. run the verification again and commit each repository independently after approval.

View File

@@ -14,7 +14,10 @@
"typecheck": "tsc -p tsconfig.json --noEmit",
"test": "node --test",
"verify": "npm run typecheck && npm run build && npm test",
"verify:workspace": "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts/verify-workspace.ps1"
"verify:workspace": "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts/verify-workspace.ps1",
"verify:scheduled": "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts/run-scheduled-verification.ps1",
"schedule:install": "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts/register-scheduled-verification.ps1",
"schedule:uninstall": "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts/register-scheduled-verification.ps1 -Unregister"
},
"engines": {
"node": ">=20"

View File

@@ -0,0 +1,100 @@
[CmdletBinding()]
param(
[string] $TaskName = 'KRI Agent Harness Workspace Verify',
[string] $At = '08:30',
[string] $WorkspaceRoot,
[switch] $Unregister
)
$ErrorActionPreference = 'Stop'
$scriptRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
$harnessRoot = Split-Path -Parent $scriptRoot
$runnerScript = Join-Path $scriptRoot 'run-scheduled-verification.ps1'
if ($Unregister) {
$existingTask = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
if ($null -eq $existingTask) {
Write-Host "Scheduled task is not registered: $TaskName"
exit 0
}
Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false
Write-Host "Scheduled task removed: $TaskName"
exit 0
}
if ([string]::IsNullOrWhiteSpace($WorkspaceRoot)) {
$WorkspaceRoot = Split-Path -Parent $harnessRoot
}
$scheduledTime = [TimeSpan]::Zero
if (-not [TimeSpan]::TryParseExact(
$At,
'hh\:mm',
[System.Globalization.CultureInfo]::InvariantCulture,
[ref] $scheduledTime
)) {
throw "Scheduled time must use HH:mm format. Found: $At"
}
$resolvedWorkspaceRoot = [System.IO.Path]::GetFullPath($WorkspaceRoot)
$expectedHarnessRoot = [System.IO.Path]::GetFullPath(
(Join-Path $resolvedWorkspaceRoot '_________AgentHarnessBase')
)
$resolvedHarnessRoot = [System.IO.Path]::GetFullPath($harnessRoot)
if (-not $resolvedHarnessRoot.Equals(
$expectedHarnessRoot,
[System.StringComparison]::OrdinalIgnoreCase
)) {
throw "Harness repository must be a direct child of the configured workspace root. Expected: $expectedHarnessRoot"
}
if (-not (Test-Path -LiteralPath $runnerScript -PathType Leaf)) {
throw "Scheduled verification runner not found: $runnerScript"
}
$account = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
$powershellCommand = Join-Path $PSHOME 'powershell.exe'
$actionArguments = @(
'-NoProfile'
'-NonInteractive'
'-ExecutionPolicy Bypass'
"-File `"$runnerScript`""
"-WorkspaceRoot `"$resolvedWorkspaceRoot`""
) -join ' '
$action = New-ScheduledTaskAction `
-Execute $powershellCommand `
-Argument $actionArguments `
-WorkingDirectory $resolvedHarnessRoot
$trigger = New-ScheduledTaskTrigger `
-Weekly `
-WeeksInterval 1 `
-DaysOfWeek Monday, Tuesday, Wednesday, Thursday, Friday `
-At ([DateTime]::Today.Add($scheduledTime))
$principal = New-ScheduledTaskPrincipal `
-UserId $account `
-LogonType Interactive `
-RunLevel Limited
$settings = New-ScheduledTaskSettingsSet `
-StartWhenAvailable `
-MultipleInstances IgnoreNew `
-RestartCount 3 `
-RestartInterval (New-TimeSpan -Minutes 10) `
-ExecutionTimeLimit (New-TimeSpan -Hours 1)
Register-ScheduledTask `
-TaskName $TaskName `
-Action $action `
-Trigger $trigger `
-Principal $principal `
-Settings $settings `
-Description 'Runs the read-only KRI Agent Harness workspace verification and stores a local log.' `
-Force | Out-Null
Write-Host "Scheduled task registered: $TaskName"
Write-Host "User: $account"
Write-Host "Schedule: Monday-Friday $At"
Write-Host "Workspace: $resolvedWorkspaceRoot"

View File

@@ -0,0 +1,89 @@
[CmdletBinding()]
param(
[string] $WorkspaceRoot,
[string] $LogDirectory,
[ValidateRange(1, 3650)]
[int] $RetentionDays = 30
)
$ErrorActionPreference = 'Stop'
$scriptRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
$harnessRoot = Split-Path -Parent $scriptRoot
$verificationScript = Join-Path $scriptRoot 'verify-workspace.ps1'
if ([string]::IsNullOrWhiteSpace($WorkspaceRoot)) {
$WorkspaceRoot = Split-Path -Parent $harnessRoot
}
$resolvedWorkspaceRoot = [System.IO.Path]::GetFullPath($WorkspaceRoot)
if ([string]::IsNullOrWhiteSpace($LogDirectory)) {
$LogDirectory = Join-Path $harnessRoot '.local\verification-logs'
}
$resolvedLogDirectory = [System.IO.Path]::GetFullPath($LogDirectory)
[System.IO.Directory]::CreateDirectory($resolvedLogDirectory) | Out-Null
$timestamp = Get-Date -Format 'yyyyMMdd-HHmmss'
$logFile = Join-Path $resolvedLogDirectory "verify-$timestamp.log"
$utf8WithoutBom = [System.Text.UTF8Encoding]::new($false)
$logWriter = [System.IO.StreamWriter]::new($logFile, $false, $utf8WithoutBom)
$exitCode = 1
function Write-VerificationLogLine {
param([AllowEmptyString()][string] $Line)
Write-Host $Line
$logWriter.WriteLine($Line)
$logWriter.Flush()
}
try {
Write-VerificationLogLine "[Agent Harness] scheduled verification started=$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss zzz')"
Write-VerificationLogLine "[Agent Harness] computer=$env:COMPUTERNAME"
Write-VerificationLogLine "[Agent Harness] log=$logFile"
$powershellCommand = Join-Path $PSHOME 'powershell.exe'
& $powershellCommand `
-NoProfile `
-NonInteractive `
-ExecutionPolicy Bypass `
-File $verificationScript `
-WorkspaceRoot $resolvedWorkspaceRoot 2>&1 |
ForEach-Object {
Write-VerificationLogLine $_.ToString()
}
$exitCode = $LASTEXITCODE
if ($null -eq $exitCode) {
$exitCode = 1
}
Write-VerificationLogLine "[Agent Harness] scheduled verification exitCode=$exitCode"
}
catch {
Write-VerificationLogLine "[Agent Harness] scheduled verification error=$($_.Exception.Message)"
$exitCode = 1
}
finally {
$logWriter.Dispose()
}
$retentionCutoff = (Get-Date).AddDays(-$RetentionDays)
try {
Get-ChildItem -LiteralPath $resolvedLogDirectory -File -Filter 'verify-*.log' |
Where-Object {
$_.FullName -ne $logFile -and $_.LastWriteTime -lt $retentionCutoff
} |
ForEach-Object {
Remove-Item -LiteralPath $_.FullName -Force
}
}
catch {
Write-Warning "Failed to remove an expired verification log: $($_.Exception.Message)"
}
exit $exitCode