Barkly Broadcast
Functional Requirements Specification (FRS)
Document Version: 0.1 Status: Draft for implementation Project: Barkly Labs System Type: Automated development activity reporting and publishing system Initial Runtime: Linux VPS alongside the existing Barkly Labs web server Initial Publishing Destination: Barkly Labs website Future Destination: Social media platforms through authorized APIs Publication Mode: Automatic, subject to mandatory validation
1. Purpose
Barkly Broadcast is an automated development-to-publication system designed to communicate verified progress across Barkly Labs projects.
The system shall observe development activity, collect supporting evidence, generate project-aware updates, validate their factual claims, and publish qualifying updates to configured destinations without requiring the developer to manually write each post.
The system shall reduce the administrative and promotional work required to maintain public project updates while preserving accuracy, transparency, security, and the actual development status of each project.
1.1 Mission
Barkly Broadcast exists to make communicating development progress easier for developers, particularly those who have limited time, energy, or capacity for repetitive administrative work.
1.2 Design principle
Automate communication, not truth.
The system shall never interpret the existence of development activity as proof of project readiness, successful testing, or completed functionality.
2. Scope
2.1 Included in the initial release
GitHub repository monitoring.
GitHub webhook ingestion.
Scheduled repository reconciliation.
Development activity and evidence collection.
Project-specific configuration.
Automated post generation using an LLM.
Evidence-based claim validation.
Project status enforcement.
Duplicate-event and duplicate-publication prevention.
Automatic website publishing.
Persistent publication records.
Operational logging and failure handling.
Background service operation on the existing VPS.
2.2 Planned extensions
Social media publishing through official platform APIs.
Additional repository providers.
Administrative dashboard.
Additional content formats, including release summaries and development digests.
Configurable publishing schedules and frequency limits.
Optional notifications about rejected posts and service failures.
2.3 Out of scope for v0.1
Autonomous modification of project source code.
Autonomous merging of pull requests.
Autonomous deployment of application code.
Generating fabricated test results or benchmarks.
Publishing private repository content without explicit authorization.
Making project completion or quality decisions solely through an LLM.
Circumventing social platform restrictions or rate limits.
3. System context
Barkly Broadcast shall operate as a separate background service alongside the existing Barkly Labs website infrastructure.
The currently known website environment uses Nginx and Astro on a Linux VPS. The precise build and deployment mechanism must be inspected before implementing website publication.
3.1 Logical components
Event Ingestion: Receives GitHub webhooks and scheduled scan results.
Evidence Collector: Retrieves relevant public development activity and test evidence.
Project Registry: Stores project identity, status, repository mappings, and publication policies.
Evidence Ledger: Records the source and timestamp of information supporting a potential post.
Content Generator: Produces a project-aware draft using an LLM.
Validation Engine: Checks claims, evidence, privacy, status, and publishing rules.
Publication Manager: Sends validated posts to configured destinations.
Persistence Layer: Stores events, drafts, evidence references, publication attempts, and outcomes.
Monitoring and Recovery: Records failures, retries recoverable operations, and supports service recovery.
4. Functional requirements
Priority levels:
MUST: Required for the initial release.
SHOULD: Strongly recommended.
LATER: Planned extension.
FR-001 — Project registration
Priority: MUST
The system shall maintain a registry of projects eligible for development reporting.
Each project record shall support:
Unique project identifier.
Display name.
Public repository URL or repository identifier.
Short project description.
Public development status.
Enabled evidence sources.
Enabled publication destinations.
Publishing frequency limits.
Project-specific writing instructions.
Automatic publishing enablement.
Project-specific claim restrictions.
Each project shall be independently configurable and disableable without stopping other projects.
Acceptance criteria:
A registered project can be monitored and published independently.
An unknown repository cannot automatically become an authorized publishing project.
Disabling a project prevents new publication jobs for that project.
Missing project configuration defaults to no publication.
FR-002 — Development event ingestion
Priority: MUST
The system shall ingest supported GitHub webhook events and scheduled repository scan results.
Initially supported events should include:
Pushes to configured branches.
Pull requests being merged.
Releases being published, when release announcements are enabled.
Completed CI workflows and their actual conclusions, when the workflow is accessible.
The system shall validate webhook signatures and reject invalid requests.
It shall record the provider, repository, event identifier, event type, timestamp, and processing state.
Acceptance criteria:
Valid configured events enter the processing pipeline.
Invalid signatures are rejected.
Repeated delivery of the same event does not create duplicate processing or posts.
Unconfigured repositories cannot trigger publication.
FR-003 — Scheduled reconciliation
Priority: MUST
The system shall periodically inspect configured repositories to recover from missed, delayed, or failed webhook deliveries.
The reconciliation process shall:
Retrieve activity since the previous successful checkpoint.
Detect previously unseen events.
Avoid duplicating previously processed activity.
Persist the checkpoint only after successful processing.
Retry recoverable failures without discarding unprocessed work.
The reconciliation interval shall be configurable.
FR-004 — Evidence collection
Priority: MUST
The system shall collect verifiable information supporting development updates.
Evidence may include:
Commit identifiers and public commit summaries.
Merged pull request titles and public descriptions.
Public release metadata.
Actual CI workflow results.
Explicitly configured, machine-readable test reports.
Public documentation changes.
Public project metadata.
Every evidence record shall include its source, associated project, relevant identifier or URL, observation time, and available status information.
The system shall distinguish between evidence that exists, evidence that was retrieved successfully, and evidence that supports a particular claim.
Acceptance criteria:
Every material factual claim in a generated post references supporting evidence.
An inaccessible test report cannot be treated as a successful test.
A commit message containing the word “fixed” does not independently prove that a bug was fixed.
Missing evidence is recorded as unknown, not as success.
FR-005 — Evidence ledger
Priority: MUST
The system shall maintain a persistent record of evidence used to generate and validate posts.
Each post shall retain references to its supporting evidence after publication.
The system shall support tracing a published statement back to the relevant development event or test result.
Evidence records shall not be silently rewritten to make a previous post appear better supported.
FR-006 — Content generation
Priority: MUST
The system shall generate human-readable development updates using a configured LLM.
Generated content shall be informed by:
The project's registered description and public status.
Newly collected development activity.
Relevant evidence records.
Project-specific tone and terminology.
Publication destination constraints.
Required disclosure language.
The generator may summarize, reorganize, and explain supported facts. It shall not invent implementation details, test results, user feedback, performance improvements, or project milestones.
The generator shall produce structured output containing at least:
Proposed title or opening.
Proposed post body.
Project identifier.
Intended destinations.
Evidence references.
Claims requiring validation.
Draft creation timestamp.
Acceptance criteria:
The generated post accurately reflects the evidence supplied to the generator.
A generation failure does not cause an empty or fabricated post to be published.
Generated output is treated as untrusted until validated.
FR-007 — Claim validation
Priority: MUST
The system shall validate proposed publication content before it can be published.
Validation shall combine deterministic rules with structured claim-to-evidence checks. LLM evaluation may assist with review but shall not override mandatory rules.
The system shall reject or hold a post if:
A material factual claim has no supporting evidence.
A claim contradicts available evidence.
A test or benchmark result cannot be verified.
The post claims completion without authorized status evidence.
The post contains restricted information.
The post violates project or destination policies.
The validation process fails or returns an indeterminate result.
Claims shall be evaluated individually where practical. Unsupported claims may be removed and the remaining post revalidated; otherwise, the entire post shall be held.
Acceptance criteria:
A fabricated test result is not published.
An unsupported “fixed” or “completed” claim is rejected or removed.
A validation error fails closed.
Every rejection records a reason and relevant evidence references.
FR-008 — Project status enforcement
Priority: MUST
Every project shall have an explicit publication status.
Supported statuses shall include:
in_development
beta
released
maintenance
paused
archived
A newly registered project shall default to in_development.
Status transitions shall be governed by explicit project policy and authoritative evidence or an authorized configuration change.
A commit, merged pull request, successful test suite, generated post, or elapsed period of time shall not independently establish that a project is ready for general use.
The system shall include appropriate in-development disclosure when a project is unfinished.
Acceptance criteria:
CYN-X remains in_development until its status is explicitly and validly changed.
Passing tests does not automatically mark a project as released.
A post cannot describe an unfinished project as production-ready merely because the LLM chooses that wording.
Status changes are recorded with their source, timestamp, and authorization or evidence.
FR-009 — Automatic publication
Priority: MUST
The system shall automatically publish validated posts to enabled destinations.
For v0.1, the initial destination shall be the Barkly Labs website.
The implementation shall integrate with the existing website deployment workflow after that workflow has been inspected and confirmed.
Possible mechanisms include generating content files for an existing build-and-deploy pipeline or integrating with an existing authenticated publishing interface. The implementation shall select one based on the actual deployment architecture.
The system shall not expose an unrestricted public publishing endpoint.
Acceptance criteria:
A validated post can be published without manual drafting or approval.
A failed validation prevents publication.
A disabled destination receives no new posts.
Website publication failures are recorded and recoverable.
Existing website pages and deployment behavior remain intact.
FR-010 — Publication state tracking
Priority: MUST
Each publication job shall maintain a persistent state, including:
queued
generating
validating
ready
publishing
published
retry_pending
rejected
failed
The system shall record timestamps, destination, content version or hash, evidence references, attempt count, external publication identifier where available, and error details.
A job shall not be marked published until the destination reports success or the system independently confirms publication.
FR-011 — Duplicate prevention and idempotency
Priority: MUST
The system shall prevent duplicate posts caused by webhook retries, scheduled scans, service restarts, or publication retries.
It shall use stable event identifiers and publication idempotency keys where supported.
If a destination does not support idempotent publication, the system shall check the publication ledger and reconcile uncertain outcomes before retrying.
FR-012 — Retry and failure recovery
Priority: MUST
The system shall retry transient failures using configurable backoff and a maximum retry policy.
Permanent errors, repeated failures, and ambiguous publication outcomes shall be logged and isolated for recovery.
A worker restart shall not erase pending jobs or cause previously published posts to be published again.
Failed jobs shall remain inspectable.
FR-013 — Website content presentation
Priority: MUST
The initial website integration shall provide a development update feed or equivalent public presentation within the existing Barkly Labs website.
Each post shall support:
Project name.
Publication date.
Title and body.
Project status or development disclosure.
Relevant public source links where appropriate.
The website integration shall follow the existing Astro site's styling and accessibility conventions.
The implementation shall preserve valid HTML, responsive layout, semantic structure, and readable content.
FR-014 — Social media publishing
Priority: LATER
The system shall support separate publishing adapters for selected social platforms.
Each adapter shall use authorized official APIs and comply with applicable platform rules.
Each platform shall have independent configuration, credentials, rate limits, content formatting, and publication records.
Failure on one platform shall not erase a successful publication to another destination.
Social publishing shall remain disabled until credentials, permissions, and platform integration have been configured and tested.
FR-015 — Project-specific writing rules
Priority: MUST
The system shall support project-specific language, disclosures, and content restrictions.
Examples include:
CYN-X must be described as under development while that status remains active.
A post may describe regression testing only when supporting evidence establishes that the work occurred.
A test fix shall not be represented as a fully resolved regression without supporting test evidence.
A release announcement shall require an actual release and permission under project policy.
Private or security-sensitive implementation details shall not be published.
FR-016 — Publication frequency and grouping
Priority: SHOULD
The system should group related development events into meaningful updates instead of publishing an individual post for every minor commit.
The system shall support configurable limits on publication frequency and post size.
It should avoid low-value duplicate content and excessive publishing.
Rate limiting shall not silently discard important events. Events that cannot immediately be published shall remain queued or be recorded as intentionally suppressed under policy.
FR-017 — Configuration management
Priority: MUST
The system shall maintain explicit configuration for projects, evidence sources, generation settings, validation rules, and publication destinations.
Configuration shall be validated before activation.
Missing or invalid configuration shall disable the affected capability rather than bypass safeguards.
Secrets shall be supplied through a protected secret-management mechanism or restricted environment configuration, never embedded in source code or generated posts.
FR-018 — Logging and operational visibility
Priority: MUST
The system shall produce structured logs for:
Service startup and shutdown.
Event receipt and validation.
Evidence collection.
Draft generation.
Claim validation.
Publication attempts and outcomes.
Retry scheduling.
Rejections and failures.
Configuration errors.
Logs shall support troubleshooting without exposing credentials, secret values, or unnecessary private content.
The system should provide a way to determine why a particular post was or was not published.
FR-019 — Service operation
Priority: MUST
Barkly Broadcast shall run independently of the main Nginx/Astro web service.
The service shall:
Start automatically after system boot.
Restart after unexpected process failure.
Run under a dedicated restricted service account.
Use configurable CPU and memory limits.
Persist essential state outside ephemeral process memory.
Support graceful shutdown.
Avoid interfering with the existing website service.
A failure of Barkly Broadcast shall not directly stop the website.
FR-020 — Security and privacy
Priority: MUST
The system shall:
Verify webhook signatures.
Accept events only from configured sources.
Restrict file-system and database permissions.
Protect API credentials.
Sanitize generated HTML and externally supplied content.
Prevent unauthorized publication requests.
Avoid exposing internal administration endpoints publicly.
Avoid publishing secrets, private logs, or sensitive personal information.
Keep an audit trail of configuration changes and publication outcomes.
FR-021 — Data retention and backups
Priority: MUST
The system shall persist the evidence ledger, job queue, project configuration, and publication history in durable storage.
It shall support backups and recovery of critical state.
Retention policies shall be configurable, with enough history preserved to audit published content and investigate duplicate or incorrect posts.
Secrets shall not be included in ordinary database backups unless an explicitly protected secret-backup procedure is used.
FR-022 — Testing and verification
Priority: MUST
The implementation shall include automated tests for core behavior.
At minimum, tests shall cover:
Valid and invalid webhook signatures.
Duplicate event processing.
Evidence-to-claim validation.
Project status enforcement.
Missing or contradictory evidence.
LLM failures and malformed output.
Privacy and content restrictions.
Duplicate publication prevention.
Transient destination errors and retry behavior.
Worker restarts and persistence.
Website publishing integration.
Configuration failures and fail-closed behavior.
A staging or test mode shall permit end-to-end verification without publishing to the live website.
5. Initial project configuration
The initial deployment should register projects explicitly rather than monitor every repository accessible to the service.
Illustrative configuration:
projects:
- id: cyn-x
display_name: CYN-X
public_status: in_development
enabled: true
sources:
commits: true
merged_pull_requests: true
ci_results: true
releases: true
publication:
website: true
social: false
automatic: true
rules:
require_evidence_for_claims: true
require_test_evidence_for_test_claims: true
allow_release_announcements: false
disclose_development_status: true
This is a proposed schema, not an existing configuration file. Repository identifiers, branch policies, evidence sources, and actual test-report availability must be confirmed before deployment.
6. High-level workflow
A GitHub event arrives or a scheduled scan detects new activity.
The service authenticates and deduplicates the event.
Relevant development evidence is collected and persisted.
The service determines whether there is enough meaningful new activity to justify an update.
The LLM generates a structured draft from the evidence.
The validation engine checks claims, project status, privacy, and destination policy.
Invalid or uncertain content is rejected or held.
Valid content enters the publication queue.
The destination receives the post.
The service records the outcome and reconciles uncertain failures.
Monitoring makes failures and rejected posts inspectable.
7. Non-functional requirements
Although this document focuses on functionality, the initial implementation shall also meet these operational expectations:
Reliability: Persistent jobs and recoverable failures.
Isolation: The publishing worker shall not be a single point of failure for the website.
Efficiency: Configurable resource limits appropriate for the existing VPS.
Security: Least-privilege execution and protected credentials.
Maintainability: Modular event providers, content generation, validation, and destination adapters.
Traceability: Published factual claims can be traced to supporting evidence.
Accessibility: Public posts remain readable and accessible on the website.
Portability: Configuration and core logic should not depend unnecessarily on a specific LLM provider.
No unverified uptime, performance, or scalability guarantee is implied by this specification.
8. Acceptance criteria for v0.1
The first release is considered functionally complete when all of the following are demonstrated:
The worker runs as a separate service on the VPS.
A configured GitHub repository is monitored through webhooks and scheduled reconciliation.
New development activity is stored with traceable evidence.
A post is generated from real activity.
Unsupported claims and fabricated test results are rejected.
CYN-X remains marked as in development unless an authorized status change is made.
A valid post is automatically published to the Barkly Labs website.
Duplicate events do not produce duplicate posts.
Failed publication attempts can recover without losing job state.
Service restarts preserve pending work and publication history.
Website behavior remains intact when the worker is stopped or restarted.
Automated tests cover the principal security, validation, and recovery requirements.
Social media publishing is not required for v0.1.
9. Implementation dependencies and unresolved decisions
The following must be verified before implementation:
The actual GitHub repository and deployment workflow for the Astro site.
Whether /srv/barkly/current is a source checkout, release directory, or built artifact.
Available VPS CPU, memory, disk, and existing service conventions.
Which GitHub events and test reports are accessible.
Whether an LLM will be called through a remote API or an existing reachable model endpoint.
The preferred website publication mechanism based on the current deployment.
The public feed route and design conventions.
Backup and log-retention requirements.
These are deployment discovery tasks, not reasons to weaken the functional requirements.
10. Future extensions
Potential future versions may add:
Social publishing adapters.
A public development changelog.
An administrative dashboard.
Per-project publication calendars.
Image generation for project updates.
Release-note compilation.
Community engagement analytics.
More repository providers.
Contributor attribution and configurable author credits.
Content correction and retraction workflows.
Any future feature must preserve the same core principles of evidence-based communication, explicit project status, secure operation, and automatic publication only after validation.
End of document — Barkly Broadcast FRS v0.1