initial

Author: denisecase

.agent/ao-config-python.toml

@@ -0,0 +1,75 @@
+# Domain configuration: PTAT sensor behavior and anomaly expectations
+
+[domain]
+name = "PTAT temperature-frequency sensor array"
+primary_measurement = "frequency_hz"
+derived_measurement = "temperature_celsius"
+
+[domain.model]
+relationship = "frequency_hz = nominal_frequency_at_25c_hz + sensitivity_hz_per_kelvin * (temperature_celsius - 25)"
+
+[domain.ptat]
+sensitivity_hz_per_kelvin = 512.0    # typical observed value
+linearity_percent = 99.993
+operating_range_celsius = [-30, 70]
+nominal_frequency_at_25c_hz = 100000
+
+[domain.anomalies]
+dropout = "sensor reports null or zero; not a valid reading"
+drift_offset_percent = 2.0
+drift_rate_percent_per_interval = 0.5
+nonlinearity = "deviation from linear fit > 0.1% across range"
+spike = "single-sample deviation > 5 sigma from rolling mean"
+
+[anomaly_semantics]
+# gradual deviation over time
+drift = "sustained directional deviation beyond expected noise"
+# abrupt change
+spike = "sudden discontinuity inconsistent with prior values"
+# cross-sensor inconsistency
+divergence = "one sensor deviates significantly from correlated peers"
+# flatline or stuck sensor
+stuck = "no meaningful variation over time"
+
+[domain.baseline]
+reference_temperature_celsius = 25
+baseline_definition = "first stable segment or calibration point"
+
+[domain.batch]
+expected_batch_size = 1000
+sampling_rate_hz = 10
+calibration_check_interval_samples = 100
+
+[system]
+name = "PTAT sensor system"
+description = "Sensors where output is proportional to absolute temperature"
+
+[expected_relationships]
+# PTAT behavior: value increases approximately linearly with temperature
+ptat_linear = true
+# sensors in a group should show correlated behavior
+multi_sensor_expected_correlation = "high"
+max_inter_sensor_deviation_percent = 2.0
+# small noise is expected
+noise_present = true
+
+[constraints]
+# acceptable variation (relative or absolute tolerance may be refined)
+max_deviation_percent = 5.0
+# drift should not exceed this rate without being flagged
+max_drift_rate = 0.5
+
+[suspicious_patterns]
+# patterns that may pass basic tests but indicate issues
+passing_but_suspicious = [
+  "consistent bias within tolerance but trending",
+  "slow monotonic drift",
+  "sensor deviates while remaining within absolute bounds",
+  "increasing variance over time",
+]
+
+[reporting]
+# agent must explicitly call out suspicious cases
+require_suspicion_reporting = true
+# explanations must reference domain expectations
+require_domain_reference = true

.agent/ao-config.toml

