Add recurring drift and run evidence

Author: At0mFlow

AGENTS.md

@@ -15,9 +15,14 @@ Audit collector, its tests, synthetic examples, documentation and brand assets.
   backend, authentication, billing or customer-data logic.
 - Never add collected client scripts, task exports, server inventories or audit
   bundles to this repository.
-- Never initialise, commit, sync or push a client's collected scripts. The tool
-  may only write the requested local audit bundle.
+- Never initialise a client's repository, create a remote, store Git
+  credentials or stage paths outside the requested bundle. Explicit Git sync
+  may operate only in an existing working tree and must commit only the
+  bundle's `scripts/`, `manifests/` and `README.txt` paths.
 - Never add telemetry or upload audit results to At0mFlow or another service.
+- Never execute discovered scripts to infer success or failure. Execution
+  evidence must come from the previous hour of the local Windows Task Scheduler
+  Operational event log and missing evidence must remain unknown.
 - Never stage files from outside this repository.
 - Keep `origin` pointed only to
   `https://github.com/At0mFlow/At0mFlow-ScriptAudit.git` or its equivalent

PUBLIC_BOUNDARY.md

@@ -20,9 +20,16 @@ The tool writes a local audit bundle only after somebody runs it. That bundle
 can contain source code, server names, file owners, task principals, paths and
 scheduling details. It must be treated as confidential client material.
 
-The tool does not initialise Git, create a remote, push a repository, upload to
-At0mFlow or send telemetry. Generated bundle names are ignored by this public
-repository's `.gitignore`.
+The default tool does not run Git. Explicit `-GitSync` works only inside an
+existing working tree, commits only the selected bundle's `scripts/`,
+`manifests/` and `README.txt`, and uses the operator's existing non-interactive
+Git configuration. It does not initialise Git, create a remote, store
+credentials, upload to At0mFlow or send telemetry. Generated bundle names are
+ignored by this public repository's `.gitignore`.
+
+Execution evidence is limited to the previous hour of the local Windows Task
+Scheduler Operational event log. The collector does not execute a discovered
+script and does not convert absent evidence into an invented outcome.
 
 ## Automated controls
 

README.md

@@ -16,13 +16,15 @@ one server or many, preserving their folder tree, and recording the scheduled
 tasks that run them.
 
 It creates one local audit bundle containing copied scripts, CSV inventories,
-task actions, triggers, conditions, hashes and collection errors. It is designed
-for server estate discovery, SCCM deployment and the first stage of a controlled
-PowerShell audit.
+task actions, triggers, conditions, hashes, collection errors and one hour of
+local Task Scheduler outcome evidence. It is designed for server estate
+discovery, SCCM deployment and the first stage of a controlled PowerShell audit.
 
 The collector is public. The bundle it creates is not. Generated bundles can
-contain source code and infrastructure metadata, so the tool never initialises
-Git, pushes a repository, uploads to At0mFlow or sends telemetry.
+contain source code and infrastructure metadata. By default the tool performs
+no Git operation. An explicit `-GitSync` option can update a preconfigured
+private Git working tree, but it never initialises Git, creates a remote, stores
+credentials, uploads to At0mFlow or sends telemetry.
 
 ## Quick start
 
@@ -75,6 +77,8 @@ Computers: 2
 Scripts found: 47
 Scripts copied: 47
 PowerShell task actions: 18
