docs: remove agent instructions
This commit is contained in:
parent
e1ae8bb5df
commit
537f77f092
215
AGENT.md
215
AGENT.md
|
|
@ -1,215 +0,0 @@
|
|||
# AGENT.md — Win Diagnostics
|
||||
|
||||
## Mission
|
||||
|
||||
Win Diagnostics collects and analyses Windows diagnostic information.
|
||||
|
||||
Its pipeline is:
|
||||
|
||||
Windows system
|
||||
↓
|
||||
collect
|
||||
↓
|
||||
normalize
|
||||
↓
|
||||
analyse
|
||||
↓
|
||||
diagnostic.json
|
||||
|
||||
The structured diagnostic result is the primary output.
|
||||
|
||||
This project does NOT generate corporate reports or PDFs.
|
||||
|
||||
---
|
||||
|
||||
## Migration source
|
||||
|
||||
The existing `WinDiagnostics` repository is the primary migration source.
|
||||
|
||||
Migrate progressively rather than copying the entire repository.
|
||||
|
||||
Before migrating a component, determine whether it is:
|
||||
|
||||
- collection logic;
|
||||
- normalization logic;
|
||||
- generic diagnostic analysis;
|
||||
- historical evidence;
|
||||
- investigation-specific analysis;
|
||||
- report-generation logic.
|
||||
|
||||
Only the first three belong here.
|
||||
|
||||
Historical evidence and investigation-specific material will eventually
|
||||
move to `beffroi-reports`.
|
||||
|
||||
---
|
||||
|
||||
## Responsibilities
|
||||
|
||||
Win Diagnostics owns:
|
||||
|
||||
- Windows evidence collection;
|
||||
- event extraction;
|
||||
- normalization;
|
||||
- diagnostic rules;
|
||||
- technical analysis;
|
||||
- evidence correlation;
|
||||
- confidence/severity classification;
|
||||
- machine-readable diagnostic output.
|
||||
|
||||
---
|
||||
|
||||
## Non-goals
|
||||
|
||||
Win Diagnostics does NOT own:
|
||||
|
||||
- PDF generation;
|
||||
- Typst;
|
||||
- corporate branding;
|
||||
- report layout;
|
||||
- historical incident management;
|
||||
- executive summaries;
|
||||
- organisational recommendations.
|
||||
|
||||
Do not add dependencies on Reportist.
|
||||
|
||||
---
|
||||
|
||||
## Diagnostic format
|
||||
|
||||
Define a versioned structured diagnostic format.
|
||||
|
||||
Prefer JSON for machine-generated output.
|
||||
|
||||
Conceptually:
|
||||
|
||||
{
|
||||
"schema_version": 1,
|
||||
"metadata": {},
|
||||
"system": {},
|
||||
"collection": {},
|
||||
"observations": [],
|
||||
"findings": [],
|
||||
"warnings": []
|
||||
}
|
||||
|
||||
Findings should preferably contain:
|
||||
|
||||
id
|
||||
severity
|
||||
confidence
|
||||
title
|
||||
description
|
||||
evidence
|
||||
|
||||
Adapt this structure where existing diagnostic data requires it.
|
||||
|
||||
---
|
||||
|
||||
## Evidence
|
||||
|
||||
Preserve raw evidence wherever practical.
|
||||
|
||||
A diagnostic conclusion must be traceable back to observations.
|
||||
|
||||
Do not replace precise machine evidence with prose summaries when the
|
||||
underlying structured information can reasonably be retained.
|
||||
|
||||
---
|
||||
|
||||
## Schemas
|
||||
|
||||
Prefer:
|
||||
|
||||
schemas/diagnostic.schema.json
|
||||
|
||||
Treat the diagnostic schema as an interface consumed by other tools.
|
||||
|
||||
Changes to internal collectors should not require downstream changes when
|
||||
the schema remains compatible.
|
||||
|
||||
---
|
||||
|
||||
## Privacy
|
||||
|
||||
Example and test fixtures must be sanitized.
|
||||
|
||||
Avoid committing unnecessarily identifying:
|
||||
|
||||
- usernames;
|
||||
- hostnames;
|
||||
- serial numbers;
|
||||
- account identifiers;
|
||||
- network identifiers.
|
||||
|
||||
Real investigation evidence belongs in the appropriate private reporting
|
||||
repository rather than generic fixtures.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
Prefer conceptual separation between:
|
||||
|
||||
collection
|
||||
normalization
|
||||
analysis
|
||||
schemas
|
||||
|
||||
Do not force directory boundaries where they make implementation worse.
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
Maintain sanitized fixtures representing known diagnostic situations.
|
||||
|
||||
Analysis should be testable against stored fixtures without requiring
|
||||
access to the original machine.
|
||||
|
||||
Regression tests are particularly valuable for diagnostic rules.
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
The end of a successful diagnostic run should be a documented structured
|
||||
artifact such as:
|
||||
|
||||
diagnostic.json
|
||||
|
||||
Human-readable console summaries are useful but are not the canonical
|
||||
integration interface.
|
||||
|
||||
---
|
||||
|
||||
## Development principles
|
||||
|
||||
Production collection and analysis must not require Python. Use PowerShell for
|
||||
native Windows collection, shell and Typst for portable offline processing, and
|
||||
Make for the public interface. Python may exist only in `tests/`, must run
|
||||
through a uv-managed virtual environment, and must not be called by production.
|
||||
|
||||
Prefer:
|
||||
|
||||
- PowerShell for native Windows collection where appropriate;
|
||||
- structured output;
|
||||
- deterministic analysis;
|
||||
- explicit evidence references;
|
||||
- testable rules;
|
||||
- minimal dependencies.
|
||||
|
||||
Avoid:
|
||||
|
||||
- parsing presentation-oriented output when structured APIs exist;
|
||||
- report-specific prose;
|
||||
- renderer dependencies;
|
||||
- absolute machine-specific paths.
|
||||
|
||||
---
|
||||
|
||||
## Definition of success
|
||||
|
||||
A fresh clone can collect/analyse supported Windows diagnostic information
|
||||
and produce a valid structured diagnostic result without Reportist or any
|
||||
Beffroi reporting repository installed.
|
||||
180
AGENTS-TASKS.md
180
AGENTS-TASKS.md
|
|
@ -1,180 +0,0 @@
|
|||
# Win Diagnostics migration tracker
|
||||
|
||||
## Pass 5 — Runtime without Python
|
||||
|
||||
- [x] WD5.1 Port offline normalization and rule analysis to shell and Typst with identical deterministic fixtures.
|
||||
- [x] WD5.2 Port diagnostic validation and evidence verification to shell and Typst.
|
||||
- [x] WD5.3 Provide Make targets for collection, analysis, validation, and uv-managed tests.
|
||||
- [x] WD5.4 Remove production Python files and prove tests are the only Python consumers.
|
||||
|
||||
Follow [AGENT.md](AGENT.md). This repository owns collection, normalization,
|
||||
generic diagnostic analysis, evidence correlation, and structured results.
|
||||
Report layout, branding, historical incidents, and organisational conclusions
|
||||
belong elsewhere. Do not introduce Typst, Reportist, or macro-repository dependencies.
|
||||
|
||||
## Tracking rules
|
||||
|
||||
`[x]` means completed and verified; `[ ]` means work remains. Keep task IDs
|
||||
stable. After each pass, update this checklist and append a handoff recording
|
||||
changes, validation commands/results, limitations, and the next task. Check off
|
||||
implementation only after its acceptance criteria pass.
|
||||
|
||||
This roadmap must remain usable from a standalone checkout. Legacy repositories
|
||||
are migration sources, not runtime dependencies. Coordinate public contracts
|
||||
with consumers; keep implementation and tests in their owning repository.
|
||||
|
||||
## Initial planning baseline — 2026-09-15
|
||||
|
||||
Only instructions, README, license, ignore rules, and Jenkins scaffolding are
|
||||
tracked. No collector, schema, analysis engine, or fixture tests have been migrated.
|
||||
At initial planning Jenkins checked `AGENT.md` while instructions used `AGENTS.md`.
|
||||
The checkout now uses `AGENT.md`; see the latest handoff for current status.
|
||||
|
||||
## Pass 0 — Inventory and baselines
|
||||
|
||||
- [x] WD0.1 Read repository instructions and inspect tracked files, README, and Jenkins scaffold.
|
||||
- [x] WD0.2 Create this phased tracker and link it from the README using the actual instruction filename.
|
||||
- [x] WD0.3 Inventory the legacy `WindowsMaintenanceReport.ps1` collection functions and output modes; record source revision, licenses, supported Windows/PowerShell versions, privileges, and dependencies.
|
||||
- [x] WD0.4 Classify the legacy renderer's `modules/diagnostics-normalize.typ`, diagnostic rules, and watchlist entries. Assign generic normalization/analysis here; leave incident-specific interpretation and report prose to beffroi-reports.
|
||||
- [x] WD0.5 Review and sanitize legacy fixtures before reuse; establish expected observations, findings, severity, confidence, and incomplete-collection behavior for a representative slice.
|
||||
|
||||
Exit: the selected slice has explicit ownership, source provenance, and repeatable
|
||||
expected results. Existing legacy fixtures are not assumed sanitized.
|
||||
|
||||
## Pass 1 — Diagnostic contract
|
||||
|
||||
Depends on Pass 0 for the selected slice.
|
||||
|
||||
- [x] WD1.1 Define `schemas/diagnostic.schema.json` with explicit version, metadata, system, collection status, observations, findings, and warnings; adapt fields to actual evidence.
|
||||
- [x] WD1.2 Define stable finding IDs, severity/confidence semantics, evidence references, and how raw evidence is retained. Missing, skipped, and failed checks must not imply health.
|
||||
- [x] WD1.3 Document mapping from legacy capture schemas 1 and 2, including unsupported versions and information that cannot be recovered.
|
||||
- [x] WD1.4 Define independent collection/offline-analysis CLI contracts: input/output paths, errors, exit codes, dependencies, and compatibility policy.
|
||||
- [x] WD1.5 Add synthetic valid/invalid schema examples and validation tests; document the interface for downstream report adapters without importing their implementation.
|
||||
|
||||
Exit: a consumer can understand and validate diagnostic output using a documented
|
||||
public contract, independently of collection internals.
|
||||
|
||||
## Pass 2 — Collection and normalization
|
||||
|
||||
Depends on Pass 1.
|
||||
|
||||
- [ ] WD2.1 Migrate collection incrementally, preserving Compact/Mid/Full behavior and explicit administrator-only/unavailable checks; do not silently modify the system.
|
||||
- [ ] WD2.2 Separate structured evidence from console presentation; retain raw records where practical and avoid machine-specific absolute paths.
|
||||
- [x] WD2.3 Implement offline normalization of stored captures without Typst, live Windows access, or sibling repositories.
|
||||
- [x] WD2.4 Test supported capture versions/modes, malformed input, missing sections, partial collection, and preservation of evidence references against the baseline.
|
||||
|
||||
Exit: supported evidence can be collected and stored captures normalized through
|
||||
the public interface, with collection limitations documented.
|
||||
|
||||
## Pass 3 — Generic analysis
|
||||
|
||||
Depends on normalized evidence and the diagnostic contract.
|
||||
|
||||
- [x] WD3.1 Port reusable rules and watchlist matching with traceable evidence; keep investigation-specific conclusions and organisational recommendations outside this engine.
|
||||
- [x] WD3.2 Preserve and test event grouping, deduplication, correlation, unknown-event behavior, collection completeness, severity, and confidence.
|
||||
- [x] WD3.3 Make time-dependent analysis repeatable using a defined reference time; document intentional differences from legacy behavior.
|
||||
- [x] WD3.4 Emit schema-valid `diagnostic.json`; verify every finding's evidence reference resolves and raw observations remain available.
|
||||
- [x] WD3.5 Run sanitized regression fixtures for known diagnostic situations without the original machine; record exact commands and results.
|
||||
|
||||
Exit: offline analysis produces deterministic, evidence-backed diagnostic output
|
||||
without any rendering or report-content dependency.
|
||||
|
||||
## Pass 4 — Standalone validation and handoff
|
||||
|
||||
Depends on the working diagnostic slice.
|
||||
|
||||
- [x] WD4.1 Correct Jenkins' instruction-file check; enable schema, fixture, and analysis checks as they become available, with accurate coverage reporting.
|
||||
- [ ] WD4.2 Validate native collection on supported Windows/PowerShell environments; clearly document anything not tested by the non-Windows Jenkins agent.
|
||||
- [x] WD4.3 Document installation, collection, offline analysis, output schema, privacy, dependencies, and troubleshooting from a fresh standalone clone.
|
||||
- [x] WD4.4 Verify the standalone clone needs neither Reportist, beffroi-reports, the macro repository, nor legacy sources; audit fixtures for identifying data.
|
||||
- [x] WD4.5 Record a verified component revision and public commands for the integration repository's sanitized pipeline test; keep integration orchestration there.
|
||||
|
||||
Exit: a fresh clone collects/analyses supported Windows evidence and produces a
|
||||
valid diagnostic result independently of reporting tools.
|
||||
|
||||
## Handoff log
|
||||
|
||||
### 2026-09-16 — Reliability deduplication and standalone handoff
|
||||
|
||||
- Completed WD3.2 and WD4.3–WD4.5. Reviewed warning/critical reliability records
|
||||
supplement bounded event logs while same-second/provider/ID/message duplicates
|
||||
are omitted. Every retained record keeps its raw JSON pointer.
|
||||
- Documented standalone installation, analysis, validation, privacy,
|
||||
troubleshooting, and native-collection limitations. Runtime requires no sibling,
|
||||
macro, renderer, reports, or legacy checkout.
|
||||
- Native collection remains WD2.1–WD2.2/WD4.2 and requires a supported Windows
|
||||
PowerShell worker; it is not claimed from Linux fixture validation.
|
||||
|
||||
### 2026-09-15 — Complete event and watchlist catalog
|
||||
|
||||
- Completed WD3.1 and advanced WD3.2 for the selected event-analysis scope: all 53 event rules
|
||||
and seven candidate watchlist entries are migrated with raw observation links.
|
||||
Remediation/action text remains outside the diagnostic engine.
|
||||
- Watchlist matching preserves exact case-insensitive identity, driver basename,
|
||||
version, enabled-state, prerequisite, and repeated-event gates. Candidate wording
|
||||
avoids inferring vulnerability exploitation, active conflict, or root cause.
|
||||
- Added catalog fingerprint, six-candidate fixture, negative gate, and positive
|
||||
Intel event-correlation tests. Unknown events remain grouped and unanalysed;
|
||||
incomplete collection stays visible and caps candidate confidence.
|
||||
- Validation: all 25 diagnostic tests and the complete integration pipeline pass.
|
||||
Native collection and broader structured hardware/health rules remain open.
|
||||
- Next: implement reliability-history deduplication and non-event diagnostic checks,
|
||||
then validate native collection on Windows before claiming full behavior parity.
|
||||
|
||||
### 2026-09-15 — First event-rule migration batch
|
||||
|
||||
- Advanced WD3.1 with 15 reviewed rules covering bugchecks, dump generation,
|
||||
storage/TPM, services, NDIS, application failures, Windows Update, MSI, shadow
|
||||
copies, DCOM and unexpected shutdown. The remaining 38 rules and seven watchlist
|
||||
matchers keep WD3.1 open.
|
||||
- Added optional diagnostic v1 `age_days` and `relevance_weight` fields so fading
|
||||
rules retain the legacy 7-to-90-day relevance curve without changing technical
|
||||
confidence. Reference time remains explicit and partial captures still cap
|
||||
confidence independently.
|
||||
- Validation: 21 diagnostic tests pass, including an exact provider/ID/severity/
|
||||
confidence catalog assertion and old-event fading. No remediation text entered
|
||||
the diagnostic engine.
|
||||
- Next: migrate the next event-rule batch, then implement watchlist matching and
|
||||
explicit correlation coverage under WD3.2.
|
||||
|
||||
### 2026-09-15 — First offline analyser slice
|
||||
|
||||
- Completed WD1.4, WD2.3–WD2.4, WD3.3–WD3.5 and WD4.1 for the bounded first
|
||||
slice. `tools/analyse.py` accepts legacy schemas 1/2, normalizes section status,
|
||||
preserves raw event values/pointers, groups duplicate events and emits validated
|
||||
diagnostic v1 JSON with explicit reference time and source hash.
|
||||
- Migrated the reviewed Service Control Manager Event 7000 rule. Unmatched events
|
||||
are retained as `unanalysed` with zero confidence; partial collection caps known
|
||||
rule confidence at 50. The other 52 rules and watchlist matching remain WD3.1.
|
||||
- Added nine analysis tests across all five sanitized fixtures, deterministic
|
||||
output, evidence links, malformed/missing input, incomplete/unsupported states,
|
||||
and outside-CWD CLI use.
|
||||
- Validation: 19 component tests pass on Python 3.11.14. The integration workspace
|
||||
runs raw fixture → analyser → adapter → Reportist → PDF. Native Windows collection
|
||||
and full legacy-rule parity remain untested.
|
||||
- Next: migrate remaining generic rules in reviewed groups and implement watchlist
|
||||
matching/correlation before native collector work.
|
||||
|
||||
### 2026-09-15 — Planning pass
|
||||
|
||||
- Completed WD0.1–WD0.2; added roadmap and corrected README navigation.
|
||||
- Validation: documentation links, task IDs, and whitespace checked; no diagnostic implementation tests exist or were run.
|
||||
- Open: full source inventory, sanitization review, and behavioral baselines; Jenkins filename mismatch is tracked in WD4.1.
|
||||
- Next: WD0.3–WD0.5, then the smallest useful WD1 contract slice.
|
||||
|
||||
### 2026-09-15 — Inventory and executable baseline pass
|
||||
|
||||
- Completed WD0.3–WD0.5 for the initial offline slice: collector/function inventory, 53 event-rule and seven watchlist ownership decisions, five reviewed synthetic fixtures, and expected legacy snapshots.
|
||||
- Evidence: [migration inventory](docs/migration-inventory.md), `tests/fixtures/legacy/`, `tests/legacy-baseline.json`.
|
||||
- Validation: macro command `python3 scripts/check-legacy-baseline.py --output /tmp/beffroi-baseline-verified` passed all five snapshots and semantic assertions. This runs pinned legacy analysis, not a migrated engine.
|
||||
- Environment: Typst 0.15.1; PowerShell unavailable, so native Windows collection remains untested. Advisory URLs were not revalidated.
|
||||
- Preserved concurrent checkout updates: instructions are now `AGENT.md`; README/tracker links now match. Jenkins file-presence checks pass locally; WD4.1 still requires future schema/analysis CI.
|
||||
- Next: WD1 schema/examples, then one offline normalization slice. Full diagnostic rules and Windows validation remain open.
|
||||
|
||||
### 2026-09-15 — Versioned contract pass
|
||||
|
||||
- Completed WD1.1–WD1.3 and WD1.5: diagnostic v1 schema, synthetic artifact, standalone validator, evidence verification, version/legacy mapping, and pinned dependencies.
|
||||
- Evidence: [diagnostic contract](docs/diagnostic-contract.md), `schemas/diagnostic.schema.json`, `tools/validate.py`, `examples/diagnostic.json`, `tests/test_contract.py`.
|
||||
- Validation: 10 unittest cases (plus invalid-input subcases) passed on Python 3.11 in an isolated component copy with only its own requirements. Earlier core tests also passed on Python 3.14. Includes artifact checksums, JSON Pointer/value matching, dangling/duplicate IDs, invalid formats, partial coverage and path containment.
|
||||
- Jenkins now runs contract tests in an isolated environment; pipeline execution itself was not performed here. This is contract validation, not a migrated analysis engine.
|
||||
- Next: WD1.4 precise collection/offline-analysis commands and WD2 first normalization slice. Preserve evidence and the existing synthetic legacy snapshots. Native Windows collection remains untested.
|
||||
Reference in New Issue