Add AGENTS.md project rules and align current-state documentation #6

New issue

Closed

opened 2026-07-24 19:38:12 -04:00 by JackFrostbyte · 1 comment

JackFrostbyte commented

2026-07-24 19:38:12 -04:00

Owner

Goal

    Add repository-level rules for coding agents and make the roadmap and architecture documents accurately distinguish completed work from future plans.

    ## Why

    Production Python work is the next project phase. Agents and contributors need one authoritative set of boundaries before implementation begins, and several foundation documents still describe completed metadata validation work as future work or refer to the nonexistent reserved AGENTS.md Issue #2.

    ## Scope

    - Add a root `AGENTS.md` that applies to the full monorepo unless a future nested file explicitly narrows it.

Clearly distinguish implemented behavior from plans, proposals, and roadmap intentions.
State that authoritative source text must remain distinguishable from extracted, normalized, translated, summarized, indexed, or AI-generated output.
Document the main/develop/feature-branch workflow, pull requests to develop, and HTTPS-only Git access.
State the validation and test expectations that apply before commits and pull requests.
Document legal, provenance, safety, and no-source-no-answer boundaries relevant to coding agents.
Identify directories that must not receive unreviewed, generated, downloaded, or unknown-license content.
Correct stale current-state wording and the mistaken reserved Issue #2 reference in the roadmap and architecture documentation.
Keep documentation changes narrowly tied to the new project rules and the repository's actual implemented state.
```
  ## Out of scope

  - Pipeline or runtime implementation.
```
Metadata schema redesign.
New source documents or generated data.
A broad rewrite of the roadmap or existing policies.

Changes to the Git branch model.

  ## Dependencies

  None.

  ## Acceptance criteria

  - `AGENTS.md` exists at the repository root and is internally consistent with `CONTRIBUTING.md` and existing policies.

The file explicitly covers implemented-versus-planned behavior, source authority, generated content, branch workflow, required validation, and protected data boundaries.
The roadmap no longer assigns the reserved AGENTS.md work to already-used Issue #2.
Architecture and status documentation no longer claim that the existing schemas, validator, and tests are wholly unimplemented.

No production behavior or data contract changes are introduced.

  ## Validation

  - Review the changes against `CONTRIBUTING.md`, the architecture overview, roadmap, source-acceptance policy, license policy, and AI-answer policy.

Run git diff --check.
Run the repository's existing unit-test command and confirm that all current tests still pass.

Confirm that no generated or unreviewed data was added.

  ## Suggested branch

  `feature/issue-6-agents-project-rules`

  <!-- arkive-planning-automation:2026-07-24-v3:M1-01 -->

## Goal Add repository-level rules for coding agents and make the roadmap and architecture documents accurately distinguish completed work from future plans. ## Why Production Python work is the next project phase. Agents and contributors need one authoritative set of boundaries before implementation begins, and several foundation documents still describe completed metadata validation work as future work or refer to the nonexistent reserved AGENTS.md Issue #2. ## Scope - Add a root `AGENTS.md` that applies to the full monorepo unless a future nested file explicitly narrows it. - Clearly distinguish implemented behavior from plans, proposals, and roadmap intentions. - State that authoritative source text must remain distinguishable from extracted, normalized, translated, summarized, indexed, or AI-generated output. - Document the `main`/`develop`/feature-branch workflow, pull requests to `develop`, and HTTPS-only Git access. - State the validation and test expectations that apply before commits and pull requests. - Document legal, provenance, safety, and no-source-no-answer boundaries relevant to coding agents. - Identify directories that must not receive unreviewed, generated, downloaded, or unknown-license content. - Correct stale current-state wording and the mistaken reserved Issue #2 reference in the roadmap and architecture documentation. - Keep documentation changes narrowly tied to the new project rules and the repository's actual implemented state. ## Out of scope - Pipeline or runtime implementation. - Metadata schema redesign. - New source documents or generated data. - A broad rewrite of the roadmap or existing policies. - Changes to the Git branch model. ## Dependencies None. ## Acceptance criteria - `AGENTS.md` exists at the repository root and is internally consistent with `CONTRIBUTING.md` and existing policies. - The file explicitly covers implemented-versus-planned behavior, source authority, generated content, branch workflow, required validation, and protected data boundaries. - The roadmap no longer assigns the reserved AGENTS.md work to already-used Issue #2. - Architecture and status documentation no longer claim that the existing schemas, validator, and tests are wholly unimplemented. - No production behavior or data contract changes are introduced. ## Validation - Review the changes against `CONTRIBUTING.md`, the architecture overview, roadmap, source-acceptance policy, license policy, and AI-answer policy. - Run `git diff --check`. - Run the repository's existing unit-test command and confirm that all current tests still pass. - Confirm that no generated or unreviewed data was added. ## Suggested branch `feature/issue-6-agents-project-rules`