+Execution evidence: 12
+Execution failures: 1
 Collection errors: 1
 Bundle: D:\Audit\At0mFlow-ScriptAudit-20260827
 ```
@@ -127,6 +131,7 @@ At0mFlow-ScriptAudit-20260827/
   manifests/
     script-inventory.csv
     scheduled-tasks.csv
+    script-run-evidence.csv
     collection-errors.csv
     summary.json
     TREE.txt
@@ -142,6 +147,12 @@ records include the principal, run level, logon type, action, arguments,
 working directory, script references, trigger summary, conditions, run times
 and last result.
 
+`script-run-evidence.csv` looks back exactly one hour in the local Windows Task
+Scheduler Operational log. A script is marked successful or failed only when a
+matching event provides that evidence. Missing, disabled or inaccessible logs
+remain explicitly unknown. The collector never runs a discovered script to
+test it.
+
 See the complete [output schema](docs/output-schema.md) and the checked-in
 [synthetic examples](examples/).
 
@@ -173,9 +184,30 @@ This writes manifests and task context without copying source files.
 
 ## Private Git hand-off
 
-The collector does not run Git. If version control is approved after review,
-use a private repository and scan the collected scripts for credentials first.
-See [safe Git hand-off](docs/safe-git-handoff.md).
+The default collector does not run Git. If version control is approved after
+review, use a private repository and scan the collected scripts for credentials
+first. See [safe Git hand-off](docs/safe-git-handoff.md).
+
+## Recurring private repository refresh
+
+For an approved, existing private Git checkout, the collector can refresh its
+stable folder tree and push only collector-owned paths:
+
+```powershell
+./src/Invoke-At0mFlowScriptAudit.ps1 `
+    -SearchPath C:\Scripts, D:\Automation `
+    -OutputPath D:\PrivateGit\PowerShell-Estate `
+    -Force `
+    -GitSync `
+    -Quiet `
+    -FailOnCollectionError
+```
+
+Configure the Git remote, upstream branch, author and non-interactive
+authentication before scheduling the command. The tool does not create or
+store those settings. It commits only `scripts/`, `manifests/` and the bundle
+`README.txt`, so unrelated repository content and staged work stay outside the
+collector commit. See [recurring private repository refresh](docs/recurring-private-repository.md).
 
 ## Take the estate further with At0mFlow
 
@@ -210,6 +242,7 @@ At0mFlow product code.
 - [SCCM deployment](docs/sccm.md)
 - [Output schema](docs/output-schema.md)
 - [Safe Git hand-off](docs/safe-git-handoff.md)
+- [Recurring private repository refresh](docs/recurring-private-repository.md)
 
 ## Contributing
 

SECURITY.md

@@ -17,5 +17,12 @@ The collector does not request, store or transmit passwords. A supplied
 `PSCredential` is passed only to PowerShell remoting for the current run. It is
 not written to the bundle.
 
-The project has no telemetry, hosted service, At0mFlow API client or automatic
-Git operations.
+The project has no telemetry, hosted service or At0mFlow API client. Git is
+disabled by default. `-GitSync` works only inside an existing working tree,
+uses the operator's existing non-interactive Git configuration and scopes its
+commit to the bundle's `scripts/`, `manifests/` and `README.txt` paths. It never
+initialises a repository, creates a remote or stores credentials.
+
+Task outcome evidence comes only from the previous hour of the local Windows
+Task Scheduler Operational event log. The collector does not run discovered
+scripts and does not interpret missing logs as success or failure.

docs/output-schema.md

@@ -9,6 +9,9 @@ One row represents one source path on one computer.
 | `ComputerName` | Windows computer that owned the source path. |
 | `OriginalPath` | Original script path. |
 | `CentralRelativePath` | Collision-safe path inside the bundle. |
+| `SourcePhysicalPath` | Explicit physical path of the source script. |
+| `CollectedCopyPath` | Absolute local path of the copied script. |
+| `RepositoryRelativePath` | Stable Git-relative path when the bundle is inside a Git working tree. |
 | `DiscoverySources` | `SearchPath`, `ScheduledTask`, or both. |
 | `ReferencedByTasks` | Scheduled task paths and names linked to the script. |
 | `DeclaredAuthor` | Optional `# Author:` or `# Created by:` header value. |
@@ -17,6 +20,9 @@ One row represents one source path on one computer.
 | `CreatedUtc` | Source creation time in UTC. |
 | `LastWriteUtc` | Source modification time in UTC. |
 | `SHA256` | Source content hash. |
+| `PreviousCollectedSHA256` | Hash of the prior collected copy when one existed. |
+| `CollectedSHA256` | Verified hash of the current collected copy. |
+| `CollectionChange` | `Added`, `Modified`, `Unchanged`, `NotCopied`, `Unavailable`, `CopyFailed` or `HashMismatch`. |
 | `CopyStatus` | `Copied`, `InventoryOnly`, `Missing`, `TooLarge`, `CopyFailed` or `HashMismatch`. |
 
 `DeclaredAuthor` and `FileOwner` are evidence fields, not proof of authorship.
@@ -30,6 +36,22 @@ It records task identity, state, description, principal, run level, logon type,
 action command, arguments, working directory, discovered script references,
 excluded references, triggers, conditions, last run, next run and last result.
 
+## `script-run-evidence.csv`
+
+One or more rows represent the available execution evidence for each discovered
+script. The time window is always the previous hour from the local
+`Microsoft-Windows-TaskScheduler/Operational` event log.
+
+`EvidenceStatus` distinguishes observed events from no scheduled-task
+reference, no matching event and an unavailable event log. `Outcome` is
+`Succeeded`, `Failed`, `SchedulerStatus` or `Unknown`. `Attribution` states
+whether the event matched an exact task action, only the task, or an ambiguous
+multi-action task.
+
+Observed rows include the event timestamp, ID, record ID, task, action, exact
+result code and a stable `EvidenceKey`. Consumers should deduplicate using that
+key and must not create failure events from `Unknown` rows.
+
 ## `collection-errors.csv`
 
 Every row includes a computer, collection stage, target and readable message.