@@ -0,0 +1,78 @@
+# ============================================================
+# .gitattributes (Keep files consistent across operating systems)
+# ============================================================
+
+# REQ.UNIVERSAL: All professional GitHub project repositories MUST include .gitattributes.
+# WHY: Ensure consistent line endings, diff behavior, and file classification
+# across Windows, macOS, and Linux environments.
+# ALT: Repository may omit .gitattributes ONLY if equivalent normalization is
+# enforced reliably by tooling and CI (rare and fragile).
+# CUSTOM: Update file-type rules only when introducing new languages,
+# binary artifacts, or documentation formats.
+# NOTE: Rules are ordered by impact and generality, not alphabetically.
+# Git attributes are documented at https://git-scm.com/docs/gitattributes
+
+# === Core defaults (always apply) ===
+
+# WHY: Auto-detect text files and normalize line endings to avoid cross-platform drift.
+* text=auto
+
+
+# === Programming languages and scripts ===
+
+# WHY: Python and shell scripts must use LF for CI/CD, Linux environments, and containers.
+*.py    text eol=lf
+*.sh    text eol=lf
+
+# WHY: PowerShell convention on Windows uses CRLF.
+*.ps1   text eol=crlf
+
+
+# === Markup and documentation ===
+
+# WHY: Documentation and markup files use LF; standard for cross-platform tooling.
+*.md    text eol=lf
+
+
+# === Configuration and structured text ===
+
+# WHY: Configuration and structured text formats use LF for stable diffs.
+*.json    text eol=lf
+*.jsonc   text eol=lf
+*.jsonl   text eol=lf
+*.toml    text eol=lf
+*.yaml    text eol=lf
+*.yml     text eol=lf
+
+
+# === Databases (binary) ===
+
+# WHY: Database files are binary; prevent text normalization and meaningless diffs.
+*.db       binary
+*.sqlite   binary
+*.sqlite3  binary
+
+
+# === Compressed artifacts (binary) ===
+
+# WHY: Compressed artifacts are binary; prevent text normalization.
+*.gz    binary
+*.tar   binary
+*.tgz   binary
+*.zip   binary
+*.7z    binary
+
+
+# === Log files (binary) ===
+
+# WHY: Log files are typically large; prevent text normalization.
+*.log         binary
+project.log   binary
+
+
+# === GitHub metadata and UI ===
+
+# WHY: Exclude documentation and tests from GitHub language statistics.
+docs/**         linguist-documentation
+tests/**        linguist-documentation
+evaluation/**   linguist-documentation

.agent/ao-domain.toml

@@ -0,0 +1,109 @@
+# ============================================================
+# .gitignore (Keep unnecessary files out of the repository)
+# ============================================================
+
+# REQ.UNIVERSAL: All professional GitHub project repositories MUST include .gitignore.
+# WHY: Prevent committing generated artifacts, local state, secrets, and OS-specific files.
+# ALT: Repository may customize ignores, but MUST preserve universal safety rules.
+# CUSTOM: Logs may be temporarily committed for verification; keep ignored for
+# production use and security.
+
+
+# === Private local evaluation scenarios ===
+
+# WHY: Users test ACS against proprietary codebases by adding scenarios here.
+# This directory is intentionally gitignored so private test cases are never
+# committed or pushed. Clone, do not fork, to preserve upstream pull access.
+evaluation/local/
+
+
+# === Universal (all projects, all languages) ===
+
+# WHY: Logs are useful during debugging and verification.
+# ALT: Comment if logs must be inspected or validated.
+*.log
+logs/
+PRIVATE_NOTES.md
+PRIVATE-NOTES.md
+
+# WHY: Temporary and swap files are machine-local noise and create meaningless diffs.
+*.swo
+*.swp
+*.tmp
+*~
+
+
+# === VS Code ===
+
+# WHY: Ignore editor state while allowing a shared baseline configuration.
+#.vscode/
+
+# WHY: Commit recommended extensions (opt-in) for consistent development experience.
+# NOTE: Share recommendations, not personal editor styles or preferences.
+!.vscode/extensions.json
+!.vscode/settings.json
+
+
+# === OS-specific files (macOS / Windows) ===
+
+# WHY: OS-generated metadata files should never be tracked.
+.AppleDouble
+.DS_Store
+.LSOverride
+Icon\r
+._*
+.Spotlight-V100/
+.Trashes
+desktop.ini
+ehthumbs.db
+Thumbs.db
+
+
+# === Editors / IDEs (non-VS Code) ===
+
+# WHY: IDE metadata is machine-local and should not be tracked.
+*.code-workspace
+.idea/
+
+
+# === Environment variables and secrets ===
+
+# WHY: Never commit credentials or environment-specific configuration.
+.env
+.env.*
+*.env
+
+
+# === Documentation build output ===
+
+# WHY: Static site build output is generated; kept in case MkDocs is added.
+site/
+
+
+# === Generic caches ===
+
+# WHY: Generic caches are machine-local and should not be tracked.
+.cache/
+
+
+# === Python (evaluation scripts) ===
+
+# WHY: Virtual environments are machine-local and reproducible.
+.venv/
+venv/
+
+# REQ.PYTHON: Do NOT git ignore uv.lock. Commit it and use it in CI/CD pipelines.
+
+# WHY: Python bytecode is generated.
+__pycache__/
+*.pyc
+*.pyd
+*.pyo
+
+# WHY: Tooling caches should not be tracked.
+.coverage
+.coverage.*
+.mypy_cache/
+.pytest_cache/
+.pytype/
+.ruff_cache/

.gitattributes

@@ -0,0 +1,5 @@
+{
+  "MD013": false,
+  "MD033": false,
+  "MD041": false
+}

.gitignore

@@ -0,0 +1,109 @@
+# ============================================================
+# .pre-commit-config.yaml (Markdown Hygiene)
+# ============================================================
+# VARIANT: markdown-hygiene
+# SOURCE: https://github.com/denisecase/templates
+#
+# REQ: Documentation-only repos MAY include a .pre-commit-config.yaml for repo hygiene (optional).
+# WHY: Keep Markdown diffs clean across OSes and prevent common documentation commit errors.
+#
+# OBS: These hooks use and do NOT override:
+#   - .editorconfig (whitespace / indentation)
+#   - .gitattributes (EOL normalization)
+#   - pyproject.toml (Python tool settings)
+#
+# OPTIONAL LOCAL USAGE (no repo venv required):
+#   You must have uv installed locally.
+#   Run these commands ONCE in from the repo root to enable pre-commit:
+#
+#   uv self update
+#   uvx pre-commit install
+#   uvx pre-commit run --all-files
+#
+# This enables the pre-commit hooks for this project repo.
+# ALL subsequent commits in this repo will AUTOMATICALLY run these
+# pre-commit hooks, after `git add` and before `git commit`.
+#
+# NOTE: enabling pre-commit is optional. It is not needed to clone or commit.
+
+exclude: |
+  (?x)^(
+    \.DS_Store|
+    \.coverage|
+    \.ipynb_checkpoints/|
+    \.mypy_cache/|
+    \.nox/|
+    \.pytest_cache/|
+    \.ruff_cache/|
+    \.tox/|
+    \.venv/|
+    .*\.(egg-info)/|
+    .*\.log|
+    __pycache__/|
+    _minted.*/|
+    build/|
+    coverage\.xml|
+    dist/|
+    htmlcov/|
+    lake-packages/|
+    node_modules/|
+    out/|
+    site/
+  )
+
+repos:
+  # === REPO: PRE-COMMIT HOOKS (cross-platform, zero config) ===
+  #
+  # These hooks prevent problems that show up later as:
+  #   - mysterious diffs
+  #   - broken builds on another OS
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      # === PRE-COMMIT: NORMALIZE FILE FORMATTING ===
+
+      - id: trailing-whitespace
+        name: A1) Clean trailing whitespace (per .editorconfig)
+        args: [--markdown-linebreak-ext=md] # Preserves markdown double-space line breaks
+
+      - id: end-of-file-fixer
+        name: A2) End files with a newline (per .gitattributes)
+
+      - id: mixed-line-ending
+        name: A3) Normalize line endings to LF before linters
+        args: [--fix=lf] # OBS: Windows working copies may be CRLF.
+
+      #  === PRE-COMMIT: CHECK DATA FILE FORMATS ===
+
+      - id: check-json
+        name: B1) Validate JSON syntax (except .vscode/)
+        # WHY: VSCode settings may include comments, which are non-standard JSON.
+        exclude: ^\.vscode/.*\.json$
+
+      - id: check-toml
+        name: B2) Validate TOML syntax
+
+      - id: check-yaml
+        name: B3) Validate YAML syntax
+        files: \.(yml|yaml)$
+        # WHY:
+        #    VS Code config files are editor-specific
+        #    mkdocs.yml may use YAML anchors not supported by the checker
+        exclude: ^(\.vscode/|mkdocs\.ya?ml$)
+
+      # === PRE-COMMIT:CHECK FOR COMMON PROBLEMS ===
+
+      - id: check-added-large-files
+        name: C1) Prevent accidental commits of large binaries
+        args: [--maxkb=500]
+
+      - id: check-merge-conflict
+        name: C2) Prevent committing merge conflicts
+
+      - id: check-case-conflict
+        name: C3) Check for filename case conflicts
+
+# === GLOBAL SETTINGS ===
+# ALT: Set fail_fast to true to stop at first failure.
+fail_fast: false # Run all hooks even if one fails

.markdownlint.json

@@ -0,0 +1 @@
+3.14

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+# ============================================================
+# .yamllint.yml (Keep YAML files clean and consistent)
+# ============================================================
+
+# WHY: Enforce YAML correctness (.yamllint.yml) without arbitrary style constraints.
+# OBS: Default yamllint rules conflict with GitHub Actions YAML.
+#      Line length, document start, truthy, and comment spacing are intentionally disabled.
+
+extends: default
+
+rules:
+  line-length: disable
+  document-start: disable
+  truthy: disable
+  comments: disable