JackFrostbyte added this to the Reproducible Acquisition & Processing v0.1 milestone

2026-07-24 19:38:12 -04:00

JackFrostbyte added the

type/design

area/governance

labels

2026-07-24 19:38:12 -04:00

JackFrostbyte added a new dependency

2026-07-24 20:10:47 -04:00

#7 Establish the Python project and development-tooling baseline

JackFrostbyte added a new dependency

2026-07-24 20:10:47 -04:00

#8 Define source-intake workflow and repository layout v0.1

JackFrostbyte referenced this issue from a pull request that will close it,

2026-07-28 01:38:31 -04:00

Add Arkive agent collaboration rules #29

JackFrostbyte closed this issue

2026-07-28 01:45:23 -04:00

JackFrostbyte referenced this issue from a commit

2026-07-28 01:45:24 -04:00

Merge pull request 'Add Arkive agent collaboration rules' (#29) from feature/issue-6-agents-project-rules into develop

JackFrostbyte commented

2026-07-28 01:46:20 -04:00

Author

Owner

Issue completed by merged PR #29.

Implemented:

Added a root AGENTS.md with model-neutral rules for coding assistants across the Arkive monorepo.
Documented human ownership, instruction security, contributor coordination, HTTPS Git workflow, validation expectations, protected repository boundaries, and review procedures.
Added Arkive-specific rules for source authority, content classes, provenance, licensing, safety-critical material, no-source-no-answer behavior, reproducibility, and source → document → chunk lineage.
Updated the README and architecture overview to acknowledge the existing metadata schema v0.1 validator, committed worked example, and seven regression tests.
Corrected the roadmap so AGENTS.md work is assigned to Issue #6 rather than the already-used Issue #2.

Verified:

git diff --check
python pipeline/validate/validate_records.py
python -m unittest discover -s tests -v — 7 tests passed
Markdown structure, scope, and links reviewed
Live PR diff reviewed against the Issue #6 acceptance criteria

No production behavior, metadata contract, policy, source data, generated data, ingestion pipeline, runtime, search, AI, translation, deployment, or unrelated implementation work was changed.

Issue #6 is complete. The repository now has the agent rules and current-state documentation needed for the next development phase. Issue #7 and Issue #8 are unblocked.

Issue completed by merged PR #29. Implemented: * Added a root `AGENTS.md` with model-neutral rules for coding assistants across the Arkive monorepo. * Documented human ownership, instruction security, contributor coordination, HTTPS Git workflow, validation expectations, protected repository boundaries, and review procedures. * Added Arkive-specific rules for source authority, content classes, provenance, licensing, safety-critical material, no-source-no-answer behavior, reproducibility, and source → document → chunk lineage. * Updated the README and architecture overview to acknowledge the existing metadata schema v0.1 validator, committed worked example, and seven regression tests. * Corrected the roadmap so AGENTS.md work is assigned to Issue #6 rather than the already-used Issue #2. Verified: * `git diff --check` * `python pipeline/validate/validate_records.py` * `python -m unittest discover -s tests -v` — 7 tests passed * Markdown structure, scope, and links reviewed * Live PR diff reviewed against the Issue #6 acceptance criteria No production behavior, metadata contract, policy, source data, generated data, ingestion pipeline, runtime, search, AI, translation, deployment, or unrelated implementation work was changed. Issue #6 is complete. The repository now has the agent rules and current-state documentation needed for the next development phase. Issue #7 and Issue #8 are unblocked.