@@ -41,8 +63,9 @@ suppressed count so a noisy access problem cannot create an unbounded CSV.
 
 ## `summary.json`
 
-Contains tool version, timestamps, output location, collection mode, counts,
-error status and the search roots used on each computer.
+Contains tool version, timestamps, output and optional Git working-tree
+locations, collection mode, counts, error status, one-hour evidence status and
+the search roots used on each computer.
 
 ## `TREE.txt`
 

docs/recurring-private-repository.md

@@ -0,0 +1,77 @@
+# Recurring private repository refresh
+
+Use this mode only after the collected material has been approved for a private
+Git repository.
+
+The collector can refresh the same stable folder tree on a schedule. Existing
+scripts are overwritten only when their SHA-256 content changes. The inventory
+records the physical source path, absolute collected-copy path, portable
+repository-relative path, previous hash, current hash and whether the copy was
+added, modified or unchanged.
+
+## Prepare the working tree
+
+Before using `-GitSync`, configure and test these items under the Windows
+identity that will run the scheduled task:
+
+1. An existing private Git working tree.
+2. An existing remote and upstream branch.
+3. Repository-local Git author name and email.
+4. Non-interactive authentication suitable for that private remote.
+5. Write permission to the collector output path.
+6. Read permission to the source paths and local Task Scheduler Operational
+   event log.
+
+The collector does not create, store or repair any of these settings.
+
+Task Scheduler history must already be enabled on each collected server. An
+administrator can enable it through Task Scheduler's **Enable All Tasks
+History** action or, after reviewing the change, with:
+
+```powershell
+wevtutil.exe sl Microsoft-Windows-TaskScheduler/Operational /e:true
+```
+
+Grant the scheduled identity only the local event-log access it needs, commonly
+through the built-in **Event Log Readers** group. The collector does not change
+event-log settings or local group membership.
+
+## Run once interactively
+
+```powershell
+./src/Invoke-At0mFlowScriptAudit.ps1 `
+    -SearchPath C:\Scripts, D:\Automation `
+    -OutputPath D:\PrivateGit\PowerShell-Estate `
+    -Force `
+    -GitSync
+```
+
+Review the resulting commit and confirm that the expected private remote
+received it before scheduling the command.
+
+## Schedule hourly
+
+Create a Windows Scheduled Task that runs the same command every hour. Use an
+approved service identity or managed execution identity that already has the
+required file, event-log and Git permissions. Add `-Quiet` for non-interactive
+output and `-FailOnCollectionError` when collection gaps should fail the task.
+
+Task Scheduler Operational evidence is always limited to the previous hour.
+This makes an hourly schedule a natural fit without turning the public tool into
+a resident agent.
+
+## Safety boundaries
+
+- The source scripts are read only. The collector never modifies or executes
+  them.
+- Git must already exist and be configured by the operator.
+- Credentials are never accepted or stored by the collector.
+- Git prompts are disabled so unattended runs fail clearly instead of hanging.
+- Only the selected output's `scripts/`, `manifests/` and `README.txt` are
+  committed.
+- Other files and staged changes are not included in the collector commit.
+- The one-hour event evidence comes only from Windows Event Viewer on each
+  collected computer. No At0mFlow service is contacted.
+
+For a reusable, repository-agnostic scheduled commit tool, see the public
+At0mFlow RepoSync project when it becomes available.

docs/safe-git-handoff.md

@@ -1,6 +1,6 @@
 # Safe Git hand-off
 
-The collector deliberately performs no Git operations.
+The collector performs no Git operation unless `-GitSync` is explicitly used.
 
 Before placing a bundle under version control:
 
@@ -25,6 +25,17 @@ git status
 Inspect the dry run and status before staging. This guide intentionally stops
 before adding a remote or pushing data.
 
