AGENTS.md

AGENTS.md

Agent capabilities and integration guide for digital.vasic.filesystem.

Module Identity

• Module: digital.vasic.filesystem
• Language: Go 1.24+
• Type: Library (no executable binary)
• Purpose: Unified multi-protocol filesystem abstraction

What This Module Provides

This module exposes a single client.Client interface that normalizes filesystem operations across five protocols:

Protocol	Package	Platform	Backend
SMB/CIFS	pkg/smb	All	go-smb2 library
FTP	pkg/ftp	All	jlaffaye/ftp library
NFS	pkg/nfs	Linux only	syscall.Mount
WebDAV	pkg/webdav	All	net/http (raw HTTP)
Local	pkg/local	All	os package

Agent Capabilities

Creating Clients

Agents that need filesystem access should use factory.DefaultFactory to create clients:

import (
    "digital.vasic.filesystem/pkg/client"
    "digital.vasic.filesystem/pkg/factory"
)

f := factory.NewDefaultFactory()
c, err := f.CreateClient(&client.StorageConfig{
    Protocol: "local",
    Settings: map[string]interface{}{
        "base_path": "/data/media",
    },
})

Available Operations

All clients support the full client.Client interface:

• Connection lifecycle: Connect, Disconnect, IsConnected, TestConnection
• File I/O: ReadFile, WriteFile, GetFileInfo, FileExists, DeleteFile, CopyFile
• Directory management: ListDirectory, CreateDirectory, DeleteDirectory
• Introspection: GetProtocol, GetConfig

Protocol-Specific Configuration

Each protocol expects specific keys in StorageConfig.Settings:

SMB: host, port (default 445), share, username, password, domain (default "WORKGROUP")

FTP: host, port (default 21), username, password, path

NFS: host, path, mount_point, options (default "vers=3")

WebDAV: url, username, password, path

Local: base_path

Integration Patterns

Connection Management

All clients require explicit Connect() before use. Always defer Disconnect():

ctx := context.Background()
if err := c.Connect(ctx); err != nil {
    return err
}
defer c.Disconnect(ctx)

Error Handling

• All methods return wrapped errors with %w formatting
• Connection-related errors indicate network or authentication failures
• File-not-found is returned as a wrapped OS-level or protocol-level error
• FileExists() returns (false, nil) for missing files rather than an error

Context Support

All operations accept context.Context for cancellation and deadline propagation.

Extending the Module

Adding a New Protocol

1. Create pkg/<protocol>/ with a Config struct and Client type
2. Implement all 15 methods of client.Client
3. Add a var _ client.Client = (*Client)(nil) compile-time check
4. Add a case to factory.DefaultFactory.CreateClient()
5. Add the protocol name to factory.DefaultFactory.SupportedProtocols()
6. If platform-specific, use build tags following the NFS pattern (nfs_linux.go / nfs_other.go)

Testing

go test ./...                          # all tests
go test -v ./pkg/local/                # local adapter (full coverage, no external deps)
go test -v ./pkg/factory/              # factory + helpers
go test -v ./pkg/client/               # interface struct tests

The local package has the most comprehensive test suite since it requires no external services. SMB, FTP, WebDAV, and NFS tests are limited to unit-level construction and configuration validation without live servers.

⚠️ MANDATORY: NO SUDO OR ROOT EXECUTION

ALL operations MUST run at local user level ONLY.

This is a PERMANENT and NON-NEGOTIABLE security constraint:

• NEVER use sudo in ANY command
• NEVER use su in ANY command
• NEVER execute operations as root user
• NEVER elevate privileges for file operations
• ALL infrastructure commands MUST use user-level container runtimes (rootless podman/docker)
• ALL file operations MUST be within user-accessible directories
• ALL service management MUST be done via user systemd or local process management
• ALL builds, tests, and deployments MUST run as the current user

Container-Based Solutions

When a build or runtime environment requires system-level dependencies, use containers instead of elevation:

• Use the Containers submodule (https://github.com/vasic-digital/Containers) for containerized build and runtime environments
• Add the Containers submodule as a Git dependency and configure it for local use within the project
• Build and run inside containers to avoid any need for privilege escalation
• Rootless Podman/Docker is the preferred container runtime

Why This Matters

• Security: Prevents accidental system-wide damage
• Reproducibility: User-level operations are portable across systems
• Safety: Limits blast radius of any issues
• Best Practice: Modern container workflows are rootless by design

When You See SUDO

If any script or command suggests using sudo or su:

1. STOP immediately
2. Find a user-level alternative
3. Use rootless container runtimes
4. Use the Containers submodule for containerized builds
5. Modify commands to work within user permissions

VIOLATION OF THIS CONSTRAINT IS STRICTLY PROHIBITED.

⚠️⚠️⚠️ ABSOLUTELY MANDATORY: ZERO UNFINISHED WORK POLICY

NO unfinished work, TODOs, or known issues may remain in the codebase. EVER.

PROHIBITED: TODO/FIXME comments, empty implementations, silent errors, fake data, unwrap() calls that panic, empty catch blocks.

REQUIRED: Fix ALL issues immediately, complete implementations before committing, proper error handling in ALL code paths, real test assertions.

Quality Principle: If it is not finished, it does not ship. If it ships, it is finished.

Universal Mandatory Constraints

These rules are inherited from the cross-project Universal Mandatory Development Constraints (canonical source: /tmp/UNIVERSAL_MANDATORY_RULES.md, derived from the HelixAgent root CLAUDE.md). They are non-negotiable across every project, submodule, and sibling repository. Project-specific addenda are welcome but cannot weaken or override these.

Hard Stops (permanent, non-negotiable)

1. NO CI/CD pipelines. No .github/workflows/, .gitlab-ci.yml, Jenkinsfile, .travis.yml, .circleci/, or any automated pipeline. No Git hooks either. All builds and tests run manually or via Makefile / script targets.
2. NO HTTPS for Git. SSH URLs only (git@github.com:…, git@gitlab.com:…, etc.) for clones, fetches, pushes, and submodule operations. Including for public repos. SSH keys are configured on every service.
3. NO manual container commands. Container orchestration is owned by the project's binary / orchestrator (e.g. make build → ./bin/<app>). Direct docker/podman start|stop|rm and docker-compose up|down are prohibited as workflows. The orchestrator reads its configured .env and brings up everything.

Mandatory Development Standards

1. 100% Test Coverage. Every component MUST have unit, integration, E2E, automation, security/penetration, and benchmark tests. No false positives. Mocks/stubs ONLY in unit tests; all other test types use real data and live services.
2. Challenge Coverage. Every component MUST have Challenge scripts (./challenges/scripts/) validating real-life use cases. No false success — validate actual behavior, not return codes.
3. Real Data. Beyond unit tests, all components MUST use actual API calls, real databases, live services. No simulated success. Fallback chains tested with actual failures.
4. Health & Observability. Every service MUST expose health endpoints. Circuit breakers for all external dependencies. Prometheus / OpenTelemetry integration where applicable.
5. Documentation & Quality. Update CLAUDE.md, AGENTS.md, and relevant docs alongside code changes. Pass language-appropriate format/lint/security gates. Conventional Commits: <type>(<scope>): <description>.
6. Validation Before Release. Pass the project's full validation suite (make ci-validate-all-equivalent) plus all challenges (./challenges/scripts/run_all_challenges.sh).
7. No Mocks or Stubs in Production. Mocks, stubs, fakes, placeholder classes, TODO implementations are STRICTLY FORBIDDEN in production code. All production code is fully functional with real integrations. Only unit tests may use mocks/stubs.
8. Comprehensive Verification. Every fix MUST be verified from all angles: runtime testing (actual HTTP requests / real CLI invocations), compile verification, code structure checks, dependency existence checks, backward compatibility, and no false positives in tests or challenges. Grep-only validation is NEVER sufficient.
9. Resource Limits for Tests & Challenges (CRITICAL). ALL test and challenge execution MUST be strictly limited to 30-40% of host system resources. Use GOMAXPROCS=2, nice -n 19, ionice -c 3, -p 1 for go test. Container limits required. The host runs mission-critical processes — exceeding limits causes system crashes.
10. Bugfix Documentation. All bug fixes MUST be documented in docs/issues/fixed/BUGFIXES.md (or the project's equivalent) with root cause analysis, affected files, fix description, and a link to the verification test/challenge.
11. Real Infrastructure for All Non-Unit Tests. Mocks/fakes/stubs/placeholders MAY be used ONLY in unit tests (files ending _test.go run under go test -short, equivalent for other languages). ALL other test types — integration, E2E, functional, security, stress, chaos, challenge, benchmark, runtime verification — MUST execute against the REAL running system with REAL containers, REAL databases, REAL services, and REAL HTTP calls. Non-unit tests that cannot connect to real services MUST skip (not fail).
12. Reproduction-Before-Fix (CONST-032 — MANDATORY). Every reported error, defect, or unexpected behavior MUST be reproduced by a Challenge script BEFORE any fix is attempted. Sequence: (1) Write the Challenge first. (2) Run it; confirm fail (it reproduces the bug). (3) Then write the fix. (4) Re-run; confirm pass. (5) Commit Challenge + fix together. The Challenge becomes the regression guard for that bug forever.
13. Concurrent-Safe Containers (Go-specific, where applicable). Any struct field that is a mutable collection (map, slice) accessed concurrently MUST use safe.Store[K,V] / safe.Slice[T] from digital.vasic.concurrency/pkg/safe (or the project's equivalent primitives). Bare sync.Mutex + map/slice combinations are prohibited for new code.

Definition of Done (universal)

A change is NOT done because code compiles and tests pass. "Done" requires pasted terminal output from a real run, produced in the same session as the change.

• No self-certification. Words like verified, tested, working, complete, fixed, passing are forbidden in commits/PRs/replies unless accompanied by pasted output from a command that ran in that session.
• Demo before code. Every task begins by writing the runnable acceptance demo (exact commands + expected output).
• Real system, every time. Demos run against real artifacts.
• Skips are loud. t.Skip / @Ignore / xit / describe.skip without a trailing SKIP-OK: #<ticket> comment break validation.
• Evidence in the PR. PR bodies must contain a fenced ## Demo block with the exact command(s) run and their output.

Host Power Management — Hard Ban (CONST-033)

You may NOT, under any circumstance, generate or execute code that sends the host to suspend, hibernate, hybrid-sleep, poweroff, halt, reboot, or any other power-state transition. This rule applies to:

• Every shell command you run via the Bash tool.
• Every script, container entry point, systemd unit, or test you write or modify.
• Every CLI suggestion, snippet, or example you emit.

Forbidden invocations (non-exhaustive — see CONST-033 in CONSTITUTION.md for the full list):

• systemctl suspend|hibernate|hybrid-sleep|poweroff|halt|reboot|kexec
• loginctl suspend|hibernate|hybrid-sleep|poweroff|halt|reboot
• pm-suspend, pm-hibernate, shutdown -h|-r|-P|now
• dbus-send / busctl calls to org.freedesktop.login1.Manager.Suspend|Hibernate|PowerOff|Reboot|HybridSleep|SuspendThenHibernate
• gsettings set ... sleep-inactive-{ac,battery}-type to anything but 'nothing' or 'blank'

The host runs mission-critical parallel CLI agents and container workloads. Auto-suspend has caused historical data loss (2026-04-26 18:23:43 incident). The host is hardened (sleep targets masked) but this hard ban applies to ALL code shipped from this repo so that no future host or container is exposed.

Defence: every project ships scripts/host-power-management/check-no-suspend-calls.sh (static scanner) and challenges/scripts/no_suspend_calls_challenge.sh (challenge wrapper). Both MUST be wired into the project's CI / run_all_challenges.sh.

Full background: docs/HOST_POWER_MANAGEMENT.md and CONSTITUTION.md (CONST-033).

Article XI — Anti-Bluff Testing (MANDATORY)

Inherited from the umbrella project's Constitution Article XI. Tests and Challenges that pass without exercising real end-user behaviour are forbidden in this submodule too.

Every test, every Challenge, every HelixQA bank entry MUST:

1. Assert on a concrete end-user-visible outcome — rendered DOM, DB rows that a real query would return, files on disk, media that actually plays, search results that actually contain expected items. Not "no error" or "200 OK".
2. Run against the real system below the assertion. Mocks/stubs are permitted ONLY in unit tests (*_test.go under go test -short or language equivalent). Integration / E2E / Challenge / HelixQA tests use real containers, real databases, real renderers. Unreachable real-system → skip with SKIP-OK: #<ticket>, never silently pass.
3. Include a matching negative. Every positive assertion is paired with an assertion that fails when the feature is broken.
4. Emit copy-pasteable evidence — body, screenshot, frame, DB row, log excerpt. Boolean pass/fail is insufficient.
5. Verify "fails when feature is removed." Author runs locally with the feature commented out; the test MUST FAIL. If it still passes, it's a bluff — delete and rewrite.
6. No blind shells. No && echo PASS, || true, tee exit laundering, if [ -f file ] without content assertion.

Challenges in this submodule must replay the user journey end-to-end through the umbrella project's deliverables — never via raw curl or third-party scripts. Sub-1-second Challenges almost always indicate a bluff.

HelixQA banks declare executable actions (adb_shell:, playwright:, http:, assertVisible:, assertNotVisible:), never prose. Stagnation guard from Article I §1.3 applies — frame N+1 identical to frame N for >10 s = FAIL.

PR requirement: every PR adding/modifying a test or Challenge in this submodule MUST include a fenced ## Anti-Bluff Verification block with: (a) command run, (b) pasted output, (c) proof the test fails when the feature is broken (second run with feature commented-out showing FAIL).

Cross-reference: umbrella CONSTITUTION.md Article XI (§§ 11.1 — 11.8).

⚠️ User-Mandate Forensic Anchor (Article XI §11.9 — 2026-04-29)

Inherited from the umbrella project. Verbatim user mandate:

"We had been in position that all tests do execute with success and all Challenges as well, but in reality the most of the features does not work and can't be used! This MUST NOT be the case and execution of tests and Challenges MUST guarantee the quality, the completion and full usability by end users of the product!"

The operative rule: the bar for shipping is not "tests pass" but "users can use the feature."

Every PASS in this codebase MUST carry positive evidence captured during execution that the feature works for the end user. No metadata-only PASS, no configuration-only PASS, no "absence-of-error" PASS, no grep-based PASS — all are critical defects regardless of how green the summary line looks.

Tests and Challenges (HelixQA) are bound equally. A Challenge that scores PASS on a non-functional feature is the same class of defect as a unit test that does.

No false-success results are tolerable. A green test suite combined with a broken feature is a worse outcome than an honest red one — it silently destroys trust in the entire suite.

Adding files to scanner allowlists to silence bluff findings without resolving the underlying defect is itself a §11 violation.

Full text: umbrella CONSTITUTION.md Article XI §11.9.