diff --git a/AGENTS.md b/AGENTS.md index 40e43c8..344fa3d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,6 +49,27 @@ The scripts call the shared bootstrap path automatically. A fresh agent should r - If a task is connected to an external repository, determine the active target-pack from `STATE.md` or an explicit `targets/.md` first. - If a fresh agent cannot continue from committed docs plus local runtime state, continuity is broken. +## Role Boundary: Orchestrator vs Executor + +The orchestrator does not perform execution work directly. It: + +- creates TASK files and dispatches them to the executor; +- reviews artifacts produced by the executor and auditor; +- drives issues and tasks to closure artifacts (PR, decision, TASK, dispute). + +If the orchestrator finds itself writing code, running audits, or generating content that belongs to a TASK — stop, create the TASK, and delegate. + +## GitHub Issues on Target Projects + +When working with GitHub Issues on a target repository: + +- **Sign every comment** with your role and model name at the bottom of the comment: + `— Роль (Модель)` — example: `— Координатор (Claude Sonnet 4.6)` +- **Use the language specified in the active target-pack** (`ISSUE_LANGUAGE` field). If not set, default to the language of the target project's README. +- If a rule is only proposed or exists only as a local draft, describe it in target-project issues as `proposed` / `pending canon`, not as accepted canon. +- **Every issue must result in a concrete artifact** before it can be closed: a PR, a new issue, a TASK file, a roadmap entry, or an explicit documented decision not to act. +- Do not leave issues in open discussion state indefinitely — every round of comments should advance the issue toward its next artifact. + ## Legacy Boundary Documents outside `multiagentsystem` may be read as reference-only sources, but not treated as live canon without an explicit decision. diff --git a/OPERATIONS.md b/OPERATIONS.md index 5a24d6c..174aea7 100644 --- a/OPERATIONS.md +++ b/OPERATIONS.md @@ -269,3 +269,27 @@ To recover a file from quarantine: ## GitHub Workflow Use GitHub issues for framework tasks and disputes, PRs for changes, and Actions for hygiene checks. GitHub Pages is optional and must be requested explicitly before implementation. + +### Target Project GitHub Issues + +When a target-pack points to an external GitHub repository, the orchestrator manages issues there with the same artifact discipline: + +- Check existing issues before creating new ones — avoid duplicates. +- Sign every comment: `— Роль (Модель)`. +- Write in the language defined by `ISSUE_LANGUAGE` in the target-pack (fallback: README language). +- If a rule has not completed canonical promotion yet, label it as `proposed` / `pending canon` in the issue thread instead of presenting it as accepted framework canon. +- Each issue round must advance to a next artifact or explicit decision. +- Before creating issues: read open issues list first. + +### Issue → Artifact Lifecycle + +``` +open issue + → discuss (each round: add comment + sign) + → agree on next artifact type (PR / new issue / TASK / decision) + → produce artifact + → link artifact in issue + → close issue +``` + +An issue with only comments and no linked artifact is incomplete. diff --git a/ROADMAP.md b/ROADMAP.md index bee1f6f..d10b0b8 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -19,6 +19,7 @@ Make `multiagentsystem` the single working canon for multi-agent coordination an - Introduce an explicit lifecycle for `canonical / derived / legacy` documents. - Add optional GitHub Pages management dashboard only after an explicit issue. - Add richer recovery diagnostics for stale local sessions. +- Track accepted process promotions through versioned decisions; current reference: `decisions/DECISION-agent-github-comment-rules.md`. ## P2 diff --git a/decisions/DECISION-agent-github-comment-rules.md b/decisions/DECISION-agent-github-comment-rules.md new file mode 100644 index 0000000..9b5ad90 --- /dev/null +++ b/decisions/DECISION-agent-github-comment-rules.md @@ -0,0 +1,91 @@ +# DECISION: Agent GitHub Comment Rules + +## Status + +`accepted` + +## Date + +2026-04-30 + +## Context + +`TASK-007` requires canonicalizing three process rules that currently exist only as local draft edits: + +- agents sign target-project GitHub issue comments with `— Роль (Модель)`; +- the comment language follows `ISSUE_LANGUAGE` from the active target-pack; +- the orchestrator creates and delegates `TASK` work instead of performing executor work directly. + +Issue [#12](https://github.com/Stolyarovmn/multiagentsystem/issues/12) establishes the recoverability problem around unsigned comments and language drift. Its follow-up comment adds one more requirement: agents must not describe a merely proposed or locally drafted rule as accepted canon in target-project issues. + +Issue [#11](https://github.com/Stolyarovmn/multiagentsystem/issues/11) is adjacent: issue threads should move toward an explicit next artifact instead of ending as chat-like discussion. This decision adopts that discipline for target-project issue handling, without trying to resolve the broader proposal scope of `#11`. + +Per `EVOLUTION.md`, local edits alone do not make canon. The rule needs an explicit decision artifact before the drafted text in `AGENTS.md` and `OPERATIONS.md` can be treated as canonical. + +## Options considered + +### Option A + +Keep the rules as local session practice only. + +Pros: +- no doc churn; +- no additional canon surface. + +Cons: +- fresh agents cannot recover the rule set from canon; +- target-project issue comments remain ambiguous about authorship and language; +- local drafts could still be misrepresented as accepted canon. + +### Option B + +Canonicalize only the comment-signature and language rules. + +Pros: +- solves the most visible target-project issue ambiguity; +- smaller documentation change. + +Cons: +- leaves the orchestrator/executor boundary implicit; +- keeps a known failure mode where the orchestrator bypasses task delegation; +- does not record the `pending canon` caution for issue comments. + +### Option C + +Canonicalize all three rules together and place them in both `AGENTS.md` and `OPERATIONS.md`, with a narrow operational note about `pending canon`. + +Pros: +- keeps role boundaries and issue behavior recoverable from canon; +- aligns policy (`AGENTS.md`) with workflow guidance (`OPERATIONS.md`); +- prevents target-project comments from overstating proposal status. + +Cons: +- slightly increases canon surface; +- overlaps with the broader issue-discipline topic tracked separately in `#11`. + +## Decision + +Adopt Option C. + +The canon now treats the following as accepted framework rules: + +1. Agents commenting in target-project GitHub issues sign comments with `— Роль (Модель)`. +2. Comment language follows `ISSUE_LANGUAGE` in the active target-pack; if that field is absent, fall back to the target project's README language. +3. The orchestrator creates `TASK` files, delegates execution, and does not directly perform executor work. +4. When a rule has not yet completed canonical promotion, target-project issue comments must describe it as `proposed` / `pending canon`, not as already accepted canon. +5. Target-project issue discussion must move toward a concrete next artifact or explicit decision, consistent with the narrower scope of this decision. + +## Consequences + +- `AGENTS.md` carries the normative boundary and target-project issue comment rules. +- `OPERATIONS.md` carries the operational workflow for target-project issue handling. +- `decisions/README.md` indexes this decision. +- `auditor_logs/events.log` records the local artifact trail for the promotion step requested by `TASK-007`. +- Broader framework-wide issue-shaping language proposed in issue `#11` remains a separate follow-up unless accepted independently. + +## Related + +- Source review: none +- Proposal issue: [#12](https://github.com/Stolyarovmn/multiagentsystem/issues/12) +- Related issue: [#11](https://github.com/Stolyarovmn/multiagentsystem/issues/11) +- Implementation PR: [#13](https://github.com/Stolyarovmn/multiagentsystem/pull/13) diff --git a/decisions/README.md b/decisions/README.md index 11cd4d3..dda6d86 100644 --- a/decisions/README.md +++ b/decisions/README.md @@ -16,4 +16,4 @@ One file per design decision. Both accepted and rejected decisions are recorded | Decision | Status | Summary | |----------|--------|---------| -| *(none yet --- first decisions pending)* | | | +| `DECISION-agent-github-comment-rules.md` | `accepted` | Canonicalizes target-project issue signatures, `ISSUE_LANGUAGE`, orchestrator delegation boundary, and `pending canon` disclosure. |