+## Optional recurring sync
+
+After the repository, private remote, upstream branch, author and
+non-interactive authentication have been configured and tested by the operator,
+`-GitSync` may be used for a managed recurring refresh. It never initialises a
+repository or creates those settings.
+
+The commit is restricted to the selected bundle's `scripts/`, `manifests/` and
+`README.txt`. Other staged changes remain staged and are not included. See
+[recurring private repository refresh](recurring-private-repository.md).
+
 For mass repository organisation, automated SOP creation, cleanup planning and
 ongoing ownership tracking, use [At0mFlow](https://at0mflow.com/) after the
 bundle has been reviewed and approved.

docs/sccm.md

@@ -20,6 +20,9 @@ gaps are present.
   or another approved execution identity.
 - Writing locally and letting SCCM collect the bundle is often simpler than
   writing directly to a network share.
+- Reading one-hour execution evidence requires local access to the Task
+  Scheduler Operational event log. Grant only the event-log permission needed
+  by the approved SCCM execution identity.
 
 ## Detection and collection
 
@@ -29,6 +32,10 @@ Use `manifests/summary.json` as the completion artefact. Check its timestamp,
 Collect the whole output folder, not only the copied scripts. The CSVs provide
 the task and provenance context needed during estate review.
 
+`script-run-evidence.csv` contains only the previous hour of local Task
+Scheduler evidence. Disabled or inaccessible logging is recorded as unavailable
+evidence rather than success or failure.
+
 ## Reruns
 
 Use a new timestamped path for immutable audit evidence. `-Force` is available

docs/usage.md

@@ -48,6 +48,33 @@ Task folders under `\Microsoft\` are excluded by default:
 
 Use that option only when built-in task context is genuinely needed.
 
+## One-hour execution evidence
+
+When scheduled-task discovery is enabled, the collector reads only the previous
+hour from `Microsoft-Windows-TaskScheduler/Operational`. It records matching
+action completion and launch failure evidence in
+`manifests/script-run-evidence.csv`.
+
+The account running the collector must be allowed to read that local Windows
+event log. When several computers are collected over WinRM, the same check runs
+inside each remote session against that computer's local event log. Nothing is
+sent to At0mFlow or another service.
+
+Task Scheduler history must be enabled by an administrator before collection.
+The collector reports disabled or inaccessible logging but does not modify the
+event log or local permissions.
+
+The outcome rules are deliberately conservative:
+
+- result code `0` from event 201 is `Succeeded`;
+- a non-zero action result, task launch failure, logon failure or action start
+  failure is `Failed`;
+- Task Scheduler status constants are `SchedulerStatus`, not failures;
+- no matching event is `Unknown`, never a presumed success;
+- ambiguous multi-action task attribution is labelled in the CSV.
+
+The collector never executes a discovered script to determine its status.
+
 ## Default locations
 
 `-IncludeDefaultLocations` removes the standard Windows and Program Files path

examples/example-script-inventory.csv

@@ -1,2 +1,2 @@
-"ComputerName","OriginalPath","CentralRelativePath","DiscoverySources","ReferencedByTasks","DeclaredAuthor","FileOwner","LengthBytes","CreatedUtc","LastWriteUtc","SHA256","CopyStatus"
-"SERVER-EXAMPLE-01","C:\Scripts\Synthetic-NightlyReport.ps1","scripts/SERVER-EXAMPLE-01/C/Scripts/Synthetic-NightlyReport.ps1","SearchPath; ScheduledTask","\Operations\Synthetic nightly report","Example Automation Team","EXAMPLE\svc-script","241","2026-08-27T01:00:00.0000000Z","2026-08-27T02:00:00.0000000Z","8B7D44C0E3E2C188C785ABF311CD9A6D61F68D4E3911AD9731CF06F4DA6CD2CE","Copied"
+"ComputerName","OriginalPath","CentralRelativePath","SourcePhysicalPath","CollectedCopyPath","RepositoryRelativePath","DiscoverySources","ReferencedByTasks","DeclaredAuthor","FileOwner","LengthBytes","CreatedUtc","LastWriteUtc","SHA256","PreviousCollectedSHA256","CollectedSHA256","CollectionChange","CopyStatus"
+"SERVER-EXAMPLE-01","C:\Scripts\Synthetic-NightlyReport.ps1","scripts/SERVER-EXAMPLE-01/C/Scripts/Synthetic-NightlyReport.ps1","C:\Scripts\Synthetic-NightlyReport.ps1","D:\PrivateGit\PowerShell-Estate\scripts\SERVER-EXAMPLE-01\C\Scripts\Synthetic-NightlyReport.ps1","scripts/SERVER-EXAMPLE-01/C/Scripts/Synthetic-NightlyReport.ps1","SearchPath; ScheduledTask","\Operations\Synthetic nightly report","Example Automation Team","EXAMPLE\svc-script","241","2026-08-27T01:00:00.0000000Z","2026-08-27T02:00:00.0000000Z","8B7D44C0E3E2C188C785ABF311CD9A6D61F68D4E3911AD9731CF06F4DA6CD2CE","7AA13CE9080A15C502AF793154347B443708F6BE8AFC45FBAE69731EAF9B3E11","8B7D44C0E3E2C188C785ABF311CD9A6D61F68D4E3911AD9731CF06F4DA6CD2CE","Modified","Copied"